Merge pull request #946 from bobsummerwill/build_from_source_docs

Updated Solidity documentation's "building from source" section

1 files changed, 116 insertions, 67 deletions

diff --git a/docs/installing-solidity.rst b/docs/installing-solidity.rst
index ba40c99f..e500717b 100644
--- a/docs/installing-solidity.rst
+++ b/docs/installing-solidity.rst
@@ -8,8 +8,10 @@ Browser-Solidity
 If you just want to try Solidity for small contracts, you
 can try `browser-solidity <https://ethereum.github.io/browser-solidity>`_
 which does not need any installation. If you want to use it
-without connection to the Internet, you can also just save the page
-locally or clone http://github.com/ethereum/browser-solidity.
+without connection to the Internet, you can go to
+https://github.com/ethereum/browser-solidity/tree/gh-pages and
+download the .ZIP file as explained on that page.
+
 
 npm / Node.js
 =============
@@ -22,7 +24,7 @@ package available.
 
 To install it, simply use
 
-::
+.. code:: bash
 
     npm install solc
 
@@ -32,102 +34,149 @@ Details about the usage of the Node.js package can be found in the
 Binary Packages
 ===============
 
-Binary packages of Solidity together with its IDE Mix are available through
-the `C++ bundle <https://github.com/ethereum/webthree-umbrella/releases>`_ of
-Ethereum.
+Binary packages of Solidity available at
+`solidity/releases <https://github.com/ethereum/solidity/releases>`_.
 
-Building from Source
-====================
+We also have PPAs for Ubuntu.  For the latest stable version.
 
-Building Solidity is quite similar on MacOS X, Ubuntu and probably other Unices.
-This guide starts explaining how to install the dependencies for each platform
-and then shows how to build Solidity itself.
+.. code:: bash
 
-MacOS X
--------
+    sudo add-apt-repository ppa:ethereum/ethereum
+    sudo apt-get update
+    sudo apt-get install solc
 
+If you want to use the cutting edge developer version:
 
-Requirements:
+.. code:: bash
 
-- OS X Yosemite (10.10.5)
-- Homebrew
-- Xcode
+    sudo add-apt-repository ppa:ethereum/ethereum
+    sudo add-apt-repository ppa:ethereum/ethereum-dev
+    sudo apt-get update
+    sudo apt-get install solc
 
-Set up Homebrew:
+Homebrew is missing pre-built bottles at the time of writing,
+following a Jenkins to TravisCI migration, but Homebrew
+should still work just fine as a means to build-from-source.
+We will re-add the pre-built bottles soon.
 
-.. code-block:: bash
+.. code:: bash
 
     brew update
     brew upgrade
+    brew tap ethereum/ethereum
+    brew install solidity
+    brew linkapps solidity
 
-    brew install boost --c++11             # this takes a while
-    brew install cmake cryptopp gmp jsoncpp
 
-Ubuntu Trusty (14.04)
----------------------
+Building from Source
+====================
+
+Clone the Repository
+--------------------
+
+To clone the source code, execute the following command:
+
+.. code:: bash
+
+    git clone --recursive https://github.com/ethereum/solidity.git
+    cd solidity
+
+If you want to help developing Solidity,
+you should fork Solidity and add your personal fork as a second remote:
+
+.. code:: bash
+
+    cd solidity
+    git remote add personal git@github.com:[username]/solidity.git
+
 
-Below are the instructions to install the minimal dependencies required
-to compile Solidity on Ubuntu 14.04 (Trusty Tahr).
+Prerequisites - macOS
+----------------------
 
-.. code-block:: bash
+For macOS, ensure that you have the latest version of
+`xcode installed <https://developer.apple.com/xcode/download/>`_.
+This contains the `Clang C++ compiler <https://en.wikipedia.org/wiki/Clang>`_, the
+`xcode IDE <https://en.wikipedia.org/wiki/Xcode>`_ and other Apple development
+tools which are required for building C++ applications on OS X.
+If you are installing xcode for the first time, or have just installed a new
+version then you will need to agree to the license before you can do
+command-line builds:
 
-    sudo apt-get -y install build-essential git cmake libgmp-dev libboost-all-dev \
-        libjsoncpp-dev
+.. code:: bash
 
