You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: Docs/GettingStarted.md
+40-43Lines changed: 40 additions & 43 deletions
Original file line number
Diff line number
Diff line change
@@ -7,9 +7,11 @@ Although macOS is not a deployment platform for Swift Foundation, it is useful f
7
7
In order to build on macOS, you will need:
8
8
9
9
* The latest version of Xcode
10
-
* The latest version of the macOS SDK (at this time: 10.14)
10
+
* The latest version of the macOS SDK (at this time: 10.15)
11
11
* The [current Swift toolchain](https://swift.org/download/#snapshots).
12
12
13
+
> Note: due to https://bugs.swift.org/browse/SR-12177 the default Xcode toolchain should be used for now.
14
+
13
15
Foundation is developed at the same time as the rest of Swift, so the most recent version of the compiler is required in order to build it.
14
16
15
17
The repository includes an Xcode project file as well as an Xcode workspace. The workspace includes both Foundation and XCTest, which makes it easy to build and run everything together. The workspace assumes that Foundation and XCTest are checked out from GitHub in sibling directories. For example:
@@ -30,71 +32,66 @@ Build and test steps:
30
32
31
33
> Note: If you see the name of the XCTest project file in red in the workspace, then Xcode cannot find the cloned XCTest repository. Make sure that it is located next to the `swift-corelibs-foundation` directory and has the name `swift-corelibs-xctest`.
32
34
35
+
### Darwin Compatibility Tests
36
+
37
+
In order to increase the compatibility between corelibs-foundation and the native Foundation shipped with macOS, there is another Xcode project in the `swift-corelibs-foundation` repository called `DarwinCompatibilityTests.xcodeproj`. This project just runs all of the `TestFoundation` tests using native Foundation. Ideally, any new test written for corelibs-foundation should be tested against
38
+
native Foundation to validate that that test is correct. The tests can be run individually using the Test navigator in the left hand pane.
39
+
40
+
It should be noted that not all tests currently run correctly either due to differences between the two implentations, the test being used to validate some
41
+
intenal functionality of corelibs-foundation or the test (and the implementation) actually being incorrect. Overtime these test differences should be reduced as compatibility is increased.
42
+
43
+
33
44
## On Linux
34
45
35
46
You will need:
36
47
37
-
* A supported distribution of Linux. At this time, we support [Ubuntu 14.04, Ubuntu 16.04 and Ubuntu 18.04](http://www.ubuntu.com).
48
+
* A supported distribution of Linux. At this time, we support [Ubuntu 16.04 and Ubuntu 18.04](http://www.ubuntu.com).
38
49
39
50
To get started, follow the instructions on how to [build Swift](https://github.com/apple/swift#building-swift). Foundation is developed at the same time as the rest of Swift, so the most recent version of the `clang` and `swift` compilers are required in order to build it. The easiest way to make sure you have all of the correct dependencies is to build everything together.
40
51
41
-
The default build script does not include Foundation. To build Foundation and XCTest as well, pass `--xctest --foundation` to the build script.
42
-
52
+
The default build script does not include Foundation. To configure and build Foundation and TestFoundation including lldb for debugging and the correct ICU library, the following command can be used. All other tests are disabled to reduce build and test time. `--release` is used to avoid building LLVM and the compiler with debugging.
This will build and run the Foundation tests, in the Debug configuration.
59
+
The build artifacts will be written to the subdirectory `build/Ninja-ReleaseAssert`. To use a different build directory set the `SWIFT_BUILD_ROOT` environment variable to point to a different directory to use instead of `build`.
48
60
49
-
After the complete Swift build has finished, you can iterate quickly on Foundation itself by simply invoking `ninja` in the Foundation directory.
61
+
When developing on Foundation, it is simplest to write tests to check the functionality, even if the test is not something that can be used in the final PR, e.g. it runs continously to demostrate a memory leak. Tests are added
62
+
to the appropiate file in the `TestFoundation` directory, and remember to add the test in to the `allTests` array in that file.
50
63
51
-
```
52
-
cd swift-corelibs-foundation
53
-
ninja
54
-
```
64
+
After the complete Swift build has finished you can iterate over changes you make to Foundation using `cmake` to build `TestFoundation` and run the tests.
65
+
Note that `cmake` needs to be a relatively recent version, currently 3.15.1, and if this is not installed already
66
+
then it is built as part of the `build-script` invocation. Therefore `cmake` may be installed in `build/cmake`.
55
67
56
-
This will build Foundation. To build and run the tests, use the `test` target:
% $SWIFT_BUILD_ROOT=build $BUILD_ROOT/cmake-linux-x86_64/bin/cmake --build $BUILD_ROOT/Ninja-ReleaseAssert/foundation-linux-x86_64/ -v -- -j4 test
60
74
```
61
75
62
-
The ninja build script will print the correct command-line invocation for both running the tests and debugging the tests. The exact library path to use will depend on how Foundation itself was configured by the earlier `build-script`. For example:
76
+
If `TestFoundation` needs to be run outside of `ctest`, perhaps to run under `lldb` or to run individual tests, then it can be run directly but an appropiate `LD_LIBRARY_PATH`
77
+
needs to be set so that `libdispatch` and `libXCTest` can be found.
To run only one test class or a single test, the tests to run can be specified as a command argument in the form of `TestFoundation.<TestClass>{/testName}` eg to run all of the tests in `TestDate` use
85
+
`TestFoundation.TestDate`. To run just `test_BasicConstruction`, use `TestFoundation.TestDate/test_BasicConstruction`.
75
86
76
-
Just copy & paste the correct line.
77
-
78
-
When new source files or flags are added to the `build.py` script, the project will need to be reconfigured in order for the build system to pick them up. The top-level `swift/utils/build-script` can be used, but for quicker iteration you can use the following command to limit the reconfiguration to just the Foundation project:
87
+
If the tests need to be run under `lldb`, use the following comand:
When new source files or flags are added to any of the `CMakeLists.txt` files, the project will need to be reconfigured in order for the build system to pick them up. Simply rerun the `cmake` command to build `TestFoundation` given above and it should be reconfigured and built correctly.
100
96
97
+
If `update-checkout` is used to update other repositories, rerun the `build-script` command above to reconfigure and rebuild the other libraries.
0 commit comments