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/bundlepackage
|
||||||
build_systems/cudapackage
|
build_systems/cudapackage
|
||||||
build_systems/intelpackage
|
build_systems/intelpackage
|
||||||
|
build_systems/rocmpackage
|
||||||
build_systems/custompackage
|
build_systems/custompackage
|
||||||
|
|
||||||
For reference, the :py:mod:`Build System API docs <spack.build_systems>`
|
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 |
|
| | built using CMake |
|
||||||
+-------------------------------+----------------------------------+
|
+-------------------------------+----------------------------------+
|
||||||
| :py:class:`.CudaPackage` | A helper class for packages that |
|
| :py:class:`.CudaPackage` | A helper class for packages that |
|
||||||
| | use CUDA. It is intended to be |
|
| | use CUDA |
|
||||||
| | used in combination with others |
|
|
||||||
+-------------------------------+----------------------------------+
|
+-------------------------------+----------------------------------+
|
||||||
| :py:class:`.QMakePackage` | Specialized class for packages |
|
| :py:class:`.QMakePackage` | Specialized class for packages |
|
||||||
| | build using QMake |
|
| | build using QMake |
|
||||||
+-------------------------------+----------------------------------+
|
+-------------------------------+----------------------------------+
|
||||||
|
| :py:class:`.ROCmPackage` | A helper class for packages that |
|
||||||
|
| | use ROCm |
|
||||||
|
+-------------------------------+----------------------------------+
|
||||||
| :py:class:`.SConsPackage` | Specialized class for packages |
|
| :py:class:`.SConsPackage` | Specialized class for packages |
|
||||||
| | built using SCons |
|
| | built using SCons |
|
||||||
+-------------------------------+----------------------------------+
|
+-------------------------------+----------------------------------+
|
||||||
|
Loading…
Reference in New Issue
Block a user