INSTALL

   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.  Support
   8 for Linux is a work in progress (see Linux notes below). Other systems are
   9 currently unsupported.
  10
  11   Configuring and installing libdispatch
  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 requires:
  16
  17         sh autogen.sh
  18         ./configure
  19         make
  20         make install
  21
  22 The following configure options may be of general interest:
  23
  24 --with-apple-libpthread-source
  25
  26         Specify the path to Apple's libpthread package, so that appropriate headers
  27         can be found and used.
  28
  29 --with-apple-libplatform-source
  30
  31         Specify the path to Apple's libplatform package, so that appropriate headers
  32         can be found and used.
  33
  34 --with-apple-libclosure-source
  35
  36         Specify the path to Apple's Libclosure package, so that appropriate headers
  37         can be found and used.
  38
  39 --with-apple-xnu-source
  40
  41         Specify the path to Apple's XNU package, so that appropriate headers can be
  42         found and used.
  43
  44 --with-blocks-runtime
  45
  46         On systems where -fblocks is supported, specify an additional library path
  47         in which libBlocksRuntime can be found.  This is not required on OS X,
  48         where the Blocks runtime is included in libSystem, but is required on
  49         FreeBSD.
  50
  51 The following options are likely to only be useful when building libdispatch on
  52 OS X as a replacement for /usr/lib/system/libdispatch.dylib:
  53
  54 --with-apple-objc4-source
  55
  56         Specify the path to Apple's objc4 package, so that appropriate headers can
  57         be found and used.
  58
  59 --disable-libdispatch-init-constructor
  60
  61         Do not tag libdispatch's init routine as __constructor, in which case it
  62         must be run manually before libdispatch routines can be called. This is the
  63         default when building on OS X. For /usr/lib/system/libdispatch.dylib
  64         the init routine is called automatically during process start.
  65
  66 --enable-apple-tsd-optimizations
  67
  68         Use a non-portable allocation scheme for pthread per-thread data (TSD) keys
  69         when building libdispatch for /usr/lib/system on OS X.  This should not
  70         be used on other OS's, or on OS X when building a stand-alone library.
  71
  72   Typical configuration commands
  73
  74 The following command lines create the configuration required to build
  75 libdispatch for /usr/lib/system on OS X El Capitan:
  76
  77         clangpath=$(dirname `xcrun --find clang`)
  78         sudo mkdir -p "$clangpath/../local/lib/clang/enable_objc_gc"
  79         LIBTOOLIZE=glibtoolize sh autogen.sh
  80         cflags='-arch x86_64 -arch i386 -g -Os'
  81         ./configure CFLAGS="$cflags" OBJCFLAGS="$cflags" CXXFLAGS="$cflags" \
  82                 --prefix=/usr --libdir=/usr/lib/system --disable-static \
  83                 --enable-apple-tsd-optimizations \
  84                 --with-apple-libpthread-source=/path/to/10.11.0/libpthread-137.1.1 \
  85                 --with-apple-libplatform-source=/path/to/10.11.0/libplatform-73.1.1 \
  86                 --with-apple-libclosure-source=/path/to/10.11.0/libclosure-65 \
  87                 --with-apple-xnu-source=/path/to/10.11.0/xnu-3247.1.106 \
  88                 --with-apple-objc4-source=/path/to/10.11.0/objc4-680
  89         make check
  90
  91 Typical configuration line for FreeBSD 8.x and 9.x to build libdispatch with
  92 clang and blocks support:
  93
  94         sh autogen.sh
  95         ./configure CC=clang --with-blocks-runtime=/usr/local/lib
  96         make check
  97
  98 Instructions for building on Linux. Initial focus is on ubuntu 15.04.
  99 Prepare your system
 100  1. Install compiler, autotools
 101     sudo apt-get install clang
 102     sudo apt-get install autoconf libtool pkg-config
 103  2. Install dtrace (to generate provider.h)
 104     sudo apt-get install systemtap-sdt-dev
 105  3. Install libdispatch pre-reqs
 106     sudo apt-get install libblocksruntime-dev libkqueue-dev libbsd-dev
 107
 108 Initialize git submodules:
 109   We are using git submodules to incorporate a specific revision of the
 110   upstream pthread_workqueue library into the build.
 111     git submodule init
 112     git submodule update
 113
 114 Build:
 115         sh autogen.sh
 116         ./configure
 117         make
 118
 119 Note: the build currently fails building tests, but libdispatch.so should
 120       build successfully.