buildlb.rst 9.31 KB
Newer Older
1
.. buildlb.rst:
2

3 4 5
##################
Build the Library 
##################
6

L.S. Cook's avatar
L.S. Cook committed
7 8 9 10
* :ref:`ubuntu`
* :ref:`centos`


11 12 13
Build Environments
==================

14
Release |release| of |project| supports Linux\*-based systems  
15 16 17 18 19 20 21
with the following packages and prerequisites: 

.. csv-table::
   :header: "Operating System", "Compiler", "Build System", "Status", "Additional Packages"
   :widths: 25, 15, 25, 20, 25
   :escape: ~

22
   CentOS 7.4 64-bit, GCC 4.8, CMake 3.4.3, supported, ``wget zlib-devel ncurses-libs ncurses-devel patch diffutils gcc-c++ make git perl-Data-Dumper`` 
23
   Ubuntu 16.04 or 18.04 (LTS) 64-bit, Clang 3.9, CMake 3.5.1 + GNU Make, supported, ``build-essential cmake clang-3.9 clang-format-3.9 git curl zlib1g zlib1g-dev libtinfo-dev unzip autoconf automake libtool``
24 25 26
   Clear Linux\* OS for Intel Architecture, Clang 5.0.1, CMake 3.10.2, experimental, bundles ``machine-learning-basic dev-utils python3-basic python-basic-dev``

Other configurations may work, but should be considered experimental with
L.S. Cook's avatar
L.S. Cook committed
27 28 29 30
limited support. On Ubuntu 16.04 with gcc-5.4.0 or clang-3.9, for example, we 
recommend adding ``-DNGRAPH_USE_PREBUILT_LLVM=TRUE`` to the cmake command in 
step 4 below. This fetches a pre-built tarball of LLVM+Clang from llvm.org, 
and it will substantially reduce build time.
31 32 33 34 35 36 37 38 39 40 41 42

If using ``gcc`` version 4.8, it may be necessary to add symlinks from ``gcc`` 
to ``gcc-4.8``, and from ``g++`` to ``g++-4.8``, in your :envvar:`PATH`, even 
if you explicitly specify the ``CMAKE_C_COMPILER`` and ``CMAKE_CXX_COMPILER`` 
flags when building. (**Do NOT** supply the ``-DNGRAPH_USE_PREBUILT_LLVM`` 
flag in this case, because the prebuilt tarball supplied on llvm.org is not 
compatible with a gcc 4.8-based build.)


Installation Steps
==================

43 44 45 46 47 48 49 50
.. important:: The default :program:`cmake` procedure (no build flags) will  
   install ``ngraph_dist`` to an OS-level location like ``/usr/bin/ngraph_dist``
   or ``/usr/lib/ngraph_dist``. Here we specify how to build locally to the
   location of ``~/ngraph_dist`` with the cmake target ``-DCMAKE_INSTALL_PREFIX=~/ngraph_dist``. 
   All of the nGraph Library documentation presumes that ``ngraph_dist`` 
   gets installed locally. The system location can be used just as easily by 
   customizing paths on that system. See the :file:`ngraph/CMakeLists.txt` 
   file to change or customize the default CMake procedure.
51

L.S. Cook's avatar
L.S. Cook committed
52
.. _ubuntu:
53

L.S. Cook's avatar
L.S. Cook committed
54 55
Ubuntu 16.04
-------------
56

57 58
The process documented here will work on Ubuntu\* 16.04 (LTS) or on Ubuntu 
18.04 (LTS).
59

60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76
#. (Optional) Create something like ``/opt/libraries`` and (with sudo), 
   give ownership of that directory to your user. Creating such a placeholder 
   can be useful if you'd like to have a local reference for APIs and 
   documentation, or if you are a developer who wants to experiment with 
   how to :doc:`../howto/execute` using resources available through the 
   code base.

   .. code-block:: console

      $ sudo mkdir -p /opt/libraries
      $ sudo chown -R username:username /opt/libraries
      $ cd /opt/libraries

