Skip to content

Commit 25bab31

Browse files
tldahlgrentldahlgren
authored
Added ROCmPackage (build system) documentation (spack#20743)
1 parent 85ea52a commit 25bab31

File tree

3 files changed

+127
-2
lines changed

3 files changed

+127
-2
lines changed

‎lib/spack/docs/build_systems.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -60,6 +60,7 @@ on these ideas for each distinct build system that Spack supports:
6060
build_systems/bundlepackage
6161
build_systems/cudapackage
6262
build_systems/intelpackage
63+
build_systems/rocmpackage
6364
build_systems/custompackage
6465

6566
For reference, the :py:mod:`Build System API docs <spack.build_systems>`

‎lib/spack/docs/build_systems/rocmpackage.rst‎

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
.. Copyright 2013-2021 Lawrence Livermore National Security, LLC and other
2+
Spack Project Developers. See the top-level COPYRIGHT file for details.
3+
4+
SPDX-License-Identifier: (Apache-2.0 OR MIT)
5+
6+
.. _rocmpackage:
7+
8+
-----------
9+
ROCmPackage
10+
-----------
11+
12+
The ``ROCmPackage`` is not a build system but a helper package. Like ``CudaPackage``,
13+
it provides standard variants, dependencies, and conflicts to facilitate building
14+
packages using GPUs though for AMD in this case.
15+
16+
You can find the source for this package (and suggestions for setting up your
17+
``compilers.yaml`` and ``packages.yaml`` files) at
18+
`<https://github.com/spack/spack/blob/develop/lib/spack/spack/build_systems/rocm.py>`__.
19+
20+
^^^^^^^^
21+
Variants
22+
^^^^^^^^
23+
24+
This package provides the following variants:
25+
26+
* **rocm**
27+
28+
This variant is used to enable/disable building with ``rocm``.
29+
The default is disabled (or ``False``).
30+
31+
* **amdgpu_target**
32+
33+
This variant supports the optional specification of the AMD GPU architecture.
34+
Valid values are the names of the GPUs (e.g., ``gfx701``), which are maintained
35+
in the ``amdgpu_targets`` property.
36+
37+
^^^^^^^^^^^^
38+
Dependencies
39+
^^^^^^^^^^^^
40+
41+
This package defines basic ``rocm`` dependencies, including ``llvm`` and ``hip``.
42+
43+
^^^^^^^^^
44+
Conflicts
45+
^^^^^^^^^
46+
47+
Conflicts are used to prevent builds with known bugs or issues. This package
48+
already requires that the ``amdgpu_target`` always be specified for ``rocm``
49+
builds. It also defines a conflict that prevents builds with an ``amdgpu_target``
50+
when ``rocm`` is disabled.
51+
52+
Refer to `Conflicts <https://spack.readthedocs.io/en/latest/packaging_guide.html?highlight=conflicts#conflicts>`__
53+
for more information on package conflicts.
54+
55+
^^^^^^^
56+
Methods
57+
^^^^^^^
58+
59+
This package provides one custom helper method, which is used to build
60+
standard AMD hip compiler flags.
61+
62+
**hip_flags**
63+
64+
This built-in static method returns the appropriately formatted
65+
``--amdgpu-target`` build option for ``hipcc``.
66+
67+
This method must be explicitly called when you are creating the
68+
arguments for your build in order to use the values.
69+
70+
^^^^^
71+
Usage
72+
^^^^^
73+
74+
This helper package can be added to your package by adding it as a base
75+
class of your package. For example, you can add it to your
76+
:ref:`CMakePackage <cmakepackage>`-based package as follows:
77+
78+
.. code-block:: python
79+
:emphasize-lines: 1,3-7,14-25
80+
81+
class MyRocmPackage(CMakePackage, ROCmPackage):
82+
...
83+
# Ensure +rocm and amdgpu_targets are passed to dependencies
84+
depends_on('mydeppackage', when='+rocm')
85+
for val in ROCmPackage.amdgpu_targets:
86+
depends_on('mydeppackage amdgpu_target={0}'.format(val),
87+
when='amdgpu_target={0}'.format(val))
88+
...
89+
90+
def cmake_args(self):
91+
spec = self.spec
92+
args = []
93+
...
94+
if '+rocm' in spec:
95+
# Set up the hip macros needed by the build
96+
args.extend([
97+
'-DENABLE_HIP=ON',
98+
'-DHIP_ROOT_DIR={0}'.format(spec['hip'].prefix])
99+
rocm_archs = spec.variants['amdgpu_target'].value
100+
if 'none' not in rocm_archs:
101+
args.append('-DHIP_HIPCC_FLAGS=--amdgpu-target={0}'
102+
.format(",".join(rocm_archs)))
103+
else:
104+
# Ensure build with hip is disabled
105+
args.append('-DENABLE_HIP=OFF')
106+
...
107+
return args
108+
...
109+
110+
assuming only on the ``ENABLE_HIP``, ``HIP_ROOT_DIR``, and ``HIP_HIPCC_FLAGS``
111+
macros are required to be set and the only dependency needing rocm options
112+
is ``mydeppackage``. You will need to customize the flags as needed for your
113+
build.
114+
115+
This example also illustrates how to check for the ``rocm`` variant using
116+
``self.spec`` and how to retrieve the ``amdgpu_target`` variant's value
117+
using ``self.spec.variants['amdgpu_target'].value``.
118+
119+
All five packages using ``ROCmPackage`` as of January 2021 also use the
120+
:ref:`CudaPackage <cudapackage>`. So it is worth looking at those packages
121+
to get ideas for creating a package that can support both ``cuda`` and
122+
``rocm``.

‎lib/spack/docs/packaging_guide.rst‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2744,12 +2744,14 @@ The classes that are currently provided by Spack are:
27442744
| | built using CMake |
27452745
+-------------------------------+----------------------------------+
27462746
| :py:class:`.CudaPackage` | A helper class for packages that |
2747-
| | use CUDA. It is intended to be |
2748-
| | used in combination with others |
2747+
| | use CUDA |
27492748
+-------------------------------+----------------------------------+
27502749
| :py:class:`.QMakePackage` | Specialized class for packages |
27512750
| | build using QMake |
27522751
+-------------------------------+----------------------------------+
2752+
| :py:class:`.ROCmPackage` | A helper class for packages that |
2753+
| | use ROCm |
2754+
+-------------------------------+----------------------------------+
27532755
| :py:class:`.SConsPackage` | Specialized class for packages |
27542756
| | built using SCons |
27552757
+-------------------------------+----------------------------------+

0 commit comments

Comments
 (0)