Update unix-instructions.md

Merge in the OpenSSL installation instructions from coreclr, and restructure the document a bit to improve clarity.

1 files changed, 49 insertions, 33 deletions

diff --git a/Documentation/building/unix-instructions.md b/Documentation/building/unix-instructions.md
index f25bf03486..a0608b3348 100644
--- a/Documentation/building/unix-instructions.md
+++ b/Documentation/building/unix-instructions.md
@@ -1,12 +1,22 @@
 Building CoreFX on FreeBSD, Linux and OS X
 ==========================================
-###Building
+##Building
+
+1. Install the prerequisites ([Linux](#user-content-linux), [macOS](#user-content-macos))
+2. Clone the corefx repo `git clone https://github.com/dotnet/corefx.git`
+3. Navigate to the `corefx` directory
+4. Run the build script `./build.sh`
+
 Calling the script `build.sh` builds both the native and managed code.
 Only use it when the parameters that you are passing to the script apply for both components. Otherwise, use the scripts `build-native.sh` and `build-managed.sh` respectively.
 
 For more information about the different options when building, run `build.sh -?` and look at examples in the [developer-guide](../project-docs/developer-guide.md).
 
-### Prerequisites (native build)
+## Prerequisites (native build)
+
+### Linux
+
+#### Native build
 
 For Ubuntu 14.04, the following packages should be installed to build the native
 components
@@ -24,24 +34,7 @@ components
 `sudo apt-get install git clang-3.5 cmake make libc6-dev libssl-dev libkrb5-dev
 libcurl4-openssl-dev zlib1g-dev`
 
-On OS X, all the needed libraries are provided by XCode, with the exception of
-openssl. To install openssl, we recommend that you use
-[Homebrew](http://brew.sh) and do the following:
-
-```
-brew install openssl
-brew link --force openssl
-```
-
-Once installed, the native components can be built by running:
-
-```bash
-./build-native.sh
-```
-
-from the root of the repository.
-
-### Prerequisites (managed build)
+#### Managed build
 
 For Ubuntu 14.04, install the following packages:
 
@@ -55,12 +48,44 @@ In addition to the above packages, the runtime versions of the packages listed
 in the native section should also be installed (this happens automatically on
 most systems when you install the development packages).
 
-On OS X, we also require that openssl has been installed via [Homebrew](http://brew.sh).
+### macOS
 
-Once installed, the managed components can be built by running:
+On macOS a few components are needed which are not provided by a default developer setup:
+* CMake
+* pkgconfig
+* OpenSSL 1.0.1 or 1.0.2
+
+One way of obtaining these components is via [Homebrew](http://brew.sh):
+```sh
+$ brew install cmake pkgconfig openssl
+```
 
-```bash
-./build-managed.sh
+As of El Capitan (OS X 10.11), Apple still has the libraries for OpenSSL 0.9.8 in `/usr/lib`,
+but the headers are no longer available since that library version is out of support.
+Some compilers get upset over new headers being in `/usr/local/include` with the old library being present at
+`/usr/lib/libcrypto.dylib` (the tools have no issue with the versioned files, e.g. `/usr/lib/libcrypto.0.9.8.dylib`),
+and so Homebrew does not allow the OpenSSL package to be installed into system default paths. A minimal installation
+is presented here to facilitiate simplifying runtime requirements and compile-time requirements (for build systems using
+CMake's `find_package`, like ours):
+```sh
+# We need to make the runtime libraries discoverable, as well as make
+# pkg-config be able to find the headers and current ABI version.
+#
+# Ensure the paths we will need exist
+mkdir -p /usr/local/lib/pkgconfig
+
+# The rest of these instructions assume a default Homebrew path of
+# /usr/local/opt/<module>, with /usr/local being the answer to
+# `brew --prefix`.
+#
+# Runtime dependencies
+ln -s /usr/local/opt/openssl/lib/libcrypto.1.0.0.dylib /usr/local/lib/
+ln -s /usr/local/opt/openssl/lib/libssl.1.0.0.dylib /usr/local/lib/
+
+# Compile-time dependencies (for pkg-config)
+ln -s /usr/local/opt/openssl/lib/pkgconfig/libcrypto.pc /usr/local/lib/pkgconfig/
+ln -s /usr/local/opt/openssl/lib/pkgconfig/libssl.pc /usr/local/lib/pkgconfig/
+ln -s /usr/local/opt/openssl/lib/pkgconfig/openssl.pc /usr/local/lib/pkgconfig/
 ```
 
 ### Known Issues
@@ -70,12 +95,3 @@ If you see errors along the lines of `SendFailure (Error writing headers)` you m
 mozroots --import --sync
 ```
 
-## Steps to build on Ubuntu 14.04 LTS
-
-
-1. Install the prerequisites
- * `sudo apt-get install git clang-3.5 cmake make libc6-dev libssl-dev
-   libkrb5-dev libcurl4-openssl-dev zlib1g-dev libunwind8 libicu52 curl`
-2. Clone the corefx repo `git clone https://github.com/dotnet/corefx.git`
-3. Navigate to the `corefx` directory
-4. Run the build script `./build.sh`