-    sudo add-apt-repository -y ppa:ethereum/ethereum
-    sudo add-apt-repository -y ppa:ethereum/ethereum-dev
-    sudo apt-get -y update
-    sudo apt-get -y upgrade # this will update cmake to version 3.x
-    sudo apt-get -y install libcryptopp-dev libjsoncpp-dev
+    sudo xcodebuild -license accept
 
-Ubuntu Xenial (16.04)
+Our OS X builds require you to `install the Homebrew <http://brew.sh>`_
+package manager for installing external dependencies.
+Here's how to `uninstall Homebrew
+<https://github.com/Homebrew/homebrew/blob/master/share/doc/homebrew/FAQ.md#how-do-i-uninstall-homebrew>`_,
+if you ever want to start again from scratch.
+
+
+Prerequisites - Windows
+------------------------
+
+You will need to install the following dependencies for Windows builds of Solidity:
+
++------------------------------+-------------------------------------------------------+
+| Software                     | Notes                                                 |
++==============================+=======================================================+
+| `Git for Windows`_           | Command-line tool for retrieving source from Github.  |
++------------------------------+-------------------------------------------------------+
+| `CMake`_                     | Cross-platform build file generator.                  |
++------------------------------+-------------------------------------------------------+
+| `Visual Studio 2015`_        | C++ compiler and dev environment.                     |
++------------------------------+-------------------------------------------------------+
+
+.. _Git for Windows: https://git-scm.com/download/win
+.. _CMake: https://cmake.org/download/
+.. _Visual Studio 2015: https://www.visualstudio.com/products/vs-2015-product-editions
+
+
+External Dependencies
 ---------------------
 
-Below are the instructions to install the minimal dependencies required
-to compile Solidity on Ubuntu 16.04 (Xenial Xerus).
+We now have a "one button" script which installs all required external dependencies
+on macOS, Windows and on numerous Linux distros.  This used to be a multi-step
+manual process, but is now a one-liner:
 
-One of the dependencies (Crypto++ Library, with version >= 5.6.2) can be
-installed either by adding the Ethereum PPA (Option 1) or by backporting
-``libcrypto++`` from Ubuntu Development to Ubuntu Xenial (Option 2).
+.. code:: bash
 
-.. code-block:: bash
+    ./scripts/install_deps.sh
 
-    sudo apt-get -y install build-essential git cmake libgmp-dev libboost-all-dev \
-        libjsoncpp-dev
+Or, on Windows:
 
-    # (Option 1) For those willing to add the Ethereum PPA:
-    sudo add-apt-repository -y ppa:ethereum/ethereum
-    sudo add-apt-repository -y ppa:ethereum/ethereum-dev
-    sudo apt-get -y update
-    sudo apt-get -y upgrade
-    sudo apt-get -y install libcryptopp-dev
+.. code:: bash
 
-    ## (Option 2) For those willing to backport libcrypto++:
-    #sudo apt-get -y install ubuntu-dev-tools
-    #sudo pbuilder create
-    #mkdir ubuntu
-    #cd ubuntu
-    #backportpackage --workdir=. --build --dont-sign libcrypto++
-    #sudo dpkg -i buildresult/libcrypto++6_*.deb buildresult/libcrypto++-dev_*.deb
-    #cd ..
+    scripts\install_deps.bat
 
-Building
---------
 
-Run this if you plan on installing Solidity only:
+Command-Line Build
+------------------
 
-.. code-block:: bash
+Building Solidity is quite similar on Linux, macOS and other Unices:
+
+.. code:: bash
 
-    git clone --recursive https://github.com/ethereum/solidity.git
-    cd solidity
     mkdir build
     cd build
     cmake .. && make
 
-If you want to help developing Solidity,
-you should fork Solidity and add your personal fork as a second remote:
+And even on Windows:
 
-.. code-block:: bash
+.. code:: bash
 
-    cd solidity
-    git remote add personal git@github.com:username/solidity.git
+    mkdir build
+    cd build
+    cmake -G "Visual Studio 14 2015 Win64" ..
+
+This latter set of instructions should result in the creation of
+**solidity.sln** in that build directory.  Double-clicking on that file
+should result in Visual Studio firing up.  We suggest building
+**RelWithDebugInfo** configuration, but all others work.
+
+Alternatively, you can build for Windows on the command-line, like so:
+
+.. code:: bash
+
+    cmake --build . --config RelWithDebInfo