Working with Xcode Projects#

Noctule 2.0 provides support for Xcode projects. You can open, build and run applications based on Xcode projects.

Requirements#

macOS is required
That’s because Apple’s Xcode tooling and support is only available on a Mac.
Because Noctule integrates with JetBrains’ remote development it possible to launch the backend of the IDE on a Mac and the frontend on a Linux or Windows machine.

xcode-build-server has to be installed.
xcode-build-server is a program to allow SourceKit LSP to work with Xcode projects.
Install it with brew install xcode-build-server or refer to the installation instructions for further details and alternative ways to install it.

Choose Scheme and Destination#

As with Xcode, you need to choose scheme and destination to work with the Xcode project.

Xcode command line tools don’t work without a scheme and many operations either don’t work without a destination or provide unexpected results.

Execute Tools → Noctule → Initialize xcode-build-server after changing scheme or destination. It’s planned to do this automatically in an update of Noctule. For now, this is only done if SourceKit LSP is launched without an existing buildServer.json file.

Setting up an Xcode Project#

Open a directory containing *.xcworkspace or *.xcodeproj directories.
This will import and set up a new IDE project based on the Xcode project.

If no JetBrains project data (directory .idea) is found, then a new project is created based on the Xcode workspace or project. If more than one *.xcworkspace or *.xcodeproj directory is found, then Noctule will let you choose the directory to import. In most cases, the Xcode workspace *.xcworkspace is to be preferred.

Building an Xcode Project#

The usual build actions like Build → Build Project and Build → Rebuild Project work as usual.

If these actions don’t seem to build your Xcode project, please verify that “Preferences… → Build, Execution, Deployment → Noctule → Run swift build or xcodebuild for project build tasks is enabled in your project. This setting is automatically enabled for projects imported from an Xcode project.

Noctule provides additional build menu items like “Build Xcode workspace …, scheme …” based on the focused file. This is only available if a scheme is selected in the main toolbar or at Tools → Noctule → Choose Xcode scheme.

If you would like to build something other than the current scheme, then use an Xcode build run configuration.

Run Configurations#

Noctule provides two types of run configurations for Xcode:

• Xcode Simulator
• Xcode Build

Common Settings#

Some settings are the same for the different types of Xcode run configurations. They are only documented once here.

Toolchain

The toolchain to use for building and deployment. This has to be an Xcode toolchain. By default, the project-wide toolchain is used.

Project or workspace

The Xcode project or workspace to use. The other settings like “scheme” depend on this setting and are updated to only show what’s available in the selected Xcode workspace or project.

Scheme or target

The scheme or target to build. Xcode workspaces only support schemes. For Xcode projects, this box will show the available scheme and targets in the same box.

Configuration

Override the configuration (e.g. “Debug”) if you don’t want to use the default specified by the selected scheme or target.

Destination

Optional setting to define the destination. The button on the right of this control lets you choose one of the destinations available in the workspace or project. You can enter your own value as destination instead if you like.

Xcode Build Settings

These settings configure the commandline of the executed xcodebuild commands.

• Quiet build
• Skip package updates
• Skip package plugin validation
• Skip package signature validation
• Skip macro validation
• Additional parameters let you configure your own, additional parameters for xcodebuild commands

Xcode Simulator Run Configuration#

Build and deploy an application to a simulator.

Settings#

The settings are available for Xcode simulator run configurations in addition to the common settings above.

Simulator Settings: Application arguments

Arguments passed to the built application when it’s launched inside the simulator.

Simulator Settings: Application environment

Environment variables, which are made available to the application launched inside the simulator.

Before launch

By default, the application to deploy is built before it’s deployed into the simulator. Remove the build step in this section to deploy what’s already on disk, without build it again.

Xcode Build Run Configuration#

Execute xcodebuild in the selected Xcode workspace or project. This is especially helpful in compound run configurations or as “Before launch” build step of other run configurations in your project.

Settings#

The settings are available for Xcode simulator run configurations in addition to the common settings above.

Program arguments

Additional arguments that are passed to the xcodebuild command.

