Added ROCmPackage (build system) documentation (#20743)
This commit is contained in:
parent
85ea52acd1
commit
25bab31bc8
@ -60,6 +60,7 @@ on these ideas for each distinct build system that Spack supports:
|
||||
build_systems/bundlepackage
|
||||
build_systems/cudapackage
|
||||
build_systems/intelpackage
|
||||
build_systems/rocmpackage
|
||||
build_systems/custompackage
|
||||
|
||||
For reference, the :py:mod:`Build System API docs <spack.build_systems>`
|
||||
|
122
lib/spack/docs/build_systems/rocmpackage.rst
Normal file
122
lib/spack/docs/build_systems/rocmpackage.rst
Normal file
@ -0,0 +1,122 @@
|
||||
.. Copyright 2013-2021 Lawrence Livermore National Security, LLC and other
|
||||
Spack Project Developers. See the top-level COPYRIGHT file for details.
|
||||
|
||||
SPDX-License-Identifier: (Apache-2.0 OR MIT)
|
||||
|
||||
.. _rocmpackage:
|
||||
|
||||
-----------
|
||||
ROCmPackage
|
||||
-----------
|
||||
|
||||
The ``ROCmPackage`` is not a build system but a helper package. Like ``CudaPackage``,
|
||||
it provides standard variants, dependencies, and conflicts to facilitate building
|
||||
packages using GPUs though for AMD in this case.
|
||||
|
||||
You can find the source for this package (and suggestions for setting up your
|
||||
``compilers.yaml`` and ``packages.yaml`` files) at
|
||||
`<https://github.com/spack/spack/blob/develop/lib/spack/spack/build_systems/rocm.py>`__.
|
||||
|
||||
^^^^^^^^
|
||||
Variants
|
||||
^^^^^^^^
|
||||
|
||||
This package provides the following variants:
|
||||
|
||||
* **rocm**
|
||||
|
||||
This variant is used to enable/disable building with ``rocm``.
|
||||
The default is disabled (or ``False``).
|
||||
|
||||
* **amdgpu_target**
|
||||
|
||||
This variant supports the optional specification of the AMD GPU architecture.
|
||||
Valid values are the names of the GPUs (e.g., ``gfx701``), which are maintained
|
||||
in the ``amdgpu_targets`` property.
|
||||
|
||||
^^^^^^^^^^^^
|
||||
Dependencies
|
||||
^^^^^^^^^^^^
|
||||
|
||||
This package defines basic ``rocm`` dependencies, including ``llvm`` and ``hip``.
|
||||
|
||||
^^^^^^^^^
|
||||
Conflicts
|
||||
^^^^^^^^^
|
||||
|
||||
Conflicts are used to prevent builds with known bugs or issues. This package
|
||||
already requires that the ``amdgpu_target`` always be specified for ``rocm``
|
||||
builds. It also defines a conflict that prevents builds with an ``amdgpu_target``
|
||||
when ``rocm`` is disabled.
|
||||
|
||||
Refer to `Conflicts <https://spack.readthedocs.io/en/latest/packaging_guide.html?highlight=conflicts#conflicts>`__
|
||||
for more information on package conflicts.
|
||||
|
||||
^^^^^^^
|
||||
Methods
|
||||
^^^^^^^
|
||||
|
||||
This package provides one custom helper method, which is used to build
|
||||
standard AMD hip compiler flags.
|
||||
|
||||
**hip_flags**
|
||||
|
||||
This built-in static method returns the appropriately formatted
|
||||
``--amdgpu-target`` build option for ``hipcc``.
|
||||
|
||||
This method must be explicitly called when you are creating the
|
||||
arguments for your build in order to use the values.
|
||||
|
||||
^^^^^
|
||||
Usage
|
||||
^^^^^
|
||||
|
||||
This helper package can be added to your package by adding it as a base
|
||||
class of your package. For example, you can add it to your
|
||||
:ref:`CMakePackage <cmakepackage>`-based package as follows:
|
||||
|
||||
.. code-block:: python
|
||||
:emphasize-lines: 1,3-7,14-25
|
||||
|
||||
class MyRocmPackage(CMakePackage, ROCmPackage):
|
||||
...
|
||||
# Ensure +rocm and amdgpu_targets are passed to dependencies
|
||||
depends_on('mydeppackage', when='+rocm')
|
||||
for val in ROCmPackage.amdgpu_targets:
|
||||
depends_on('mydeppackage amdgpu_target={0}'.format(val),
|
||||
when='amdgpu_target={0}'.format(val))
|
||||
...
|
||||
|
||||
def cmake_args(self):
|
||||
spec = self.spec
|
||||
args = []
|
||||
...
|
||||
if '+rocm' in spec:
|
||||
# Set up the hip macros needed by the build
|
||||
args.extend([
|
||||
'-DENABLE_HIP=ON',
|
||||
'-DHIP_ROOT_DIR={0}'.format(spec['hip'].prefix])
|
||||
rocm_archs = spec.variants['amdgpu_target'].value
|
||||
if 'none' not in rocm_archs:
|
||||
args.append('-DHIP_HIPCC_FLAGS=--amdgpu-target={0}'
|
||||
.format(",".join(rocm_archs)))
|
||||
else:
|
||||
# Ensure build with hip is disabled
|
||||
args.append('-DENABLE_HIP=OFF')
|
||||
...
|
||||
return args
|
||||
...
|
||||
|
||||
assuming only on the ``ENABLE_HIP``, ``HIP_ROOT_DIR``, and ``HIP_HIPCC_FLAGS``
|
||||
macros are required to be set and the only dependency needing rocm options
|
||||
is ``mydeppackage``. You will need to customize the flags as needed for your
|
||||
build.
|
||||
|
||||
This example also illustrates how to check for the ``rocm`` variant using
|
||||
``self.spec`` and how to retrieve the ``amdgpu_target`` variant's value
|
||||
using ``self.spec.variants['amdgpu_target'].value``.
|
||||
|
||||
All five packages using ``ROCmPackage`` as of January 2021 also use the
|
||||
:ref:`CudaPackage <cudapackage>`. So it is worth looking at those packages
|
||||
to get ideas for creating a package that can support both ``cuda`` and
|
||||
``rocm``.
|
@ -2744,12 +2744,14 @@ The classes that are currently provided by Spack are:
|
||||
| | built using CMake |
|
||||
+-------------------------------+----------------------------------+
|
||||
| :py:class:`.CudaPackage` | A helper class for packages that |
|
||||
| | use CUDA. It is intended to be |
|
||||
| | used in combination with others |
|
||||
| | use CUDA |
|
||||
+-------------------------------+----------------------------------+
|
||||
| :py:class:`.QMakePackage` | Specialized class for packages |
|
||||
| | build using QMake |
|
||||
+-------------------------------+----------------------------------+
|
||||
| :py:class:`.ROCmPackage` | A helper class for packages that |
|
||||
| | use ROCm |
|
||||
+-------------------------------+----------------------------------+
|
||||
| :py:class:`.SConsPackage` | Specialized class for packages |
|
||||
| | built using SCons |
|
||||
+-------------------------------+----------------------------------+
|
||||
|
Loading…
Reference in New Issue
Block a user