From 25bab31bc8c74997e695be5d7a4bcbfcd49828ca Mon Sep 17 00:00:00 2001 From: Tamara Dahlgren <35777542+tldahlgren@users.noreply.github.com> Date: Thu, 21 Jan 2021 10:46:39 -0800 Subject: Added ROCmPackage (build system) documentation (#20743) --- lib/spack/docs/build_systems.rst | 1 + lib/spack/docs/build_systems/rocmpackage.rst | 122 +++++++++++++++++++++++++++ lib/spack/docs/packaging_guide.rst | 6 +- 3 files changed, 127 insertions(+), 2 deletions(-) create mode 100644 lib/spack/docs/build_systems/rocmpackage.rst (limited to 'lib') diff --git a/lib/spack/docs/build_systems.rst b/lib/spack/docs/build_systems.rst index 609b5fd060..784730ce40 100644 --- a/lib/spack/docs/build_systems.rst +++ b/lib/spack/docs/build_systems.rst @@ -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 ` diff --git a/lib/spack/docs/build_systems/rocmpackage.rst b/lib/spack/docs/build_systems/rocmpackage.rst new file mode 100644 index 0000000000..e322194adf --- /dev/null +++ b/lib/spack/docs/build_systems/rocmpackage.rst @@ -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 +``__. + +^^^^^^^^ +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 `__ +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 `-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 `. So it is worth looking at those packages +to get ideas for creating a package that can support both ``cuda`` and +``rocm``. diff --git a/lib/spack/docs/packaging_guide.rst b/lib/spack/docs/packaging_guide.rst index 2cbb3ccf20..1d25dda2fd 100644 --- a/lib/spack/docs/packaging_guide.rst +++ b/lib/spack/docs/packaging_guide.rst @@ -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 | +-------------------------------+----------------------------------+ -- cgit v1.2.3-60-g2f50