INSTALL.md

   1 ## Grand Central Dispatch (GCD)
   2
   3 GCD is a concurrent programming framework first shipped with Mac OS X Snow
   4 Leopard.  This package is an open source bundling of libdispatch, the core
   5 user space library implementing GCD.  At the time of writing, support for
   6 the BSD kqueue API, and specifically extensions introduced in Mac OS X Snow
   7 Leopard and FreeBSD 9-CURRENT, are required to use libdispatch.  Linux is
   8 supported, but requires specific packages to be installed (see Linux
   9 section at the end of the file). Other systems are currently unsupported.
  10
  11 ### Configuring and installing libdispatch (general comments)
  12
  13 GCD is built using autoconf, automake, and libtool, and has a number of
  14 compile-time configuration options that should be reviewed before starting.
  15 An uncustomized install of the C-API to libdispatch requires:
  16
  17         sh autogen.sh
  18         ./configure
  19         make
  20         make install
  21
  22 libdispatch can be optionally built to include a Swift API. This requires a
  23 Swift toolchain to compile the Swift code in libdispatch and can be done
  24 in two possible scenarios.
  25
  26 If you are building your own Swift toolchain from source, then you should build
  27 libdispatch simply by giving additional arguments to swift/utils/build-script:
  28
  29     ./swift/utils/build-script --libdispatch -- --install-libdispatch
  30
  31 To build libdispatch using a pre-built Swift toolchain and install libdispatch
  32 into that toolchain (to allow that toolchain to compile Swift code containing
  33 "import Dispatch") requires:
  34
  35     sh autogen.sh
  36         ./configure --with-swift-toolchain=<PATH_TO_SWIFT_TOOLCHAIN> --prefix=<PATH_TO_SWIFT_TOOLCHAIN>
  37         make
  38         make install
  39
  40 Note that once libdispatch is installed into a Swift toolchain, that
  41 toolchain cannot be used to compile libdispatch again (you must 'make uninstall'
  42 libdispatch from the toolchain before using it to rebuild libdispatch).
  43
  44 You can also use the build-toolchain script to create a toolchain
  45 that includes libdispatch on Linux:
  46
  47 1. Add libdispatch and install-libdispatch lines to ./swift/utils/build-presets.ini under `[preset: buildbot_linux]` section, as following:
  48
  49     ```
  50     [preset: buildbot_linux]
  51     mixin-preset=mixin_linux_installation
  52     build-subdir=buildbot_linux
  53     lldb
  54     release
  55     test
  56     validation-test
  57     long-test
  58     libdispatch
  59     foundation
  60     lit-args=-v
  61     dash-dash
  62
  63     install-libdispatch
  64     install-foundation
  65     reconfigure
  66     ```
  67
  68 2. Run:
  69
  70     ```
  71     ./swift/utils/build-toolchain local.swift
  72     ```
  73
  74 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.
  75
  76 ### Building and installing on OS X
  77
  78 The following configure options may be of general interest:
  79
  80 `--with-apple-libpthread-source`
  81
  82 Specify the path to Apple's libpthread package, so that appropriate headers
  83         can be found and used.
  84
  85 `--with-apple-libplatform-source`
  86
  87 Specify the path to Apple's libplatform package, so that appropriate headers
  88         can be found and used.
  89
  90 `--with-apple-libclosure-source`
  91
  92 Specify the path to Apple's Libclosure package, so that appropriate headers
  93         can be found and used.
  94
  95 `--with-apple-xnu-source`
  96
  97 Specify the path to Apple's XNU package, so that appropriate headers can be
  98         found and used.
  99
 100 `--with-blocks-runtime`
 101
 102 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.
 103
 104 The following options are likely to only be useful when building libdispatch on
 105 OS X as a replacement for /usr/lib/system/libdispatch.dylib:
 106
 107 `--with-apple-objc4-source`
 108
 109 Specify the path to Apple's objc4 package, so that appropriate headers can
 110         be found and used.
 111
 112 `--disable-libdispatch-init-constructor`
 113
 114 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.
 115
 116 `--enable-apple-tsd-optimizations`
 117
 118 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.
 119
 120 #### Typical configuration commands
 121
 122 The following command lines create the configuration required to build
 123 libdispatch for /usr/lib/system on OS X El Capitan:
 124
 125         clangpath=$(dirname `xcrun --find clang`)
 126         sudo mkdir -p "$clangpath/../local/lib/clang/enable_objc_gc"
 127         LIBTOOLIZE=glibtoolize sh autogen.sh
 128         cflags='-arch x86_64 -arch i386 -g -Os'
 129         ./configure CFLAGS="$cflags" OBJCFLAGS="$cflags" CXXFLAGS="$cflags" \
 130                 --prefix=/usr --libdir=/usr/lib/system --disable-static \
 131                 --enable-apple-tsd-optimizations \
 132                 --with-apple-libpthread-source=/path/to/10.11.0/libpthread-137.1.1 \
 133                 --with-apple-libplatform-source=/path/to/10.11.0/libplatform-73.1.1 \
 134                 --with-apple-libclosure-source=/path/to/10.11.0/libclosure-65 \
 135                 --with-apple-xnu-source=/path/to/10.11.0/xnu-3247.1.106 \
 136                 --with-apple-objc4-source=/path/to/10.11.0/objc4-680
 137         make check
 138
 139 ### Building and installing for FreeBSD
 140
 141 Typical configuration line for FreeBSD 8.x and 9.x to build libdispatch with
 142 clang and blocks support:
 143
 144         sh autogen.sh
 145         ./configure CC=clang --with-blocks-runtime=/usr/local/lib
 146         make check
 147
 148 ### Building and installing for Linux
 149
 150 Note that libdispatch development and testing is done only
 151 on Ubuntu; currently supported versions are 14.04, 15.10 and 16.04.
 152
 153 1. The first thing to do is install required packages:
 154
 155  1a. Install build tools and clang compiler.
 156     `sudo apt-get install autoconf libtool pkg-config clang`
 157
 158  1b. Install dtrace (to generate provider.h)
 159     `sudo apt-get install systemtap-sdt-dev`
 160
 161  1c. Install additional libdispatch dependencies
 162     `sudo apt-get install libblocksruntime-dev libkqueue-dev libbsd-dev`
 163
 164     Note: compiling libdispatch requires clang 3.8 or better and
 165 the gold linker. If the default clang on your Ubuntu version is
 166 too old, see http://apt.llvm.org/ to install a newer version.
 167 On older Ubuntu releases, you may need to install binutils-gold
 168 to get the gold linker.
 169
 170 2. Initialize git submodules.
 171   We are using git submodules to incorporate specific revisions of the
 172   upstream pthread_workqueue and libkqueue projects into the build.
 173
 174     ```
 175     git submodule init
 176     git submodule update
 177     ```
 178
 179 3. Build (as in the general instructions above)
 180
 181     ```
 182     sh autogen.sh
 183     ./configure
 184     make
 185     make install
 186     ```