How to read Swift source code

Why do we need to read the source code

• To learn how it works
• To improve personal coding ability
• To find bugs
• To satisfy self
• Just for fun
• …

Some funny Examples

What will output in the terminal after executing those codes? Try it by yourself.

Example 1

Example 2

I think that is hard to guess why to happen if you don’t read the source code.

How to take the first step

Not like reading a book or paper, we can read those chapters by chapters. Reading source code is not an easy thing, insist on it is a challenge. Thus, here are some suggestions.

• Start from where you are interested in. Interest is the best teacher.
• Share what you learn recently with your mates.
• Don’t be afraid of the slow progress of the beginning learning, and keep patient. The more you learn, the faster you can learn.

Debugging Swift

I think the best way to read swift source code is by debugging it, makes you look into each piece code step by step.

I highly recommend that you should read the entire README.md from beginning to end before you continue reading the next part.

Let’s start exploring.

To build from source you will need about 2 GB of disk space for the source code and up to 70 GB of disk space for the build artifacts with full debugging.

System Requirements

1. Python 2.x
2. The latest Xcode ( 11.3 is the latest version on Dec 16, 2019)
3. brew install cmake ninja

Download source code

https://github.com/apple/swift

mkdir swift-source
cd swift-source
git clone <https://github.com/apple/swift.git>
./swift/utils/update-checkout --clone

You may pass --tag [VERSION] to update-checkout for fetching specified Swift version.

For debugging swift 5.1.3, I use this script.

./utils/update-checkout --tag swift-5.1.3-RELEASE --clone

Building Swift

you can follow the help documentation to assemble the scripts you need.

Depending on your machine, those build scripts can cost a half hour or more.

To debug Swift standard library with ninja (Recommended)

sudo ./swift/utils/build-script -r --debug-swift-stdlib --lldb

This build script can generate LLDB paired with Swift, which guarantees you to debug normally.

To debug Swift & swift standard library with Xcode

sudo ./swift/utils/build-script -x -R --debug-swift --debug-swift-stdlib

By passing the parameter -x, a swift.xcodeproj will be generated in the build/.../swift-macosx-x86_64 directory. You can view the entire project in Xcode and use the jump to definition function to improve reading efficiency.

However, because of this tight integration, developers must use a matched pair of compiler and debugger built using the same sources. Debugging using any other version of LLDB can lead to unpredictable results.

https://swift.org/lldb/#why-combine-the-repl-and-debugger

But there’s an issue, the built-in LLDB may lead to unpredictable results. You can’t see the clear type for the specified variable, as shown below.

Build Failures

1. Make sure you are using the correct release of Xcode.
2. If you have changed Xcode versions but still encounter errors that appear to be related to the Xcode version, try passing — clean to build-script .
3. When a new version of Xcode is released, you can update your build without recompiling the entire project by passing the — reconfigure option.
4. Make sure all repositories are up to date with the update-checkout command described above.
5. When encountering permission issues, you may need to execute this **sudo chown -R $(whoami)** ..

Debugging Swift

Once you build the Swift successfully, find the products in the build directory.

The product here is built on this command. You can find the corresponding in build/Ninja-RelWithDebInfoAssert+stdlib-DebugAssert.

sudo ./swift/utils/build-script -r --debug-swift-stdlib --lldb

VS Code (Recommended)

Firstly, open swift directory on VS Code, and add debug configuration like below (launch.json).

{
    "version": "0.2.0",
    "configurations": [
        {
            "type": "lldb",
            "request": "launch",
            "name": "Debug",
            "program": "${workspaceFolder}/../build/Ninja-RelWithDebInfoAssert+stdlib-DebugAssert/swift-macosx-x86_64/bin/swift",
            "args": [],
            "cwd": "${workspaceFolder}",
        }
    ]
}

Secondly, set the breakpoint where you need to debug.

Lastly, input something in the terminal and enjoy it!

Terminal

Firstly, run the Swift executable file.

cd build/Ninja-RelWithDebInfoAssert+stdlib-DebugAssert
./swift-macosx-x86_64/bin/swift

Secondly, run the paired LLDB in the same folder.

./lldb-macosx-x86_64/bin/lldb

Lastly, attach the Swift process and enjoy it again!

Reference

https://github.com/apple/swift

https://lldb.llvm.org/index.html

https://forums.swift.org/t/debug-local-stack-frame-variables-fails-failed-to-get-module-builtin-from-ast-context/19171/12

https://github.com/apple/swift/blob/master/docs/DebuggingTheCompiler.rst#types-loghttps://github.com/apple/swift/blob/master/docs/DebuggingTheCompiler.rst#types-log

https://www.polidea.com/blog/how-to-build-swift-compiler-based-tool-the-step-by-step-guide/

https://github.com/vadimcn/vscode-lldb/blob/master/MANUAL.md