refs #2: Clean up build docs.

docs/gsg/build.rst

@@ -1,30 +1,24 @@
 Building NBA
 ============
 
-We recommend to use Ubuntu 14.04 or newer.  
+We recommend to use Ubuntu 14.04 or newer.
 
 Supported Platforms
 -------------------
 
+Currently NBA is only tested on Linux x86_64 3.10 or newer kernels,
+and the Ubuntu 14.04 LTS distribution.
+
 Step-by-step Guide for Ubuntu 14.04 LTS
 ---------------------------------------
 
-** Package and software to install **
-
-* NVIDIA CUDA 7.0 or newer
-  - We recommend to download the latest version of `.bin` package from `the NVIDIA website<https://developer.nvidia.com/cuda-downloads>`_ instead of using system packages.
-
-.. note::
-
-  A small daemon is required to "pin" GPU's interrupts to specific cores.  
-  See details in `our gist <https://gist.github.com/3404967>`_.
+**Software packages to install**
 
-  - Add `export PATH=$PATH:/usr/local/cuda/bin` to `/etc/profile` or similar places.
-  - Add `/usr/local/cuda/lib64` to `/etc/ld.so.conf.d/cuda.conf` (create if not exists) and run `ldconfig`.
+Ensure that you have a C/C++ compiler (e.g., g++ 4.8 or newer).
+The compiler must support the C++11 standard.
 
-* g++ 4.8 or newer (the compiler must support C++11 standard.)
+Check out the latest DPDK source tree:
 
-* Intel DPDK 1.8
 .. code-block:: console
 
    ~$ git clone git://dpdk.org/dpdk
@@ -35,48 +29,88 @@ Step-by-step Guide for Ubuntu 14.04 LTS
 
    You need to install the kernel header/source packages first.
 
-* Python 3.4 or newer
+Install Python 3.4 on your system.
+You may use the system package manager such as :code:`apt-get`.
+In that case, ensure that you also have development package as well:
+
+.. code-block:: console
+
+  $ sudo apt-get install python3.4 libpython3.4-dev
+
+Then install our Python dependencies:
 
 .. code-block:: console
 
-  pip install snakemake
-  apt-get install libpython3-dev
+  $ pip3 install --user snakemake
 
 .. note::
 
    We recommend using a separate Python environment contained inside the user directory.
-   See pyenv for more details.
+   See `pyenv <https://github.com/yyuu/pyenv>`_ for more details.
+
+Clone the project source code:
+
+.. code-block:: console
+
+   ~$ git clone https://github.com/anlab-kaist/NBA nba
+
+Install our 3rd-party libraries, the Click configuration parser:
+
+.. code-block:: console
+
+   ~$ cd nba
+   ~/nba$ git submodule init && git submodule update
+
+.. note::
 
-* Click configuration parser
-  - Just run `git submodule init && git submodule update`
-  - It will be *automatically built* along with NBA when you first build NBA.
+   It will be *automatically built* along with NBA when you first build NBA.
 
-* `sysstat` package (or any package that offers `mpstat` command) to run experiment scripts
 
-** Compilation **
+**Compilation**
 
 * Set the environment variable as follows:
 
 .. code-block:: console
 
-  $ export NBA_DPDK_PATH=/home/userid/dpdk/x86_64-native-linuxapp-gcc
-  $ snakemake
+  ~/nba$ export NBA_DPDK_PATH=/home/userid/dpdk/x86_64-native-linuxapp-gcc
+  ~/nba$ snakemake
 
 * If all is well, the executable is located in `bin/main`.
 
+**Optional installation**
+
+If you want to use GPU acceleration, install NVIDIA CUDA 7.0 or newer.
+We recommend to download the latest version of :code:`.bin` package from `the NVIDIA website <https://developer.nvidia.com/cuda-downloads>`_ instead of using system packages.
+
+.. note::
+
+  A small daemon is required to "pin" GPU's interrupts to specific cores.
+  See details in `our gist <https://gist.github.com/3404967>`_.
+
+Make CUDA binaries accessible from your shell:
+
+.. code-block:: console
+
+  $ echo 'export PATH="$PATH:/usr/local/cuda/bin"' >> ~/.profile
+  $ sudo sh -c 'echo /usr/local/cuda/lib64 > /etc/ld.so.conf.d/cuda.conf'
+  $ sudo ldconfig
+
+To run experiment scripts, install :code:`sysstat` package (or any package that offers :code:`mpstat` command).
+
+
 Customizing Your Build
 ----------------------
 
 Our build script offers a few configurable parameters as environment variables:
 
-* `NBA_DPDK_PATH`: specifies the path to Intel DPDK (required)
-* `NBA_RANDOM_PORT_ACCESS`: randomizes the RX queue scanning order for each worker thread (default: false)
-* `NBA_OPENSSL_PATH`: specifies the path of OpenSSL library (default: /usr)
-* `USE_CUDA`: activates NVIDIA CUDA support (default: true)
-* `USE_PHI`: activates Intel Xeon Phi support (default: false, not fully implemented yet)
-* `USE_NVPROF`: activates nvprof API calls to track GPU-related timings (default: false)
-* `USE_OPENSSL_EVP`: determines whether to use EVP API for OpenSSL that enables AES-NI support (default: true)
-* `NBA_NO_HUGE`: determines whether to use huge-pages (default: true)
-* `NBA_PMD`: determines what poll-mode driver to use (default: ixgbe)
+* :code:`NBA_DPDK_PATH`: specifies the path to Intel DPDK (required)
+* :code:`NBA_RANDOM_PORT_ACCESS`: randomizes the RX queue scanning order for each worker thread (default: false)
+* :code:`NBA_OPENSSL_PATH`: specifies the path of OpenSSL library (default: /usr)
+* :code:`USE_CUDA`: activates NVIDIA CUDA support (default: true)
+* :code:`USE_PHI`: activates Intel Xeon Phi support (default: false, not fully implemented yet)
+* :code:`USE_NVPROF`: activates nvprof API calls to track GPU-related timings (default: false)
+* :code:`USE_OPENSSL_EVP`: determines whether to use EVP API for OpenSSL that enables AES-NI support (default: true)
+* :code:`NBA_NO_HUGE`: determines whether to use huge-pages (default: true)
+* :code:`NBA_PMD`: determines what poll-mode driver to use (default: ixgbe)
 
 ※ Boolean variables are expressed as 1 or 0.