Skip to content

SR-11411: Update GettingStarted.md #2657

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Feb 13, 2020
Merged

SR-11411: Update GettingStarted.md #2657

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
83 changes: 40 additions & 43 deletions Docs/GettingStarted.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,9 +7,11 @@ Although macOS is not a deployment platform for Swift Foundation, it is useful f
In order to build on macOS, you will need:

* The latest version of Xcode
* The latest version of the macOS SDK (at this time: 10.14)
* The latest version of the macOS SDK (at this time: 10.15)
* The [current Swift toolchain](https://swift.org/download/#snapshots).

> Note: due to https://bugs.swift.org/browse/SR-12177 the default Xcode toolchain should be used for now.

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.

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:
Expand All @@ -30,71 +32,66 @@ Build and test steps:

> 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`.

### Darwin Compatibility Tests

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
native Foundation to validate that that test is correct. The tests can be run individually using the Test navigator in the left hand pane.

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
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.


## On Linux

You will need:

* A supported distribution of Linux. At this time, we support [Ubuntu 14.04, Ubuntu 16.04 and Ubuntu 18.04](http://www.ubuntu.com).
* A supported distribution of Linux. At this time, we support [Ubuntu 16.04 and Ubuntu 18.04](http://www.ubuntu.com).

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.

The default build script does not include Foundation. To build Foundation and XCTest as well, pass `--xctest --foundation` to the build script.

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.
```
swift/utils/build-script --xctest --foundation -t
% swift/utils/build-script --libicu --lldb --release --test --foundation --xctest \
--foundation-build-type=debug --skip-test-swift --skip-build-benchmarks \
--skip-test-lldb --skip-test-xctest --skip-test-libdispatch --skip-test-libicu --skip-test-cmark
```

This will build and run the Foundation tests, in the Debug configuration.
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`.

After the complete Swift build has finished, you can iterate quickly on Foundation itself by simply invoking `ninja` in the Foundation directory.
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
to the appropiate file in the `TestFoundation` directory, and remember to add the test in to the `allTests` array in that file.

```
cd swift-corelibs-foundation
ninja
```
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.
Note that `cmake` needs to be a relatively recent version, currently 3.15.1, and if this is not installed already
then it is built as part of the `build-script` invocation. Therefore `cmake` may be installed in `build/cmake`.

This will build Foundation. To build and run the tests, use the `test` target:

```
ninja test
# Build TestFoundation
% $SWIFT_BUILD_ROOT=build $BUILD_ROOT/cmake-linux-x86_64/bin/cmake --build $BUILD_ROOT/Ninja-ReleaseAssert/foundation-linux-x86_64/ -v -- -j4 TestFoundation
# Run the tests
% $SWIFT_BUILD_ROOT=build $BUILD_ROOT/cmake-linux-x86_64/bin/cmake --build $BUILD_ROOT/Ninja-ReleaseAssert/foundation-linux-x86_64/ -v -- -j4 test
```

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:
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`
needs to be set so that `libdispatch` and `libXCTest` can be found.

```
% ninja test
[5/5] Building Tests
**** RUNNING TESTS ****
execute:
LD_LIBRARY_PATH=../build/Ninja-ReleaseAssert/foundation-linux-x86_64/Foundation/:/home/user/Development/build/Ninja-ReleaseAssert/xctest-linux-x86_64 ../build/Ninja-ReleaseAssert/foundation-linux-x86_64/TestFoundation/TestFoundation
**** DEBUGGING TESTS ****
execute:
LD_LIBRARY_PATH=../build/Ninja-ReleaseAssert/foundation-linux-x86_64/Foundation/:/home/user/Development/build/Ninja-ReleaseAssert/xctest-linux-x86_64 lldb ../build/Ninja-ReleaseAssert/foundation-linux-x86_64/TestFoundation/TestFoundation
%
% export BUILD_DIR=build/Ninja-ReleaseAssert
% export LD_LIBRARY_PATH=$BUILD_DIR/foundation-linux-x86_64/Foundation:$BUILD_DIR/xctest-linux-x86_64:$BUILD_DIR/libdispatch-linux-x86_64
% $BUILD_DIR/foundation-linux-x86_64/TestFoundation.app/TestFoundation
```
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
`TestFoundation.TestDate`. To run just `test_BasicConstruction`, use `TestFoundation.TestDate/test_BasicConstruction`.

Just copy & paste the correct line.

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:
If the tests need to be run under `lldb`, use the following comand:

```
% ninja reconfigure
% ninja
% export BUILD_DIR=build/Ninja-ReleaseAssert
% export LD_LIBRARY_PATH=$BUILD_DIR/foundation-linux-x86_64/Foundation:$BUILD_DIR/xctest-linux-x86_64:$BUILD_DIR/libdispatch-linux-x86_64
% $BUILD_DIR/lldb-linux-x86_64/bin/lldb $BUILD_DIR/foundation-linux-x86_64/TestFoundation.app/TestFoundation
```

It is possible to build Foundation without the use of `build-script`. You can
build with cmake. It currently requires clang, swift, and libdispatch (which
are generally built as part of the swift build).

```
cmake \
-G Ninja \
-D CMAKE_BUILD_TYPE=RelWithDebInfo \
-D CMAKE_C_COMPILER=build/Ninja-ReleaseAssert/llvm-linux-x86_64/bin/clang \
-D CMAKE_Swift_COMPILER=build/Ninja-ReleaseAssert/swift-linux-x86_64/bin/swiftc \
-D dispatch_DIR=build/Ninja-ReleaseAssert/libdispatch-linux-x86_64/cmake/modules \
-B build/Ninja-ReleaseAssert/foundation-linux-x86_64
-S swift-corelibs-foundation
ninja -C build/Ninja-ReleaseAssert/foundation-linux-x86_64
```
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.

If `update-checkout` is used to update other repositories, rerun the `build-script` command above to reconfigure and rebuild the other libraries.
10 changes: 9 additions & 1 deletion Foundation.xcodeproj/project.pbxproj
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -426,6 +426,8 @@
B951B5EC1F4E2A2000D8B332 /* TestNSLock.swift in Sources */ = {isa = PBXBuildFile; fileRef = B951B5EB1F4E2A2000D8B332 /* TestNSLock.swift */; };
B95FC97522AF051B005DEA0A /* xcode-build.sh in Resources */ = {isa = PBXBuildFile; fileRef = B95FC97422AF051B005DEA0A /* xcode-build.sh */; };
B95FC97622B84B0A005DEA0A /* TestNSSortDescriptor.swift in Sources */ = {isa = PBXBuildFile; fileRef = 152EF3932283457B001E1269 /* TestNSSortDescriptor.swift */; };
B983E32C23F0C69600D9C402 /* Docs in Resources */ = {isa = PBXBuildFile; fileRef = B983E32B23F0C69600D9C402 /* Docs */; };
B983E32E23F0C6E200D9C402 /* CONTRIBUTING.md in Resources */ = {isa = PBXBuildFile; fileRef = B983E32D23F0C6E200D9C402 /* CONTRIBUTING.md */; };
B98E33DD2136AA740044EBE9 /* TestFileWithZeros.txt in Resources */ = {isa = PBXBuildFile; fileRef = B98E33DC2136AA740044EBE9 /* TestFileWithZeros.txt */; };
B99EAE72236044C900C8FB46 /* SwiftXCTest.framework in CopyFiles */ = {isa = PBXBuildFile; fileRef = B95FC97222AF0050005DEA0A /* SwiftXCTest.framework */; settings = {ATTRIBUTES = (CodeSignOnCopy, RemoveHeadersOnCopy, ); }; };
B9C0E89620C31AB60064C68C /* CFInternal.h in Headers */ = {isa = PBXBuildFile; fileRef = 5B5D888A1BBC963C00234F36 /* CFInternal.h */; settings = {ATTRIBUTES = (Private, ); }; };
Expand Down Expand Up @@ -1075,6 +1077,8 @@
B951B5EB1F4E2A2000D8B332 /* TestNSLock.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = TestNSLock.swift; sourceTree = "<group>"; };
B95FC97222AF0050005DEA0A /* SwiftXCTest.framework */ = {isa = PBXFileReference; explicitFileType = wrapper.framework; path = SwiftXCTest.framework; sourceTree = BUILT_PRODUCTS_DIR; };
B95FC97422AF051B005DEA0A /* xcode-build.sh */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = text.script.sh; path = "xcode-build.sh"; sourceTree = "<group>"; };
B983E32B23F0C69600D9C402 /* Docs */ = {isa = PBXFileReference; lastKnownFileType = folder; path = Docs; sourceTree = "<group>"; };
B983E32D23F0C6E200D9C402 /* CONTRIBUTING.md */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = net.daringfireball.markdown; path = CONTRIBUTING.md; sourceTree = "<group>"; };
B98E33DC2136AA740044EBE9 /* TestFileWithZeros.txt */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = text; path = TestFileWithZeros.txt; sourceTree = "<group>"; };
B9974B8F1EDF4A22007F15B8 /* TransferState.swift */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.swift; path = TransferState.swift; sourceTree = "<group>"; };
B9974B901EDF4A22007F15B8 /* MultiHandle.swift */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.swift; path = MultiHandle.swift; sourceTree = "<group>"; };
Expand Down Expand Up @@ -1342,8 +1346,10 @@
5B5D88531BBC938800234F36 = {
isa = PBXGroup;
children = (
B95FC97422AF051B005DEA0A /* xcode-build.sh */,
B167A6641ED7303F0040B09A /* README.md */,
B983E32D23F0C6E200D9C402 /* CONTRIBUTING.md */,
B95FC97422AF051B005DEA0A /* xcode-build.sh */,
B983E32B23F0C69600D9C402 /* Docs */,
5BDC3F2C1BCC5DB500ED97BB /* Foundation */,
EAB57B681BD1A255004AC5C5 /* CoreFoundation */,
EA66F65B1BF2DF3200136161 /* Bootstrap */,
Expand Down Expand Up @@ -2658,6 +2664,8 @@
isa = PBXResourcesBuildPhase;
buildActionMask = 2147483647;
files = (
B983E32E23F0C6E200D9C402 /* CONTRIBUTING.md in Resources */,
B983E32C23F0C69600D9C402 /* Docs in Resources */,
);
runOnlyForDeploymentPostprocessing = 0;
};
Expand Down