Skip to content

Added Toolchain section in INSTALL.md #138

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
Aug 10, 2016
Merged

Added Toolchain section in INSTALL.md #138

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
112 changes: 72 additions & 40 deletions INSTALL → INSTALL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
Grand Central Dispatch (GCD)
## Grand Central Dispatch (GCD)

GCD is a concurrent programming framework first shipped with Mac OS X Snow
Leopard. This package is an open source bundling of libdispatch, the core
Expand All @@ -8,7 +8,7 @@ Leopard and FreeBSD 9-CURRENT, are required to use libdispatch. Linux is
supported, but requires specific packages to be installed (see Linux
section at the end of the file). Other systems are currently unsupported.

I. Configuring and installing libdispatch (general comments)
### Configuring and installing libdispatch (general comments)

GCD is built using autoconf, automake, and libtool, and has a number of
compile-time configuration options that should be reviewed before starting.
Expand Down Expand Up @@ -41,59 +41,82 @@ Note that once libdispatch is installed into a Swift toolchain, that
toolchain cannot be used to compile libdispatch again (you must 'make uninstall'
libdispatch from the toolchain before using it to rebuild libdispatch).

II. Building and installing on OS X
To create the toolchain with libdispatch Using build-toolchain in Linux:

1. Add libdispatch and install-libdispatch lines to ./swift/utils/build-presets.ini under `[preset: buildbot_linux]` section, as following:

```
[preset: buildbot_linux]
mixin-preset=mixin_linux_installation
build-subdir=buildbot_linux
lldb
release
test
validation-test
long-test
libdispatch
foundation
lit-args=-v
dash-dash

install-libdispatch
install-foundation
reconfigure
```

2. Run:

```
./swift/utils/build-toolchain local.swift
```

Note that adding libdispatch in build-presets.ini is for Linux only as Swift on macOS platforms uses the system installed libdispatch, so its not required.

### Building and installing on OS X

The following configure options may be of general interest:

--with-apple-libpthread-source
`--with-apple-libpthread-source`

Specify the path to Apple's libpthread package, so that appropriate headers
Specify the path to Apple's libpthread package, so that appropriate headers
can be found and used.

--with-apple-libplatform-source
`--with-apple-libplatform-source`

Specify the path to Apple's libplatform package, so that appropriate headers
Specify the path to Apple's libplatform package, so that appropriate headers
can be found and used.

--with-apple-libclosure-source
`--with-apple-libclosure-source`

Specify the path to Apple's Libclosure package, so that appropriate headers
Specify the path to Apple's Libclosure package, so that appropriate headers
can be found and used.

--with-apple-xnu-source
`--with-apple-xnu-source`

Specify the path to Apple's XNU package, so that appropriate headers can be
Specify the path to Apple's XNU package, so that appropriate headers can be
found and used.

--with-blocks-runtime
`--with-blocks-runtime`

On systems where -fblocks is supported, specify an additional library path
in which libBlocksRuntime can be found. This is not required on OS X,
where the Blocks runtime is included in libSystem, but is required on
FreeBSD.
On systems where -fblocks is supported, specify an additional library path in which libBlocksRuntime can be found. This is not required on OS X, where the Blocks runtime is included in libSystem, but is required on FreeBSD.

The following options are likely to only be useful when building libdispatch on
OS X as a replacement for /usr/lib/system/libdispatch.dylib:

--with-apple-objc4-source
`--with-apple-objc4-source`

Specify the path to Apple's objc4 package, so that appropriate headers can
Specify the path to Apple's objc4 package, so that appropriate headers can
be found and used.

--disable-libdispatch-init-constructor
`--disable-libdispatch-init-constructor`

Do not tag libdispatch's init routine as __constructor, in which case it
must be run manually before libdispatch routines can be called. This is the
default when building on OS X. For /usr/lib/system/libdispatch.dylib
the init routine is called automatically during process start.
Do not tag libdispatch's init routine as __constructor, in which case it must be run manually before libdispatch routines can be called. This is the default when building on OS X. For /usr/lib/system/libdispatch.dylib the init routine is called automatically during process start.

--enable-apple-tsd-optimizations
`--enable-apple-tsd-optimizations`

