A script for generating an Xcode project for the Swift repo, that sits on top of an existing Ninja build. This has a few advantages over CMake's Xcode generator (using build-script --xcode):
- Fast to regenerate (less than a second)
- Native Swift targets for ASTGen/SwiftCompilerSources + Standard Library
- Better file organization (by path rather than by target)
- Much fewer targets, easier to manage
This script is primarily focussed on providing a good editor experience for working on the Swift project; it is not designed to produce compiled products or run tests, that should be done with ninja and build-script. It can however be used to debug executables produced by the Ninja build.
You can run using either utils/generate-xcode or the swift-xcodegen script in this directory; the former is just a convenience for the latter. The basic invocation is:
./swift-xcodegen <build dir>where <build dir> is the path to the build directory e.g build/Ninja-RelWithDebInfoAssert. This will by default create a Swift.xcodeproj in the parent directory (next to the build directory). Projects for LLVM, LLDB, and Clang may also be created by passing --llvm, --lldb, and --clang respectively. Workspaces of useful combinations will also be created (e.g Swift+LLVM, Clang+LLVM).
For the full set of options, see the Command usage below.
An ALL meta-target is created that depends on all the targets in the given project or workspace. A scheme for this target is automatically generated too (and automatic scheme generation is disabled). You can manually add individual schemes for targets you're interested in. Note however that Clang targets do not currently have dependency information.
By default, schemes are added for executable products, which can be used for debugging in Xcode. These use ninja to build the product before running. If using a separate build for debugging, you can specify it with --runnable-build-dir.
By default, C/C++ standard library + runtime files are added to the project. Swift targets may be added by passing --stdlib-swift, which adds a target for the core standard library as well as auxiliary libraries (e.g CxxStdlib, Backtracing, Concurrency). This requires using Xcode with an up-to-date development snapshot, since the standard library expects to be built using the just-built compiler.
USAGE: swift-xcodegen [<options>] <build-dir>
ARGUMENTS:
<build-dir> The path to the Ninja build directory to generate for
LLVM PROJECTS:
--clang/--no-clang Generate an xcodeproj for Clang (default: --no-clang)
--clang-tools-extra/--no-clang-tools-extra
When generating a project for Clang, whether to include clang-tools-extra (default: --clang-tools-extra)
--lldb/--no-lldb Generate an xcodeproj for LLDB (default: --no-lldb)
--llvm/--no-llvm Generate an xcodeproj for LLVM (default: --no-llvm)
SWIFT TARGETS:
--swift-targets/--no-swift-targets
Generate targets for Swift files, e.g ASTGen, SwiftCompilerSources. Note
this by default excludes the standard library, see '--stdlib-swift'. (default: --swift-targets)
--swift-dependencies/--no-swift-dependencies
When generating Swift targets, add dependencies (e.g swift-syntax) to the
generated project. This makes build times slower, but improves syntax
highlighting for targets that depend on them. (default: --swift-dependencies)
RUNNABLE TARGETS:
--runnable-build-dir <runnable-build-dir>
If specified, runnable targets will use this build directory. Useful for
configurations where a separate debug build directory is used.
--runnable-targets/--no-runnable-targets
Whether to add runnable targets for e.g swift-frontend. This is useful
for debugging in Xcode. (default: --runnable-targets)
--build-runnable-targets/--no-build-runnable-targets
If runnable targets are enabled, whether to add a build action for them.
If false, they will be added as freestanding schemes. (default: --build-runnable-targets)
PROJECT CONFIGURATION:
--compiler-libs/--no-compiler-libs
Generate targets for compiler libraries (default: --compiler-libs)
--compiler-tools/--no-compiler-tools
Generate targets for compiler tools (default: --compiler-tools)
--docs/--no-docs Add doc groups to the generated projects (default: --docs)
--stdlib, --stdlib-cxx/--no-stdlib, --no-stdlib-cxx
Generate a target for C/C++ files in the standard library (default: --stdlib)
--stdlib-swift/--no-stdlib-swift
Generate targets for Swift files in the standard library. This requires
using Xcode with a main development Swift snapshot, and as such is
disabled by default.
A development snapshot is necessary to avoid spurious build/live issues
due to the fact that the the stdlib is built using the just-built Swift
compiler, which may support features not yet supported by the Swift
compiler in Xcode's toolchain. (default: --no-stdlib-swift)
--test-folders/--no-test-folders
Add folder references for test files (default: --test-folders)
--unittests/--no-unittests
Generate a target for the unittests (default: --unittests)
--infer-args/--no-infer-args
Whether to infer build arguments for files that don't have any, based
on the build arguments of surrounding files. This is mainly useful for
files that aren't built in the default config, but are still useful to
edit (e.g sourcekitdAPI-InProc.cpp). (default: --infer-args)
--prefer-folder-refs/--no-prefer-folder-refs
Whether to prefer folder references for groups containing non-source
files (default: --prefer-folder-refs)
--buildable-folders/--no-buildable-folders
Requires Xcode 16: Enables the use of "buildable folders", allowing
folder references to be used for compatible targets. This allows new
source files to be added to a target without needing to regenerate the
project.
Only supported for targets that have no per-file build settings. This
unfortunately means some Clang targes such as 'lib/Basic' and 'stdlib'
cannot currently use buildable folders. (default: --buildable-folders)
--runtimes-build-dir <runtimes-build-dir>
Experimental: The path to a build directory for the new 'Runtimes/'
stdlib CMake build. This creates a separate 'SwiftRuntimes' project, along
with a 'Swift+Runtimes' workspace.
Note: This requires passing '-DCMAKE_EXPORT_COMPILE_COMMANDS=YES' to
CMake.
MISC:
--project-root-dir <project-root-dir>
The project root directory, which is the parent directory of the Swift repo.
By default this is inferred from the build directory path.
--output-dir <output-dir>
The output directory to write the Xcode project to. Defaults to the project
root directory.
--log-level <log-level> The log level verbosity (default: info) (values: debug, info, note, warning, error)
--parallel/--no-parallel
Parallelize generation of projects (default: --parallel)
-q, --quiet Quiet output; equivalent to --log-level warning
OPTIONS:
-h, --help Show help information.