[apple/libdispatch.git] / INSTALL

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
user space library implementing GCD.  At the time of writing, support for
the BSD kqueue API, and specifically extensions introduced in Mac OS X Snow
Leopard and FreeBSD 9-CURRENT, are required to use libdispatch.  Other
systems are currently unsupported.

  Configuring and installing libdispatch

GCD is built using autoconf, automake, and libtool, and has a number of
compile-time configuration options that should be reviewed before starting.
An uncustomized install requires:

	sh autogen.sh
	./configure
	make
	make install

The following configure options may be of general interest:

--with-apple-libc-source

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

--with-apple-libclosure-source

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

--with-apple-xnu-source

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

--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
	Mac 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 Mac OS X as a replacement for /usr/lib/system/libdispatch.dylib:

--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.
	For the libdispatch library in /usr/lib/system, the init routine is called
	automatically during process start.

--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 Mac OS X.  This
	should not be used on other OS's, or on Mac OS X when building a
	stand-alone library.

  Typical configuration commands

The following command lines create the configuration required to build
libdispatch for /usr/lib/system on Mac OS X Lion:

	sh autogen.sh
	./configure CFLAGS='-arch x86_64 -arch i386' \
		--prefix=/usr --libdir=/usr/lib/system \
		--disable-dependency-tracking --disable-static \
		--disable-libdispatch-init-constructor \
		--enable-apple-tsd-optimizations \
		--with-apple-libc-source=/path/to/10.7.0/Libc-763.11 \
		--with-apple-libclosure-source=/path/to/10.7.0/libclosure-53 \
		--with-apple-xnu-source=/path/to/10.7.0/xnu-1699.22.73

Typical configuration line for FreeBSD 8.x and 9.x to build libdispatch with
clang and blocks support:

	sh autogen.sh
	./configure CC=clang --with-blocks-runtime=/usr/local/lib
Commit	Line	Data
e85f4437 A	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. Other
	8	systems are currently unsupported.
	9
	10	Configuring and installing libdispatch
	11
	12	GCD is built using autoconf, automake, and libtool, and has a number of
	13	compile-time configuration options that should be reviewed before starting.
	14	An uncustomized install requires:
	15
	16	sh autogen.sh
	17	./configure
	18	make
	19	make install
	20
	21	The following configure options may be of general interest:
	22
	23	--with-apple-libc-source
	24
	25	Specify the path to Apple's Libc package, so that appropriate headers
	26	can be found and used.
	27
	28	--with-apple-libclosure-source
	29
	30	Specify the path to Apple's Libclosure package, so that appropriate headers
	31	can be found and used.
	32
	33	--with-apple-xnu-source
	34
	35	Specify the path to Apple's XNU package, so that appropriate headers
	36	can be found and used.
	37
	38	--with-blocks-runtime
	39
	40	On systems where -fblocks is supported, specify an additional library
	41	path in which libBlocksRuntime can be found. This is not required on
	42	Mac OS X, where the Blocks runtime is included in libSystem, but is
	43	required on FreeBSD.
	44
	45	The following options are likely to only be useful when building libdispatch
	46	on Mac OS X as a replacement for /usr/lib/system/libdispatch.dylib:
	47
	48	--disable-libdispatch-init-constructor
	49
	50	Do not tag libdispatch's init routine as __constructor, in which case
	51	it must be run manually before libdispatch routines can be called.
	52	For the libdispatch library in /usr/lib/system, the init routine is called
	53	automatically during process start.
	54
	55	--enable-apple-tsd-optimizations
	56
	57	Use a non-portable allocation scheme for pthread per-thread data (TSD)
	58	keys when building libdispatch for /usr/lib/system on Mac OS X. This
	59	should not be used on other OS's, or on Mac OS X when building a
	60	stand-alone library.
	61
	62	Typical configuration commands
	63
	64	The following command lines create the configuration required to build
65	libdispatch for /usr/lib/system on Mac OS X Lion:
66
67	sh autogen.sh
68	./configure CFLAGS='-arch x86_64 -arch i386' \
69	--prefix=/usr --libdir=/usr/lib/system \
70	--disable-dependency-tracking --disable-static \
71	--disable-libdispatch-init-constructor \
72	--enable-apple-tsd-optimizations \
73	--with-apple-libc-source=/path/to/10.7.0/Libc-763.11 \
74	--with-apple-libclosure-source=/path/to/10.7.0/libclosure-53 \
75	--with-apple-xnu-source=/path/to/10.7.0/xnu-1699.22.73
76
77	Typical configuration line for FreeBSD 8.x and 9.x to build libdispatch with
78	clang and blocks support:
79
80	sh autogen.sh
81	./configure CC=clang --with-blocks-runtime=/usr/local/lib