Skip to content

Commit 60f4aeb

Browse files
corbett5corbett5
committed
Added build documentation.
1 parent 1cf2bf1 commit 60f4aeb

File tree

3 files changed

+198
-5
lines changed

3 files changed

+198
-5
lines changed

‎docs/sphinx/buildGuide.rst‎

Lines changed: 197 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,200 @@
11
###############################################################################
2-
Build Guide (Coming soon)
2+
Build Guide
33
###############################################################################
44

5-
Coming soon: documentation on how to build ``LvArray`` and build options.
5+
LvArray uses a CMake based build system augmented with `BLT <https://github.com/LLNL/blt>`_. If you're not familiar with CMake, RAJA has a good `introduction <https://raja.readthedocs.io/en/main/getting_started.html#getting-started-label>`_. LvArray has a dependency on RAJA and as such requires that the ``RAJA_DIR`` CMake variable defined and points to a RAJA installation.
6+
7+
CMake Options
8+
-------------
9+
In addition to the standard CMake and BLT options LvArray supports the following options.
10+
11+
* **Adding additional targets**
12+
The following variables add additional build targets but do not alter the usage or functionality of LvArray.
13+
14+
* ``ENABLE_TESTS`` : default ``ON``
15+
Build the unit tests which can be run with ``make test``. The unit tests take a long time to build with the IMB XL and Intel compilers.
16+
* ``ENABLE_EXAMPLES`` : default ``ON``
17+
Build the examples, ``ENABLE_TESTS`` must also be ``ON``.
18+
* ``ENABLE_BENCHMARKS`` : default ``ON``
19+
Build the benchmarks, ``ENABLE_TESTS`` must also be ``ON``.
20+
* ``DISABLE_UNIT_TESTS`` : default ``OFF``
21+
Use with ``ENABLE_TESTS=ON`` to disable building the unit tests but still allow the examples and benchmarks.
22+
* ``ENABLE_DOCS`` : default ``ON``
23+
Build the documentation.
24+
25+
* **Third party libraries**
26+
LvArray has a hard dependency on RAJA along with multiple optional dependencies. Of the following variables only ``RAJA_DIR`` is mandatory.
27+
28+
* ``RAJA_DIR``
29+
The path to the RAJA installation.
30+
* ``ENABLE_UMPIRE`` : default ``OFF``
31+
If Umpire is enabled. Currently no part of LvArray uses Umpire but it is required when using CHAI.
32+
* ``UMPIRE_DIR``
33+
The path to the Umpire installation, must be specified when Umpire is enabled.
34+
* ``ENABLE_CHAI`` : default ``OFF``
35+
If CHAI is enabled, CHAI also requires Umpire. Enabling CHAI allows the usage of the ``LvArray::ChaiBuffer``.
36+
* ``CHAI_DIR``
37+
The path to the CHAI installation, must be specified when CHAI is enabled.
38+
* ``ENABLE_CALIPER`` : default ``OFF``
39+
If caliper is enabled. Currently caliper is only used to time the benchmarks.
40+
* ``CALIPER_DIR``
41+
The path to the caliper installation, must be specified when caliper is enabled.
42+
* ``ENABLE_ADDR2LINE`` : default ``ON``
43+
If ``addr2line`` is enabled. This is used in ``LvArray::system::stackTrace`` to attempt to provide file and line locations for the stack frames.
44+
* ``ADDR2LINE_EXEC`` : default ``/usr/bin/addr2line``
45+
The path to the ``addr2line`` executable.
46+
47+
* **Debug options**
48+
The following options don't change the usage of LvArray but they are intended to make debugging easier.
49+
50+
* ``LVARRAY_BOUNDS_CHECK`` : default ``ON`` iff in a CMake ``Debug`` build.
51+
Enables bounds checks on container access along with checks for other invalid operations.
52+
* ``ENABLE_TOTALVIEW_OUTPUT`` : default ``OFF``
53+
Makes it easier to inspect the ``LvArray::Array`` in TotalView. This functionality is highly dependent on the version of TotalView used.
54+
55+
Host Configs
56+
------------
57+
Host config files are a convenient way to group CMake options for a specific configuration together. There are a set of example host configs in the ``host-configs`` directory. Once you've created a host config file you can use ``scripts/config-build.py`` to create the build directory and run CMake for you. An example usage would be ``python ./scripts/config-build.py --hc host-configs/LLNL/[email protected]``.
58+
59+
::
60+
61+
> python scripts/config-build.py --help
62+
usage: config-build.py [-h] [-bp BUILDPATH] [-ip INSTALLPATH]
63+
[-bt {Release,Debug,RelWithDebInfo,MinSizeRel}] [-e]
64+
[-x] [-ecc] -hc HOSTCONFIG
65+
66+
Configure cmake build. Unrecognized arguments are passed on to CMake.
67+
68+
optional arguments:
69+
-h, --help show this help message and exit
70+
-bp BUILDPATH, --buildpath BUILDPATH
71+
specify path for build directory. If not specified,
72+
will create in current directory.
73+
-ip INSTALLPATH, --installpath INSTALLPATH
74+
specify path for installation directory. If not
75+
specified, will create in current directory.
76+
-bt {Release,Debug,RelWithDebInfo,MinSizeRel}, --buildtype {Release,Debug,RelWithDebInfo,MinSizeRel}
77+
build type.
78+
-e, --eclipse create an eclipse project file.
79+
-x, --xcode create an xcode project.
80+
-ecc, --exportcompilercommands
81+
generate a compilation database. Can be used by the
82+
clang tools such as clang-modernize. Will create a
83+
file called 'compile_commands.json' in build
84+
directory.
85+
-hc HOSTCONFIG, --hostconfig HOSTCONFIG
86+
select a specific host-config file to initalize
87+
CMake's cache
88+
89+
Submodule usage
90+
---------------
91+
LvArray can also be used as a submodule. In this case the configuration is largely the same except that LvArray expects the parent project to have imported the third party libraries. For example if ``ENABLE_UMPIRE`` is ``ON`` then LvArray will depend on ``umpire`` but it will make no attempt to find these library (``UMPIRE_DIR`` is unused).
92+
93+
Spack and Uberenv Builds
94+
------------------------
95+
LvArray has an associated `Spack <https://github.com/spack/spack>`_ package. For those unfamiliar with Spack the most important thing to understand is the `spec syntax <https://spack.readthedocs.io/en/latest/basic_usage.html#specs-dependencies>`_. For those interested the LvArray package implementation is `here <https://github.com/corbett5/spack/blob/feature/corbett/lvarray/var/spack/repos/builtin/packages/lvarray/package.py>`_ the important part of which is reproduced below.
96+
97+
.. code:: python
98+
99+
class Lvarray(CMakePackage, CudaPackage):
100+
"""LvArray portable HPC containers."""
101+
102+
homepage = "https://github.com/GEOSX/lvarray"
103+
git = "https://github.com/GEOSX/LvArray.git"
104+
105+
version('develop', branch='develop', submodules='True')
106+
version('tribol', branch='temp/feature/corbett/tribol', submodules='True')
107+
108+
variant('shared', default=True, description='Build Shared Libs')
109+
variant('umpire', default=False, description='Build Umpire support')
110+
variant('chai', default=False, description='Build Chai support')
111+
variant('caliper', default=False, description='Build Caliper support')
112+
variant('tests', default=True, description='Build tests')
113+
variant('benchmarks', default=False, description='Build benchmarks')
114+
variant('examples', default=False, description='Build examples')
115+
variant('docs', default=False, description='Build docs')
116+
variant('addr2line', default=True,
117+
description='Build support for addr2line.')
118+
119+
depends_on('[email protected]:', type='build')
120+
depends_on('[email protected]:', when='+cuda', type='build')
121+
122+
depends_on('raja')
123+
depends_on('raja+cuda', when='+cuda')
124+
125+
depends_on('umpire', when='+umpire')
126+
depends_on('umpire+cuda', when='+umpire+cuda')
127+
128+
depends_on('chai+raja', when='+chai')
129+
depends_on('chai+raja+cuda', when='+chai+cuda')
130+
131+
depends_on('caliper', when='+caliper')
132+
133+
depends_on('[email protected]:', when='+docs', type='build')
134+
depends_on('[email protected]:', when='+docs', type='build')
135+
136+
137+
LvArray also has an ``uberenv`` based build which simplifies building LvArray's dependencies along with optionally LvArray using spack.
138+
139+
::
140+
141+
> ./scripts/uberenv/uberenv.py --help
142+
Usage: uberenv.py [options]
143+
144+
Options:
145+
-h, --help show this help message and exit
146+
--install Install `package_name`, not just its dependencies.
147+
--prefix=PREFIX destination directory
148+
--spec=SPEC spack compiler spec
149+
--mirror=MIRROR spack mirror directory
150+
--create-mirror Create spack mirror
151+
--upstream=UPSTREAM add an external spack instance as upstream
152+
--spack-config-dir=SPACK_CONFIG_DIR
153+
dir with spack settings files (compilers.yaml,
154+
packages.yaml, etc)
155+
--package-name=PACKAGE_NAME
156+
override the default package name
157+
--package-final-phase=PACKAGE_FINAL_PHASE
158+
override the default phase after which spack should
159+
stop
160+
--package-source-dir=PACKAGE_SOURCE_DIR
161+
override the default source dir spack should use
162+
--project-json=PROJECT_JSON
163+
uberenv project settings json file
164+
-k Ignore SSL Errors
165+
--pull Pull if spack repo already exists
166+
--clean Force uninstall of packages specified in project.json
167+
--run_tests Invoke build tests during spack install
168+
--macos-sdk-env-setup
169+
Set several env vars to select OSX SDK settings.This
170+
was necessary for older versions of macOS but can
171+
cause issues with macOS versions >= 10.13. so it is
172+
disabled by default.
173+
174+
Two simple examples are provided below.
175+
176+
::
177+
quartz2498 > ./scripts/uberenv/uberenv.py --install --spec="@develop %[email protected]"
178+
179+
This will build RAJA (LvArray's only hard dependency) and LvArray and install them in ``./uberenv_libs/[email protected]``. By default libraries are built in the ``RelWithDebInfo`` CMake configuration.
180+
181+
::
182+
quartz2498 > ./scripts/uberenv/uberenv.py --spec="@develop %[email protected] ^[email protected] build_type=Release"
183+
184+
This will install RAJA in the same location but it will be built in the ``Release`` configuration and instead of building and installing LvArray a host-config will be generated and placed in the current directory. This can be useful for developing or debugging.
185+
186+
Currently ``uberenv`` only works on the LLNL ``toss_3_x86_64_ib`` and ``blueos_3_ppc64le_ib_p9`` systems. Further more only certain compilers are supported. On the TOSS systems ``[email protected]``, ``[email protected]`` and ``[email protected]`` are supported. On BlueOS ``clang-upstream-2019.08.15 ([email protected])``, ``clang-ibm-10.0.1-gcc-8.3.1 ([email protected])``, ``[email protected]`` and ``xl-2020.09.17-cuda-11.0.2 ([email protected])`` are supported. Adding support for more compilers is as simple as adding them to the appropriate ``compilers.yaml`` file.
187+
188+
Adding support for a new system is easy too, you just need to create a directory with a ``compilers.yaml`` which specifies the available compilers and a ``packages.yaml`` for system packages and then pass this directory to uberenv with the ``--spack-config-dir`` option.
189+
190+
For reference two more complicated specs are shown below
191+
192+
::
193+
lassen709 > ./scripts/uberenv/uberenv.py --install --run_tests --spec="@develop+umpire+chai+caliper+cuda %[email protected] cuda_arch=70 ^[email protected] ^[email protected]~examples~exercises cuda_arch=70 ^[email protected]~examples cuda_arch=70 ^chai@master~benchmarks~examples cuda_arch=70 ^[email protected]~adiak~mpi~dyninst~callpath~papi~libpfm~gotcha~sampler~sosflow"
194+
195+
This will use ``[email protected]`` and ``[email protected]`` to build and install RAJA v0.12.1 without examples or exercises, Umpire v4.0.1 without examples, the master branch of CHAI without benchmarks or examples, and caliper v2.4 without a bunch of options. Finally it will build and install LvArray after running the unit tests and verifying that they pass. Note that each package that depends on cuda gets the ``cuda_arch=70`` variable.
196+
197+
::
198+
quartz2498 > ./scripts/uberenv/uberenv.py --spec="@tribol+umpire+chai %[email protected] ^[email protected] build_type=Release ^[email protected] build_type=Release"
199+
200+
This will use ``[email protected]`` to build and install RAJA V0.12.1 in release and Umpire v4.0.1 in release. Finally it will generate a host config that can be used to build LvArray.

‎docs/sphinx/tensorOps.rst‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -204,8 +204,6 @@ There are also two function ``tensorOps::denseToSymmetric`` and ``tensorOps::sym
204204
.. note::
205205
Apart from ``tensorOps::symAddIdentity`` and ``tensorOps::symTrace`` the symmetric matrix operations are only implemented for matrices of size :math:`2 \times 2` and :math:`3 \times 3`.
206206

207-
``LvArray::tensorOps`` contains a lot of operations and it can be hard to remember the appropriate order to specify the function arguments and size template parameters. In general the arguments are provided in the order they appear in the equation describing the operation. This implies that the output variable is always the first argument. For example to compute the matrix matrix product :math:`\mathbf{A} \leftarrow \mathbf{B} \mathbf{C}` the arguments are ``A`` then ``B`` then ``C``. The order of the sizes is created from the sizes of the arguments after removing duplicates. If :math:`\mathbf{A} \in \mathbb{R}^m \times \mathbb{R}^n` and :math:`\mathbf{B} \in \mathbb{R}^m \times \mathbb{R}^p` then the sizes are ``m`` then ``n`` then ``p``. This leads to a call of ``LvArray::tensorOps::AikBkj< m, n, p >( A, B, C )``.
208-
209207
Examples
210208
--------
211209

‎scripts/config-build.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@ def extract_cmake_location(file_path):
2424

2525

2626

27-
parser = argparse.ArgumentParser(description="Configure cmake build.")
27+
parser = argparse.ArgumentParser(description="Configure cmake build. Unrecognized arguments are passed on to CMake.")
2828

2929
parser.add_argument("-bp",
3030
"--buildpath",

0 commit comments

Comments
 (0)