Environment variables

Additional environment variables that are passed to the xcodebuild command.

Simulators#

Noctule’s tool window “Xcode simulators” helps to manage Xcode simulators on your system.

Grouping#

To help working with simulators, the tool window displays a tree with configurable grouping.

State

Groups simulators by state, e.g. “Booted” and “Shutdown”.

Platform

Groups simulators by platform, e.g. “iOS” or “tvOS”.

Family

Groups simulators by family, which is the platform with a version, e.g. “iOS 26.5”.

View Options#

Show unavailable devices

If enabled, unavailable simulator devices are shown in red. If turned off, then such simulators will be hidden in the tree.

Context Actions#

Several actions are available in the context menu of a simulator item.

In remote development mode, these actions are executed on the backend.
For example, if you would like to see the output of a simulator, you need to use screen sharing or similar solutions.

Boot Simulator

Boot the selected simulator. This item is only enabled if the simulator is not yet booted.

Shutdown Simulator

Shut down the selected simulator. This item is only enabled if the simulator is running.

Rename Simulator

Rename the selected simulator. Displays a text input to rename the simulator.

Show Simulator Window

Open and focus the window of the selected simulator. This item is only available if the simulator is running.

Erase Simulator

Wipe the selected simulator. This basically resets the simulator but does not remove it from the system.

Delete Simulator

Delete the selected simulator. This removes the simulator from the system.

Additional Features#

Xcode File Support#

Noctule supports additional Xcode file types.

Xcode project files project.pbxproj are supported with highlighting, folding and basic navigation inside the file. This is mostly useful for inspecting such files, but not intended to make changes to the file.

Text-based and XML-based PList files are recognized and highlighted.

Xcode Project View#

Noctule adds an additional project view “Xcode workspace” to the “Project” tool window of your IDE. This view visualizes the structure of an Xcode workspace or project similar to Xcode.

The dropdown of the “Project” tool window has a new item to activate this view.

This feature may change or be merged into the default project view in a future version.

Troubleshooting#

In general, make sure that Noctule knows about the Xcode workspace or project.

You can verify this at Preferences… → Build, Execution, Deployment → Noctule → Directory Settings. Your Xcode project or workspace should be listed on this page.

I Can’t Build My Xcode Project#

The Xcode setup may be incomplete, for example, if Xcode needs user confirmation for configured plugins.

Open the same workspace or project in Xcode and build it there with the same scheme and destination.

If Xcode builds the project without prompting for input, then building in Noctule should work via the Build menu and with Xcode build run configurations.

Navigation or Editor Features Don’t Work#

The LSP server may be out-of-sync with the Xcode project. With Xcode projects, the server cannot build on its own.

1. SourceKit LSP server. Make sure that a SourceKit LSP server is running by clicking the Noctule bat icon in the status bar. If there already is a server running, proceed with the next step.
2. Build your Xcode workspace or project. Make sure that the correct Xcode scheme and destination is selected.
   Then build your Xcode workspace or project with Build → Build project or Build → Build Xcode …. If navigation does not yet work, proceed with the next step.
3. xcode-build-server setup. Recreate the setup of xcode-build-server. Then reconfigure xcode-build-server with Tools → Noctule → Initialize xcode-build-server. This action should show modal progress while executing xcodebuild and the setup command of xcode-build-server. Wait until the steps are finished and try again.
4. Contact support. If the editor of Swift files still does not work as expected, please reach out to us or submit a bug report.

Loading Destinations Takes Very Long#

Loading destinations for Xcode workspaces or projects with many schemes can take several minutes. The destinations are cached for the next time the project is opened.

Improvements are planned
Handling of destinations will be improved in future updates of Noctule.

First, make sure that your Xcode project is fully working. For example, broken Xcode project data can prevent Xcode commandline tools to list the available destinations in a reasonable time.

Make sure that no other Xcode project or workspace is shown in Noctule’s settings at Preferences… → Build, Execution, Deployment → Noctule → Directory Settings. If another item is shown, select it and click the “-” button to ignore it.