#. Clone the `NervanaSystems` ``ngraph`` repo:

   .. code-block:: console

77
      $ git clone https://github.com/NervanaSystems/ngraph.git
78 79 80 81 82 83 84 85 86
      $ cd ngraph

#. Create a build directory outside of the ``ngraph/src`` directory 
   tree; somewhere like ``ngraph/build``, for example:

   .. code-block:: console

      $ mkdir build && cd build

L.S. Cook's avatar
L.S. Cook committed
87
#. Generate the GNU Makefiles in the customary manner (from within the 
88 89 90
   ``build`` directory). This command enables ONNX support in the library  
   and sets the target build location at ``~/ngraph_dist``, where it can be 
   found easily.  
91 92 93

   .. code-block:: console

94
      $ cmake .. -DNGRAPH_ONNX_IMPORT_ENABLE=ON  -DCMAKE_INSTALL_PREFIX=~/ngraph_dist
95 96 97 98

   **Other optional build flags** -- If running ``gcc-5.4.0`` or ``clang-3.9``, 
   remember that you can also append ``cmake`` with the prebuilt LLVM option 
   to speed-up the build.  Another option if your deployment system has Intel® 
99 100
   Advanced Vector Extensions (Intel® AVX) is to target the accelerations 
   available directly by compiling the build as follows during the cmake 
101 102
   step: ``-DNGRAPH_TARGET_ARCH=skylake-avx512``.  
   
103 104
   .. code-block:: console

105
      $ cmake .. [-DNGRAPH_USE_PREBUILT_LLVM=TRUE] [-DNGRAPH_TARGET_ARCH=skylake-avx512]   
106 107

#. Run ``$ make`` and ``make install`` to install ``libngraph.so`` and the 
108
   header files to ``~/ngraph_dist``:
109 110 111

   .. code-block:: console
      
112
      $ make   # note: make -j <N> may work, but sometimes results in out-of-memory errors if too many compilation processes are used
L.S. Cook's avatar
L.S. Cook committed
113
      $ make install          
114 115 116 117

#. (Optional, requires `doxygen`_, `Sphinx`_, and `breathe`_). Run ``make html`` 
   inside the ``doc/sphinx`` directory of the cloned source to build a copy of 
   the `website docs`_ locally. The low-level API docs with inheritance and 
L.S. Cook's avatar
L.S. Cook committed
118 119 120 121
   collaboration diagrams can be found inside the ``/docs/doxygen/`` directory. 
   See the :doc:`project/doc-contributor-README` for more details about how to 
   build documentation for nGraph. 

122

L.S. Cook's avatar
L.S. Cook committed
123
.. _centos: 
124

L.S. Cook's avatar
L.S. Cook committed
125 126
CentOS 7.4
-----------
127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156

The process documented here will work on CentOS 7.4.

#. (Optional) Create something like ``/opt/libraries`` and (with sudo), 
   give ownership of that directory to your user. Creating such a placeholder 
   can be useful if you'd like to have a local reference for APIs and 
   documentation, or if you are a developer who wants to experiment with 
   how to :doc:`../howto/execute` using resources available through the 
   code base.

   .. code-block:: console

      $ sudo mkdir -p /opt/libraries
      $ sudo chown -R username:username /opt/libraries

#. Update the system with :command:`yum` and issue the following commands: 
   
   .. code-block:: console

      $ sudo yum update
      $ sudo yum install zlib-devel install ncurses-libs ncurses-devel patch diffutils wget gcc-c++ make git perl-Data-Dumper


#. Install Cmake 3.4:

   .. code-block:: console
    
      $ wget https://cmake.org/files/v3.4/cmake-3.4.3.tar.gz      
      $ tar -xzvf cmake-3.4.3.tar.gz
      $ cd cmake-3.4.3
157 158
      $ ./bootstrap --system-curl --prefix=~/cmake
      $ make && make install     
