.____   _____________________
|    |  \______   \_   _____/
|    |   |     ___/|    __)  
|    |___|    |    |     \   
|_______ \____|    \___  /   
        \/             \/    

Lightweight Parallel Foundations

Copyright 2021 Huawei Technologies Co., Ltd.

  Licensed under the Apache License, Version 2.0 (the "License");
  you may not use this file except in compliance with the License.
  You may obtain a copy of the License at

      http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.


Prerequisites
=============

Mandatory
 - GNU/Linux,
 - GNU C compiler,
 - GNU C++ compiler (C++03/TR1 or C++11),
 - GNU Make,
 - CMake 3.1 or better.

Optional MPI engine requires
 - MPI-3, such as 'MPICH', 'OpenMPI', or 'MVAPICH'.

Optional for thread pinning by Pthreads and hybrid engines
 - hwloc > 1.11

Optional (see --enable-doc) documentation requires
 - doxygen > 1.5.6,
 - graphviz,
 - latex, dvips, and pdflatex.


Quick Start
===========

1) Create an empty build directory.

2) Run 'bootstrap.sh' from within the build directory. If you want to set the
   installation directory, use the --prefix option.

3) Run 'make' and 'make install'.

4) Ready.


Configuration Options
=====================

LPF can be built in different flavours depending on how it is configured. The
'bootstrap.sh' script can be given certain command line parameters which
accomplish that:

    --help

        Displays this README

    --release    [DEFAULT]
    --debug

        In case you do any serious benchmarking with LPF, be sure you to build
        it in 'Release' mode with the '--release' option. In case you are
        developing, you should choose '--debug', which will enable additional
        runtime checks.

    --with-cmake=<command>

        By default, the bootstrap script will rely on the `cmake' CLI command.
        On different systems, and depending on the default version installed,
        the required command name may differ from the default `cmake'. This
        flag allows replacing the default with the specified command instead.

    --with-mpicc=<path to mpicc> 
    --with-mpicxx=<path to mpicxx>
    --with-mpiexec=<path to mpiexec> [as required]
      
        If you want to try another MPI implementation than can be found in the
        current PATH, use this option to compile LPF with this compiler. It will
        also try to autodetect how to run MPI programs, which is then being used
        to generate the 'lpfrun' script. If autodetection fails, you may have to
        set the following CMake variables manually:
        MPI_C_LIBRARIES, MPI_C_INCLUDE_PATH, MPI_C_LINK_FLAGS, MPIEXEC,
        MPIEXEC_NUMPROC_FLAG, and MPI_C_FOUND.
        
        Notes:

        1) you need at least an MPI-3 implementation, which is at the moment
        of writing not supported yet by some commercial MPI vendors.  Recent
        versions of MPICH and OpenMPI do support this.

    --with-hwloc=<path to hwloc>
    --without-hwloc

        By default an installation of Hwloc will be sought in the standard
        system locations and used to pin threads in the Pthread and hybrid
        engines. The --without-hwloc flag will disable thread pinning. The
        --with-hwloc= flag can be set to search in different locations.

    --prefix=<installdir>

        Configures the build script to install the library, headers, and
        various tools to path denoted by <installdir>. 

    --enable-doc
    --disable-doc [DEFAULT]

        Use --enable-doc to generate and install the API documentation of LPF
        and --disable-doc to skip this step. Building the documentation requires
        doxygen, latex, dvips, and pdflatex. This is disabled by default.

    --functests[=i-agree-with-googletest-license]

        Enable the functional test suite. This comprises unit tests as well as
        an API test base. It uses Google Testing and Mocking framework, which
        will be downloaded during the build. During the bootstrap, the user is
        prompted to agree with its license. To consent prior to execution of
        the script, use the --functests=i-agree-with-googletest-license option.
        All tests are executed by the main test driver CTest or just `make
        test'.  The functional test suite is disabled by default. Enabling and
        successfully running the test suite typically requires more than 32GB
        RAM.

    --perftests[=p0,p1,...]

        Enable compilation and inclusion of the the extra performance tests to
        the test suite. A comma separated list of numbers can be given to run
        the tests on that number of processes. Produces JUnit output. The
        performance tests are disabled by default. It must only be enabled
        together with the functional test suite (see `--functests').

    --config-name=<identifier>  [DEFAULT: performance]

        Use this <identifier> to differentiate the symbol names of this build. 
        This is then used to substitute the macro LPF_CORE_IMPL_CONFIG when
        building and linking LPF. See also --debug.
 
    --reconfig
       
        Reconfigure the build forcefully. This is useful when you want to 
        change some build settings, but do not want to rebuild everything from
        scratch.
       

Installation
============

When performing a system-wide installation of LPF the following steps are
recommended:

1) Configure with the functional test suite enabled (see the `--functests'
   option). After the `make' in step 3 of the quick start and before issuing
   `make install', first issue `make test' in the build directory. This runs all
   functional tests of all engines LPF is configured to be built with, thus
   making sure they function correctly on the target platform.

2) Run <installpath>/bin/lpfprobe to obtain reliable estimations of the BSP
   all-to-all latency and throughput parameters. These figures should be close
   to the specified minimum latency of the system interconnect and close to its
   specified maximum throughput, respectively.
   Depending on the target platform, some engines may be outperformed by
   others-- and sometimes significantly so. It hence deserves recommendation to
   use the lpfprobe tool for every engine the LPF was configured with. (And, in
   production, to avoid the use of engines that underperform significantly on
   the target platform.)