Really backport PRs 134 135 139 138 140 to swift-3.0-branch

INSTALL → INSTALL.md

@@ -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
@@ -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.
@@ -41,59 +41,83 @@ 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
+You can also use the build-toolchain script to create a toolchain
+that includes libdispatch on 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:
@@ -112,7 +136,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:
@@ -121,33 +145,35 @@ 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:
- 1a. Install build tools and clang compiler.
-    sudo apt-get install autoconf libtool pkg-config clang
- 1b. Install dtrace (to generate provider.h)
-    sudo apt-get install systemtap-sdt-dev
- 1c. Install additional libdispatch dependencies
-    sudo apt-get install libblocksruntime-dev libkqueue-dev libbsd-dev
-
-Note: compiling libdispatch requires clang 3.8 or better and
+1. The first thing to do is install required packages:
+
+    `sudo apt-get install autoconf libtool pkg-config clang systemtap-sdt-dev libbsd-dev`
+
+    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
+    ```

README.md

@@ -4,23 +4,16 @@ Grand Central Dispatch (GCD or libdispatch) provides comprehensive support for c
 
 libdispatch is currently available on all Darwin platforms. This project aims to make a modern version of libdispatch available on all other Swift platforms. To do this, we will implement as much of the portable subset of the API as possible, using the existing open source C implementation.
 
-## Project Goals
-
-We are currently very early in the development of this project. Our starting point is simply a mirror of the open source drop that corresponds with OS X El Capitan (10.11). Therefore, our earliest goals are:
-
-0. Build and test the C source code as a dynamic library on the current Swift Linux targets (Ubuntu 14.04 and Ubuntu 15.10).
-0. Add a `module.modulemap` and make the libdispatch API importable into Swift.
-0. After the previous two steps are done, consider possible improvements to the interface of the libdispatch API in Swift.
+libdispatch on Darwin is a combination of logic in the `xnu` kernel alongside the user-space Library. The kernel has the most information available to balance workload across the entire system. As a first step, however, we believe it is useful to bring up the basic functionality of the library using user-space pthread primitives on Linux.  Eventually, a Linux kernel module could be developed to support more informed thread scheduling.
 
-## Building a C Library
-
-libdispatch on Darwin is a combination of logic in the `xnu` kernel alongside the user-space Library. The kernel has the most information available to balance workload across the entire system. As a first step, however, we believe it is useful to bring up the basic functionality of the library using user-space pthread primitives on Linux.
+## Project Goals
 
-Our first tasks for this project are:
+We are currently early in the development of this project. We began with a mirror of the open source drop that corresponds with OS X El Capitan (10.11) and have ported it to x86_64 Ubuntu 14.04 and 15.10. The next steps are:
+1. Complete the work to adopt libdispatch in other Core Libraries projects, especially Foundation. This will validate our work and get immediate test coverage on basic functionality of the Swift API.
+2. Include libdispatch and libdispatch-enabled Core Libraries in the Swift CI environment and the pre-built Swift toolchains at Swift.org.
+4. Develop a test suite for the Swift APIs of libdispatch.
+4. Enhance libdispatch as needed to support Swift language evolution and the needs of the other Core Libraries projects.
 
-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.
+## Build and Install
 
-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.
+For detailed instructions on building and installing libdispatch, see [INSTALL.md](INSTALL.md)

dispatch/module.modulemap

@@ -2,7 +2,6 @@ module Dispatch {
 	requires blocks
 	export *
 	link "dispatch"
-	link "BlocksRuntime"
 }
 
 module DispatchIntrospection [system] [extern_c] {
@@ -16,5 +15,4 @@ module CDispatch [system] [extern_c] {
 	export *
 	requires blocks
 	link "dispatch"
-	link "BlocksRuntime"
 }

m4/blocks.m4

@@ -10,6 +10,21 @@ AC_ARG_WITH([blocks-runtime],
     LIBS="$LIBS -L$blocks_runtime"]
 )
 
+#
+# Configure argument to enable/disable using an embedded blocks runtime
+#
+AC_ARG_ENABLE([embedded_blocks_runtime],
+  [AS_HELP_STRING([--enable_embedded_blocks_runtime],
+    [Enable usage of blocks runtime embedded in libdispatch])],,
+  [case $target_os in
+      linux*)
+        enable_embedded_blocks_runtime=yes
+	    ;;
+      *)
+        enable_embedded_blocks_runtime=no
+   esac]
+)
+
 #
 # Detect compiler support for Blocks; perhaps someday -fblocks won't be
 # required, in which case we'll need to change this.
@@ -29,30 +44,32 @@ AC_CACHE_CHECK([for C Blocks support], [dispatch_cv_cblocks], [
 AS_IF([test "x$dispatch_cv_cblocks" != "xno"], [
     CBLOCKS_FLAGS="$dispatch_cv_cblocks"
 
-    #
-    # It may be necessary to directly link the Blocks runtime on some
-    # systems, so give it a try if we can't link a C program that uses
-    # Blocks.  We will want to remove this at somepoint, as really -fblocks
-    # should force that linkage already.
-    #
-    saveCFLAGS="$CFLAGS"
-    CFLAGS="$CFLAGS -fblocks -O0"
-    AC_MSG_CHECKING([whether additional libraries are required for the Blocks runtime])
-    AC_TRY_LINK([], [
-	^{ int j; j=0; }();
-    ], [
-	AC_MSG_RESULT([no]);
-    ], [
-      saveLIBS="$LIBS"
-      LIBS="$LIBS -lBlocksRuntime"
-      AC_TRY_LINK([], [
-	^{ int k; k=0; }();
-      ], [
-	AC_MSG_RESULT([-lBlocksRuntime])
-      ], [
-	AC_MSG_ERROR([can't find Blocks runtime])
-      ])
-    ])
+	AS_IF([test "x$enable_embedded_blocks_runtime" != "xyes"], [
+	    #
+	    # It may be necessary to directly link the Blocks runtime on some
+	    # systems, so give it a try if we can't link a C program that uses
+	    # Blocks.  We will want to remove this at somepoint, as really -fblocks
+	    # should force that linkage already.
+	    #
+	    saveCFLAGS="$CFLAGS"
+	    CFLAGS="$CFLAGS -fblocks -O0"
+	    AC_MSG_CHECKING([whether additional libraries are required for the Blocks runtime])
+	    AC_TRY_LINK([], [
+		^{ int j; j=0; }();
+	    ], [
+		AC_MSG_RESULT([no]);
+	    ], [
+	      saveLIBS="$LIBS"
+	      LIBS="$LIBS -lBlocksRuntime"
+	      AC_TRY_LINK([], [
+		^{ int k; k=0; }();
+	      ], [
+		AC_MSG_RESULT([-lBlocksRuntime])
+	      ], [
+		AC_MSG_ERROR([can't find Blocks runtime])
+	      ])
+	    ])
+	])
     CFLAGS="$saveCFLAGS"
     have_cblocks=true
 ], [
@@ -61,6 +78,7 @@ AS_IF([test "x$dispatch_cv_cblocks" != "xno"], [
 ])
 AM_CONDITIONAL(HAVE_CBLOCKS, $have_cblocks)
 AC_SUBST([CBLOCKS_FLAGS])
+AM_CONDITIONAL([BUILD_OWN_BLOCKS_RUNTIME], [test "x$enable_embedded_blocks_runtime" = "xyes"])
 
 #
 # Because a different C++ compiler may be specified than C compiler, we have
@@ -82,24 +100,26 @@ AC_CACHE_CHECK([for C++ Blocks support], [dispatch_cv_cxxblocks], [
 AS_IF([test "x$dispatch_cv_cxxblocks" != "xno"], [
     CXXBLOCKS_FLAGS="$dispatch_cv_cxxblocks"
 
-    saveCXXFLAGS="$CXXFLAGS"
-    CXXFLAGS="$CXXFLAGS -fblocks -O0"
-    AC_MSG_CHECKING([whether additional libraries are required for the Blocks runtime])
-    AC_TRY_LINK([], [
-	^{ int j; j=0; }();
-    ], [
-	AC_MSG_RESULT([no]);
-    ], [
-      saveLIBS="$LIBS"
-      LIBS="$LIBS -lBlocksRuntime"
-      AC_TRY_LINK([], [
-	^{ int k; k=0; }();
-      ], [
-	AC_MSG_RESULT([-lBlocksRuntime])
-      ], [
-	AC_MSG_ERROR([can't find Blocks runtime])
-      ])
-    ])
+	AS_IF([test "x$enable_embedded_blocks_runtime" != "xyes"], [
+	    saveCXXFLAGS="$CXXFLAGS"
+	    CXXFLAGS="$CXXFLAGS -fblocks -O0"
+	    AC_MSG_CHECKING([whether additional libraries are required for the Blocks runtime])
+	    AC_TRY_LINK([], [
+		^{ int j; j=0; }();
+	    ], [
+		AC_MSG_RESULT([no]);
+	    ], [
+	      saveLIBS="$LIBS"
+	      LIBS="$LIBS -lBlocksRuntime"
+	      AC_TRY_LINK([], [
+		^{ int k; k=0; }();
+	      ], [
+		AC_MSG_RESULT([-lBlocksRuntime])
+	      ], [
+		AC_MSG_ERROR([can't find Blocks runtime])
+	      ])
+	    ])
+	])
     CXXFLAGS="$saveCXXFLAGS"
     have_cxxblocks=true
 ], [