diff --git a/Documentation/AdvancedBuildInstructions.md b/Documentation/AdvancedBuildInstructions.md index 9a528982668..5f1aa3ce2f9 100644 --- a/Documentation/AdvancedBuildInstructions.md +++ b/Documentation/AdvancedBuildInstructions.md @@ -152,3 +152,53 @@ After you’ve finished debugging your code changes with that build, you can rev ``` That will restore your git environment to the state it was in before you patched the build file. + +## Building with Swift support + +There is experimental Swift 6 support in the ladybird codebase. This experiment intends to determine whether Swift 6 and +its improved C++ interoperability is a good choice for new memory-safe and concurrent code for Ladybird. + +Building with Swift 6 support requires a main snapshot toolchain. The Ladybird team is actively working with the Swift +team to improve the C++ interop features to meet the needs of our project. + +The best way to get started is with `swiftly`. After setting up a swiftly toolchain, any of the existing build presets +can be modified to use the Swift toolchain. However, note that in order to build Swift support into the project, the +build must use a version of clang that is built from an llvm fork with swift support. The two places this can be found +are from the swift.org snapshot/release toolchains, and Xcode toolchains. Upstream llvm.org clang does not support +Swift, and gcc does not support Swift either. + +### Get Swiftly + +`swiftly` is a tool that helps you manage Swift toolchains. It can be installed from https://www.swift.org/install/linux/ +or https://www.swift.org/install/macos/ as applicable. After following the instructions on the swift.org install page, +swiftly installs the latest release toolchain. If you wish to save space, add the `--skip-install` flag to the `swiftly +init` invocation. If you wish to avoid swiftly messing with your shellrc files, add `--no-modify-profile`. On some linux +platforms, it may be necessary to add a `--platform` flag to the `swiftly init` invocation to instruct swiftly on which +supported platform to masquerade as. This is especially necessary on Fedora or other non-Debian based distributions. + +Note that while `$SWIFTLY_HOME_DIR` and `$SWIFTLY_BIN_DIR` can be used +to set the installed location of the swiftly binary and its associated files, the install location of toolchains is not +nearly as customizable. On linux they will always be placed in `$XDG_DATA_HOME/swiftly/toolchains`, and on macOS they will always be +placed in `$HOME/Library/Developer/Toolchains`. On macOS, the `.pkg` file will always drop temporary files in `$HOME/.swiftly`, +so be sure to clear them out if you change the default home/bin directories. + +### Build with Swift + +The simplest way to enable swift is to pass extra arguments to a build preset. Note however that if your IDE has loaded +the build presets from disk, you may need to create a customized build preset in your IDE settings to avoid the IDE +overriding your settings with its own, causing unnecessary rebuilds. + +``` +# Refer to .github/actions/setup/action.yml for the snapshot version tested in CI +swiftly install --use main-snapshot + +cmake --preset default \ + -DENABLE_SWIFT=ON \ + -DCMAKE_C_COMPILER=$(swiftly use --print-location)/usr/bin/clang \ + -DCMAKE_CXX_COMPILER=$(swiftly use --print-location)/usr/bin/clang++ +``` + +Note that trying to use just `clang` or `$SWIFTLY_BIN_DIR/clang` will both fail, due to https://github.com/swiftlang/swiftly/issues/272. + +As another note, the main-snapshot toolchains from swift.org are `+assertion` builds. This means that both clang and +swiftc are built with extra assertions that will cause compile-times to be longer than a standard release build.