Installation of Nanos6
=======================
.. index::
double: Nanos6; installation
Nanos6 is a runtime that implements the OmpSs-2 parallel programming
model, developed by the `Programming Models group `__ at
the `Barcelona Supercomputing Center `__.
Nanos6 can be obtained from the `GitHub public repository `__
or by contacting us at pm-tools@bsc.es.
Build requirements
------------------
.. index::
double: Nanos6; build requirements
To install Nanos6 the following tools and libraries must be installed:
1. automake, autoconf, libtool, pkg-config, make and a C and C++ compiler
2. `boost `__ >= 1.59
3. `hwloc `__
4. `numactl `__
Optional libraries and tools
----------------------------
.. index::
double: Nanos6; optional build requirements
In addition to the build requirements, the following libraries and tools enable additional features:
1. `Extrae `__ to generate execution traces for offline performance analysis with `Paraver `__
2. `CUDA `__ to enable CUDA tasks
3. `PGI or NVIDIA HPC-SDK `__ to enable OpenACC tasks
4. `PAPI `__ to generate real-time statistics of hardware counters
5. `PQOS `__ to generate real-time statistics of hardware counters
6. `DLB `__ to enable dynamic management and sharing of computing resources
7. `jemalloc `__ to use jemalloc as the default memory allocator, providing better performance than the default glibc implementation. Jemalloc software must be compiled with ``--enable-stats`` and ``--with-jemalloc-prefix=nanos6_je_`` to link with the runtime
8. `ovni `__ to generate execution traces for performance analysis with `Paraver `__
.. nanos6-build-procedure:
Build procedure
---------------
.. index::
double: Nanos6; build procedure
Nanos6 uses the standard GNU automake and libtool toolchain. When cloning from
a repository, the building environment must be prepared through the command
below. When the code is distributed through a tarball, it usually does not need
that command.
.. code:: sh
$ ./autogen.sh
.. note::
The ``autogen.sh`` script was recently introduced. Please use this script instead
of the ``autoreconf`` command; otherwise the autotools configuration will fail.
Then execute the following commands:
.. code:: sh
$ ./configure --prefix=$INSTALLATION_PREFIX ...other options...
$ make
$ make install
where ``$INSTALLATION_PREFIX`` is the directory into which to install Nanos6.
The configure script accepts the following options:
1. ``--with-nanos6-clang=prefix`` to specify the prefix of the LLVM/Clang installation that supports OmpSs-2
2. ``--with-nanos6-mercurium=prefix`` to specify the prefix of the Mercurium installation
3. ``--with-boost=prefix`` to specify the prefix of the Boost installation
4. ``--with-papi=prefix`` to specify the prefix of the PAPI installation
5. ``--with-libnuma=prefix`` to specify the prefix of the numactl installation
6. ``--with-extrae=prefix`` to specify the prefix of the extrae installation
7. ``--with-dlb=prefix`` to specify the prefix of the DLB installation
8. ``--with-papi=prefix`` to specify the prefix of the PAPI installation
9. ``--with-pqos=prefix`` to specify the prefix of the PQoS installation
10. ``--with-cuda[=prefix]`` to enable support for CUDA tasks
11. ``--enable-openacc`` to enable support for OpenACC tasks; requires PGI compilers
12. ``--with-pgi=prefix`` to specify the prefix of the PGI compilers installation, in case they are not in ``$PATH``
13. ``--enable-monitoring`` to enable monitoring and predictions of task/CPU/thread statistics
14. ``--enable-chrono-arch`` to enable an architecture-based timer for the monitoring infrastructure
15. ``--with-ovni=prefix`` to specify the prefix of the ovni installation and enable the ovni instrumentation
The hwloc dependency is mandatory, and, by default, an internal hwloc is embedded
to the Nanos6 library. This behavior can be modified through the `--with-hwloc`
option, which can take the following values:
* ``--with-hwloc=embedded``: The hwloc is built and embedded into the Nanos6 library
as an internal module. This is useful when user programs may have third-party
software (e.g., MPI libraries) that depend on a different hwloc version and may
conflict with the one used by Nanos6. In this way, the hwloc library is internal
and is only used by Nanos6. This is the **default** behavior if the option is not
present, or no value is provided. See :ref:`nanos6-build-embedding` for
more information
* ``--with-hwloc=pkgconfig``: The hwloc is an external installation and Nanos6
should discover it through the pkg-config tool. Make sure to set the
``PKG_CONFIG_PATH`` if the hwloc is not installed in non-standard directories
* ``--with-hwloc=``: A prefix of an external hwloc installation
The jemalloc dependency is optional but highly **recommended**. This allocator
significantly improves the performance of the Nanos6 runtime by optimizing the
memory allocations. By default, an internal jemalloc is embedded to the Nanos6
library. This behavior can be modified through the ``--with-jemalloc`` option,
which can take the following values:
* ``--with-jemalloc=embedded``: The jemalloc is built and embedded into Nanos6
as an internal library. The building process installs the jemalloc headers
and libraries in ``$INSTALLATION_PREFIX/deps/nanos6/jemalloc`` and dynamically
links our runtime against the jemalloc library. This is the **default** behavior
if the option is not provided. See :ref:`nanos6-build-embedding` for
more information
* ``--with-jemalloc=``: A prefix of an external jemalloc installation
configured with the ``--enable-stats`` and ``--with-jemalloc-prefix=nanos6_je_``
options
* ``--with-jemalloc=no`` or ``--without-jemalloc``: Disable the jemalloc allocator
(not recommended)
The location of an external hwloc can be retrieved through pkg-config when specifying
``--with-hwloc=pkgconfig``. If it is installed in a non-standard location, pkg-config
can be told where to find it through the ``PKG_CONFIG_PATH`` environment variable. For
instance:
.. code:: sh
$ export PKG_CONFIG_PATH=/apps/HWLOC/2.0.0/INTEL/lib/pkgconfig:$PKG_CONFIG_PATH
The ``--with-cuda`` flag is needed to enable CUDA tasks. The location of CUDA
can be retrieved automatically, if it is in standard system locations (``/usr/lib``,
``/usr/include``, etc), or through pkg-config. Alternatively, for non-standard
installation paths, it can be specified using the optional ``=prefix`` of the
parameter.
The ``--enable-openacc`` flag is needed to enable OpenACC tasks. The location of
PGI compilers can be retrieved from the ``$PATH`` variable, if it is not specified
through the ``--with-pgi`` parameter.
Optionally, if you passed any valid LLVM/Clang or Mercurium installation, you can
execute the Nanos6 tests by running:
.. code:: sh
$ make check
.. _nanos6-build-embedding:
Embedding software dependencies
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
As mentioned above, there are some software dependencies that may be embedded
into Nanos6. This is the case for hwloc and jemalloc, which will be embedded by
default. The sources of these embedded dependencies are taken from the ``deps``
sub-directory in this repository. Inside the sub-directory, there is a default
hwloc and jemalloc source tarballs. These tarballs are automatically extracted
into ``deps/hwloc`` and ``deps/jemalloc`` by our ``autogen.sh`` script.
These are the source packages that are then built when choosing ``--with-hwloc=embedded``
or ``--with-jemalloc=embedded``. You may change the embedded software version by
placing the desired tarball inside the ``deps`` folder and re-running ``autogen.sh``
with the option ``--embed- ``. Currently, ```` can be
``hwloc`` or ``jemalloc`` and ```` should be the desired version number
of that software. For instance, a valid option could be:
.. code:: sh
./autogen.sh --embed-jemalloc 5.3.0
For the moment, the tarballs must follow the format ``deps/-.tar.gz``.