Use a non-portable allocation scheme for pthread per-thread data (TSD) keys
when building libdispatch for /usr/lib/system on OS X. This should not
be used on other OS's, or on OS X when building a stand-alone library.
Use a non-portable allocation scheme for pthread per-thread data (TSD) keys when building libdispatch for /usr/lib/system on OS X. This should not be used on other OS's, or on OS X when building a stand-alone library.

Typical configuration commands
#### Typical configuration commands

The following command lines create the configuration required to build
libdispatch for /usr/lib/system on OS X El Capitan:
Expand All @@ -112,7 +135,7 @@ libdispatch for /usr/lib/system on OS X El Capitan:
--with-apple-objc4-source=/path/to/10.11.0/objc4-680
make check

III. Building and installing for FreeBSD
### Building and installing for FreeBSD

Typical configuration line for FreeBSD 8.x and 9.x to build libdispatch with
clang and blocks support:
Expand All @@ -121,33 +144,42 @@ clang and blocks support:
./configure CC=clang --with-blocks-runtime=/usr/local/lib
make check

IV. Building and installing for Linux
### Building and installing for Linux

Note that libdispatch development and testing is done only
on Ubuntu; currently supported versions are 14.04, 15.10 and 16.04.

(1) The first thing to do is install required packages:
1. The first thing to do is install required packages:

1a. Install build tools and clang compiler.
sudo apt-get install autoconf libtool pkg-config clang
`sudo apt-get install autoconf libtool pkg-config clang`

1b. Install dtrace (to generate provider.h)
sudo apt-get install systemtap-sdt-dev
`sudo apt-get install systemtap-sdt-dev`

1c. Install additional libdispatch dependencies
sudo apt-get install libblocksruntime-dev libkqueue-dev libbsd-dev
`sudo apt-get install libblocksruntime-dev libkqueue-dev libbsd-dev`

Note: compiling libdispatch requires clang 3.8 or better and
Note: compiling libdispatch requires clang 3.8 or better and
the gold linker. If the default clang on your Ubuntu version is
too old, see http://apt.llvm.org/ to install a newer version.
On older Ubuntu releases, you may need to install binutils-gold
to get the gold linker.

(2) Initialize git submodules.
2. Initialize git submodules.
We are using git submodules to incorporate specific revisions of the
upstream pthread_workqueue and libkqueue projects into the build.

```
git submodule init
git submodule update
```

3. Build (as in the general instructions above)

(3) Build (as in the general instructions above)
sh autogen.sh
./configure
make
```
sh autogen.sh
./configure
make
make install
```
12 changes: 8 additions & 4 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,9 +18,13 @@ libdispatch on Darwin is a combination of logic in the `xnu` kernel alongside th

Our first tasks for this project are:

0. Adapt the current autotools build system to work on Linux, or develop a new makefile or other build script for the project on Linux. The current version of the build system has only been tested on Darwin, though previous versions have been made to work on FreeBSD and Linux (see INSTALL).
0. Omit as much of the extra functionality of the library as possible, to get a core version of the project building. Much of the OS X-specific functionality can be elided completely on Linux.
0. Adopt libdispatch in other Core Libraries projects, especially Foundation. This will validate our work and get immediate coverage on basic functionality.
0. Incrementally add functionality back in.
1. Adapt the current autotools build system to work on Linux, or develop a new makefile or other build script for the project on Linux. The current version of the build system has only been tested on Darwin, though previous versions have been made to work on FreeBSD and Linux (see [INSTALL](INSTALL.md)).
2. Omit as much of the extra functionality of the library as possible, to get a core version of the project building. Much of the OS X-specific functionality can be elided completely on Linux.
3. Adopt libdispatch in other Core Libraries projects, especially Foundation. This will validate our work and get immediate coverage on basic functionality.
4. Incrementally add functionality back in.

Some C headers and sources (e.g. `Availability.h`, `Block.h`, and the libclosure `runtime.c`) are similar to ones embedded into the CoreFoundation part of [swift-corelibs-foundation](http://github.com/apple/swift-corelibs-foundation). We should figure out a mechanism to share these instead of duplicating them across projects.

## See also

[INSTALL](INSTALL.md)