diff --git a/docs/gsg/build.rst b/docs/gsg/build.rst index c922770..475ea86 100644 --- a/docs/gsg/build.rst +++ b/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`_ instead of using system packages. - -.. note:: - - A small daemon is required to "pin" GPU's interrupts to specific cores. - See details in `our gist `_. +**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 `_ 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 `_ instead of using system packages. + +.. note:: + + A small daemon is required to "pin" GPU's interrupts to specific cores. + See details in `our gist `_. + +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.