159

160
#. Clone the `NervanaSystems` ``ngraph`` repo via HTTPS and use Cmake 3.4.3 to 
161 162
   build nGraph Libraries to ``~/ngraph_dist``. This command enables ONNX 
   support in the library (optional). 
163

164 165 166
   .. code-block:: console

      $ cd /opt/libraries 
167
      $ git clone https://github.com/NervanaSystems/ngraph.git
168
      $ cd ngraph && mkdir build && cd build
169
      $ ~/cmake/bin/cmake .. -DCMAKE_INSTALL_PREFIX=~/ngraph_dist -DNGRAPH_ONNX_IMPORT_ENABLE=ON 
170 171 172
      $ make && sudo make install 


173 174
macOS\* development
--------------------
175

L.S. Cook's avatar
L.S. Cook committed
176 177
.. note:: Although we do not currently offer full support for the macOS platform, 
   some configurations and features may work.
178 179 180 181 182 183 184 185 186 187

The repository includes two scripts (``maint/check-code-format.sh`` and 
``maint/apply-code-format.sh``) that are used respectively to check adherence 
to ``libngraph`` code formatting conventions, and to automatically reformat code 
according to those conventions. These scripts require the command 
``clang-format-3.9`` to be in your ``PATH``. Run the following commands 
(you will need to adjust them if you are not using bash):

.. code-block:: bash

188
   $ brew install llvm@3.9 automake
189 190 191 192 193
   $ mkdir -p $HOME/bin
   $ ln -s /usr/local/opt/llvm@3.9/bin/clang-format $HOME/bin/clang-format-3.9
   $ echo 'export PATH=$HOME/bin:$PATH' >> $HOME/.bash_profile


194 195
Testing the build 
=================
196 197

The |InG| library code base uses GoogleTest's\* `googletest framework`_ 
198
for unit tests. The ``cmake`` command from the :doc:`buildlb` guide 
199 200 201 202 203 204
automatically downloaded a copy of the needed ``gtest`` files when 
it configured the build directory.

To perform unit tests on the install:

#. Create and configure the build directory as described in our 
205
   :doc:`buildlb` guide.
206 207 208 209 210 211 212 213 214 215 216 217

#. Enter the build directory and run ``make check``:
   
   .. code-block:: console

      $ cd build/
      $ make check


Compile a framework with ``libngraph``
======================================

218
After building and installing nGraph on your system, there are two likely 
219
paths for what you'll want to do next: either compile a framework to run a DL 
220 221
training model, or load an import of an "already-trained" model for inference 
on an Intel nGraph-enabled backend.
222

223
For the former case, this early |version|, :doc:`framework-integration-guides`, 
224 225 226 227
can help you get started with a training a model on a supported framework. 

* :doc:`MXNet<framework-integration-guides>` framework,  
* :doc:`TensorFlow<framework-integration-guides>` framework, and
L.S. Cook's avatar
L.S. Cook committed
228 229
* :doc:`neon<framework-integration-guides>` framework,  

230 231 232 233 234 235

For the latter case, if you've followed a tutorial from `ONNX`_, and you have an 
exported, serialized model, you can skip the section on frameworks and go directly
to our :doc:`../howto/import` documentation. 

Please keep in mind that both of these are under continuous development, and will 
236
be updated frequently in the coming months. Stay tuned!  
237 238 239 240 241 242 243 244 245


.. _doxygen: https://www.stack.nl/~dimitri/doxygen/
.. _Sphinx:  http://www.sphinx-doc.org/en/stable/
.. _breathe: https://breathe.readthedocs.io/en/latest/
.. _llvm.org: https://www.llvm.org 
.. _NervanaSystems: https://github.com/NervanaSystems/ngraph/blob/master/README.md
.. _googletest framework: https://github.com/google/googletest.git
.. _ONNX: http://onnx.ai
246
.. _website docs: http://ngraph.nervanasys.com/docs/latest/