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``.