First try at "Building tips" documentation (JuliaPackaging#150)

* First try at "Building tips" documentation

The intent is to provide tips for common build scenarios. If common items keep appearing, they could be baked into the environment.

* Updates based on input from Elliot and David

docs/src/build_tips.md

@@ -0,0 +1,133 @@
+# Building tips
+
+BinaryBuilder provides a convenient environment to enable cross-platform building. But, many libraries have complicated build scripts that may need to be adapted to support all of the BinaryBuilder targets.
+
+*If you have additional tips, please submit a PR with suggestions.*
+
+## Initiating different shell commands based on target
+
+Sometimes, you need to adapt build scripts based on the target platform. This can be done within the shell script. Here is an example from [staticfloat/OpenBLASBuilder](https://github.com/staticfloat/OpenBLASBuilder/blob/master/build_tarballs.jl):
+
+```sh
+# Set BINARY=32 on i686 platforms and armv7l
+if [[ ${target} == i686* ]] || [[ ${target} == arm-* ]]; then
+    flags="${flags} BINARY=32"
+fi
+```
+
+Here are other examples of scripts with target-specific checks:
+
+* [davidanthoff/ReadStatBuilder](https://github.com/davidanthoff/ReadStatBuilder/blob/cc1745add155224ef1672e7a0013c4adb1df8141/build_tarballs.jl#L33) - windows check
+* [JuliaDiffEq/SundialsBuilder](https://github.com/JuliaDiffEq/SundialsBuilder/blob/6a155530557ac2c49277d33baf02f30921739348/build_tarballs.jl#L125-L131) - 32-bit check
+
+It is also possible to run quite different scripts for each target by running different build scripts for different sets of targets. Here is an example where windows builds are separated from other targets:
+
+* [Keno/ZlibBuilder](https://github.com/Keno/ZlibBuilder/blob/master/build_tarballs.jl)
+
+## Autoconfigure builds
+
+Autoconfigure builds are generally quite straightforward. Here is a typical approach:
+
+```sh
+./configure --prefix=$prefix --host=${target}
+make -j${nproc}
+make install
+```
+
+Here are examples of autoconfigure build scripts:
+
+* [staticfloat/OggBuilder](https://github.com/staticfloat/OggBuilder/blob/master/build_tarballs.jl)
+* [staticfloat/NettleBuilder](https://github.com/staticfloat/NettleBuilder/blob/master/build_tarballs.jl)
+
+
+## CMake builds
+
+For CMake, the wizard will suggest a template for running CMake. Typically, this will look like:
+
+```sh
+make -DCMAKE_INSTALL_PREFIX=$prefix -DCMAKE_TOOLCHAIN_FILE=/opt/$target/$target.toolchain
+```
+
+The toolchain file sets up several CMake environment variables for better cross-platform support: 
+
+```sh
+# Toolchain file for x86_64-linux-gnu
+set(CMAKE_SYSTEM_NAME Linux)
+
+set(CMAKE_SYSROOT /opt/x86_64-linux-gnu/x86_64-linux-gnu/sys-root/)
+set(CMAKE_INSTALL_PREFIX /)
+
+set(CMAKE_C_COMPILER /opt/x86_64-linux-gnu/bin/x86_64-linux-gnu-gcc)
+set(CMAKE_CXX_COMPILER /opt/x86_64-linux-gnu/bin/x86_64-linux-gnu-g++)
+
+set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER)
+set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)
+set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)
+set(CMAKE_FIND_ROOT_PATH_MODE_PACKAGE ONLY)
+```
+
+Examples of builds that include CMake parts include:
+
+* [staticfloat/IpoptBuilder](https://github.com/staticfloat/IpoptBuilder/blob/master/build_tarballs.jl)
+
+* [davidanthoff/SnappyBuilder](https://github.com/davidanthoff/SnappyBuilder/blob/master/build_tarballs.jl)
+
+* [JuliaDiffEq/SundialsBuilder](https://github.com/JuliaDiffEq/SundialsBuilder/blob/master/build_tarballs.jl)
+  - Needs `-DSUNDIALS_INDEX_TYPE=int32_t` on 32-bit targets (Sundials-specific way to specify integer size)
+  - Needs to copy *.dll files from `destdir/lib` to `destdir/bin` for windows; this also removes symlinks by using `cp -L`
+  - Needs `-DCMAKE_FIND_ROOT_PATH="$WORKSPACE/destdir"`, so CMake's `find_library` can find libraries from KLU
+
+
+## Builds with binary dependencies
+
+A build script can depend on binaries generated by another Builder repository. A builder specifies `dependencies` like:
+
+```julia
+dependencies = [
+    # We need libogg to build FLAC
+    "https://github.com/staticfloat/OggBuilder/releases/download/v1.3.3-0/build.jl"
+]
+```
+
+Each of the `dependencies` points to a `build.jl` file, usually provided with a release of another Builder repository.
+
+In the wizard, this can be specified with the prompt: *Do you require any (binary) dependencies?  [y/N]*.
+
+Examples of builders that depend on other binaries include:
+
+* [staticfloat/FLACBuilder](https://github.com/staticfloat/FLACBuilder/blob/master/build_tarballs.jl) depends on [staticfloat/OggBuilder](https://github.com/staticfloat/OggBuilder/blob/master/build_tarballs.jl) ([build.jl](https://github.com/staticfloat/OggBuilder/releases/download/v1.3.3-0/build.jl)).
+
+
+## Editing files in the wizard
+
+In the wizard, the `vi` editor is available for editing files. But, it doesn't leave any record in the build script. One generally needs to provide patch files or sue something like `sed`. Here is an approach using `diff` and `patch`:
+
+```sh
+cp file.ext file.ext.orig
+vi file.ext     # make the changes
+diff -u file.ext.orig file.ext
+# Create a patch based on the results copy-pasted from the output of `diff`
+cat > file.patch <<'END'
+--- file.ext.orig 2017-12-14 19:28:48.816021000 -0500
++++ file.ext2017-12-14 19:29:03.912021000 -0500
+@@ -1,4 +1,5 @@
+ -https://computation.llnl.gov/projects/sundials/download/sundials-3.0.0.tar.gz
+ +https://computation.llnl.gov/projects/sundials/download/sundials-3.1.0.tar.gz
+  
+  http://faculty.cse.tamu.edu/davis/SuiteSparse/SuiteSparse-5.0.0.tar.gz
+ 
+END
+# Apply the patch
+patch -l file.ext.orig file.patch -o file.ext
+```
+
+There are plans to handle file changes in the wizard automatically [(#25)](https://github.com/JuliaPackaging/BinaryBuilder.jl/issues/125).
+
+
+## Other examples
+
+Examples of other interesting builders include:
+
+* [Keno/LinuxBuilder](https://github.com/Keno/LinuxBuilder/blob/master/build_tarballs.jl) -- Why not build Linux?
+
+