Merge pull request #104 from htgoebel/master

Add some information to the README and description to the script

README.md

@@ -7,14 +7,26 @@ Linux, *BSD, and Cygwin.
 
 ### HOW DOES IT WORK? ###
 
-[Clang/LLVM is a cross compiler by default](http://clang.llvm.org/docs/CrossCompilation.html)
-and is now available on nearly every Linux distribution,
-so we just need a proper
-[port](https://github.com/tpoechtrager/cctools-port)
-of the [cctools](http://www.opensource.apple.com/tarballs/cctools)
-(ld, lipo, ...) and the OS X SDK.
+For cross-compiling for OS X you need
+* the Clang/LLVM compiler
+* the the [cctools](http://www.opensource.apple.com/tarballs/cctools)
+  (ld, lipo, …), and
+* the OSX SDK.
+
+[Clang/LLVM is a cross compiler by default](http://clang.llvm.org/docs/CrossCompilation.html)
+and is now available on nearly every Linux distribution, so we just
+need a proper [port](https://github.com/tpoechtrager/cctools-port) of
+the cctools and the OS X SDK.
+
+OSXCross includes a collection of scripts for preparing the SDK and
+building the cctools.
+
+It also includes scripts for optionally building
+* Clang using gcc (for the case your distribution does not include it),
+* an up-to-date vanilla GCC as a cross-compiler for target OS X,
+* the "compiler-rt" runtime library, and
+* the `llvm-dsymutil` tool required for debugging.
 
-If you want, then you can build an up-to-date vanilla GCC as well.
 
 ### WHAT CAN I BUILD WITH IT? ###
 
@@ -38,17 +50,18 @@ Then ensure you have the following installed on your system:
 
 `Clang 3.2+`, `patch`, `libxml2-devel` (<=10.6 only) and the `bash shell`.
 
+You can run 'sudo tools/get\_dependencies.sh' to get these (and the
+optional packages) automatically.
+
 *Optional:*
 
-`llvm-devel`: For Link Time Optimization support
-`uuid-devel`: For ld64 `-random_uuid` support
-`llvm-devel` + `xar-devel`: For ld64 `-bitcode_bundle` support
+- `llvm-devel`: For Link Time Optimization support
+- `uuid-devel`: For ld64 `-random_uuid` support
+- `llvm-devel` + `xar-devel`: For ld64 `-bitcode_bundle` support
 
 You can find xar [here](https://github.com/mackyle/xar).
 Do not install libxar-dev on Ubuntu, it's a different package.
 
-\--
-You can run 'sudo tools/get\_dependencies.sh' to get these automatically.
 
 ##### Building Clang #####
 

build.sh

@@ -1,4 +1,10 @@
 #!/usr/bin/env bash
+#
+# Build and install the cctools the SDK and macports.
+#
+# This script requires the OS X SDK and the Clang/LLVM compiler.
+#
+
 
 pushd "${0%/*}" &>/dev/null
 

build_binutils.sh

@@ -1,4 +1,11 @@
 #!/usr/bin/env bash
+#
+# Build and install the GNU binutils and the GNU Debugger (gdb) for
+# target OS X.
+#
+# You may want to run this script if you want to build software using
+# gcc. Please refer to the README.md for details.
+#
 
 pushd "${0%/*}" &>/dev/null
 

build_clang.sh

@@ -1,4 +1,11 @@
 #!/usr/bin/env bash
+#
+# Build and install Clang/LLVM, using `gcc`.
+#
+# You only need to run this if your distribution does not provide
+# clang - or if you want to build your own version from a recent
+# source tree.
+#
 
 pushd "${0%/*}" &>/dev/null
 

build_compiler_rt.sh

@@ -1,4 +1,10 @@
 #!/usr/bin/env bash
+#
+# Build and install the "compiler-rt" runtime library.
+#
+# This requires that you already finished `build.sh`.
+# Please refer to README.COMPILER-RT.md for details.
+#
 
 pushd "${0%/*}" &>/dev/null
 

build_gcc.sh

@@ -1,4 +1,11 @@
 #!/usr/bin/env bash
+#
+# Build and install gcc/gcc++ as a cross-compiler with target OSX,
+# using `clang`.
+#
+# You may want to run this script if you want to build software using
+# gcc. Please refer to the README.md for details.
+#
 
 pushd "${0%/*}" &>/dev/null
 

build_llvm_dsymutil.sh

@@ -1,4 +1,9 @@
 #!/usr/bin/env bash
+#
+# Build and install the `llvm-dsymutil` tool required for debugging.
+#
+# Please refer to README.DEBUGGING.md for details.
+#
 
 pushd "${0%/*}" &>/dev/null
 

tools/gen_cyglto_dll.sh

@@ -1,4 +1,8 @@
 #!/usr/bin/env bash
+#
+# Build and install the LTO library, which the Cygwin package of
+# libLLVM is lacking.
+#
 
 pushd "${0%/*}/.." &>/dev/null
 source tools/tools.sh

tools/gen_sdk_package.sh

@@ -1,5 +1,7 @@
 #!/usr/bin/env bash
-# OS X SDK packaging script
+#
+# Package the OS X SDKs into a tar file to be used by `build.sh`.
+#
 
 export LC_ALL=C
 

tools/gen_sdk_package_darling_dmg.sh

@@ -1,4 +1,13 @@
 #!/usr/bin/env bash
+#
+# Mount a Xcode .dmg (using fuse) and run gen_sdk_package.sh.
+#
+# Works up to Xcode 7.3
+#
+# This script uses darling-dmg and fuse to mount the .dmg, thus
+# avoiding to actually unpack it.
+# darling-dmg will be downloaded and compiled if missing.
+#
 
 pushd "${0%/*}/.." &>/dev/null
 source tools/tools.sh

tools/gen_sdk_package_p7zip.sh

@@ -1,4 +1,12 @@
 #!/usr/bin/env bash
+#
+# Extract required files from a Xcode .dmg using p7zip and run
+# gen_sdk_package.sh.
+#
+# Works up to Xcode 7.2
+#
+# p7zip will be downloaded and compiled if missing.
+#
 
 pushd "${0%/*}/.." &>/dev/null
 source tools/tools.sh

tools/mount_xcode_image.sh

@@ -1,4 +1,9 @@
 #!/usr/bin/env bash
+#
+# Mount a Xcode .dmg (requires root) and run gen_sdk_package.sh.
+#
+# Works up to Xcode 4.2
+#
 
 if [ $(uname -s) != "Linux" ]; then
   echo "This script must be run on Linux"