.____ _____________________
| | \______ \_ _____/
| | | ___/| __)
| |___| | | \
|_______ \____| \___ /
\/ \/
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.)