Skip to content

Commit 13c8175

Browse files
neon60neon60
committed
Update install and build instructions
1 parent dff5c10 commit 13c8175

File tree

2 files changed

+187
-179
lines changed

2 files changed

+187
-179
lines changed

‎docs/install/build.rst‎

Lines changed: 129 additions & 125 deletions
Original file line numberDiff line numberDiff line change
@@ -9,27 +9,28 @@ Build HIP from source
99
Prerequisites
1010
=================================================
1111

12-
HIP code can be developed either on AMD ROCm platform using HIP-Clang compiler, or a CUDA platform with ``nvcc`` installed.
13-
Before building and running HIP, make sure drivers and prebuilt packages are installed properly on the platform.
12+
HIP code can be developed either on AMD ROCm platform using HIP-Clang compiler,
13+
or a CUDA platform with ``nvcc`` installed. Before building and running HIP,
14+
make sure drivers and prebuilt packages are installed properly on the platform.
1415

1516
You also need to install Python 3, which includes the ``CppHeaderParser`` package.
1617
Install Python 3 using the following command:
1718

1819
.. code-block:: shell
1920
20-
apt-get install python3
21+
apt-get install python3
2122
2223
Check and install ``CppHeaderParser`` package using the command:
2324

2425
.. code-block:: shell
2526
26-
pip3 install CppHeaderParser
27+
pip3 install CppHeaderParser
2728
2829
Install ``ROCm LLVM`` package using the command:
2930

3031
.. code-block:: shell
3132
32-
apt-get install rocm-llvm-dev
33+
apt-get install rocm-llvm-dev
3334
3435
3536
.. _Building the HIP runtime:
@@ -41,197 +42,200 @@ Set the repository branch using the variable: ``ROCM_BRANCH``. For example, for
4142

4243
.. code-block:: shell
4344
44-
export ROCM_BRANCH=rocm-6.1.x
45+
export ROCM_BRANCH=rocm-6.1.x
4546
4647
.. tab-set::
4748

48-
.. tab-item:: AMD
49-
:sync: amd
49+
.. tab-item:: AMD
50+
:sync: amd
5051

51-
#. Get HIP source code.
52+
#. Get HIP source code.
5253

53-
.. note::
54-
Starting in ROCM 5.6, CLR is a new repository that includes the former ROCclr, HIPAMD and
55-
OpenCl repositories. OpenCL provides headers that ROCclr runtime depends on.
54+
.. note::
55+
56+
Starting in ROCM 5.6, CLR is a new repository that includes the former ROCclr, HIPAMD and
57+
OpenCl repositories. OpenCL provides headers that ROCclr runtime depends on.
5658

57-
.. note::
58-
Starting in ROCM 6.1, a new repository ``hipother`` is added to ROCm, which is branched out from HIP.
59-
``hipother`` provides files required to support the HIP back-end implementation on some non-AMD platforms,
60-
like NVIDIA.
59+
.. note::
6160

62-
.. code-block:: shell
61+
Starting in ROCM 6.1, a new repository ``hipother`` is added to ROCm, which is branched out from HIP.
62+
``hipother`` provides files required to support the HIP back-end implementation on some non-AMD platforms,
63+
like NVIDIA.
6364

64-
git clone -b "$ROCM_BRANCH" https://github.com/ROCm/clr.git
65-
git clone -b "$ROCM_BRANCH" https://github.com/ROCm/hip.git
65+
.. code-block:: shell
6666
67-
CLR (Compute Language Runtime) repository includes ROCclr, HIPAMD and OpenCL.
67+
git clone -b "$ROCM_BRANCH" https://github.com/ROCm/clr.git
68+
git clone -b "$ROCM_BRANCH" https://github.com/ROCm/hip.git
6869
69-
ROCclr (ROCm Compute Language Runtime) is a virtual device interface which
70-
is defined on the AMD platform. HIP runtime uses ROCclr to interact with different backends.
70+
CLR (Compute Language Runtime) repository includes ROCclr, HIPAMD and OpenCL.
7171

72-
HIPAMD provides implementation specifically for HIP on the AMD platform.
72+
ROCclr (ROCm Compute Language Runtime) is a virtual device interface which
73+
is defined on the AMD platform. HIP runtime uses ROCclr to interact with different backends.
7374

74-
OpenCL provides headers that ROCclr runtime currently depends on.
75-
hipother provides headers and implementation specifically for non-AMD HIP platforms, like NVIDIA.
75+
HIPAMD provides implementation specifically for HIP on the AMD platform.
7676

77-
#. Set the environment variables.
77+
OpenCL provides headers that ROCclr runtime currently depends on.
78+
hipother provides headers and implementation specifically for non-AMD HIP platforms, like NVIDIA.
7879

79-
.. code-block:: shell
80+
#. Set the environment variables.
8081

81-
export CLR_DIR="$(readlink -f clr)"
82-
export HIP_DIR="$(readlink -f hip)"
82+
.. code-block:: shell
8383
84+
export CLR_DIR="$(readlink -f clr)"
85+
export HIP_DIR="$(readlink -f hip)"
8486
85-
#. Build HIP.
8687
87-
.. code-block:: shell
88+
#. Build HIP.
8889

89-
cd "$CLR_DIR"
90-
mkdir -p build; cd build
91-
cmake -DHIP_COMMON_DIR=$HIP_DIR -DHIP_PLATFORM=amd -DCMAKE_PREFIX_PATH="/opt/rocm/" -DCMAKE_INSTALL_PREFIX=$PWD/install -DHIP_CATCH_TEST=0 -DCLR_BUILD_HIP=ON -DCLR_BUILD_OCL=OFF ..
90+
.. code-block:: shell
9291
93-
make -j$(nproc)
94-
sudo make install
92+
cd "$CLR_DIR"
93+
mkdir -p build; cd build
94+
cmake -DHIP_COMMON_DIR=$HIP_DIR -DHIP_PLATFORM=amd -DCMAKE_PREFIX_PATH="/opt/rocm/" -DCMAKE_INSTALL_PREFIX=$PWD/install -DHIP_CATCH_TEST=0 -DCLR_BUILD_HIP=ON -DCLR_BUILD_OCL=OFF ..
9595
96-
.. note::
96+
make -j$(nproc)
97+
sudo make install
9798
98-
Note, if you don't specify ``CMAKE_INSTALL_PREFIX``, the HIP runtime is installed at
99-
``<ROCM_PATH>``.
99+
.. note::
100100

101-
By default, release version of HIP is built. If need debug version, you can put the option ``CMAKE_BUILD_TYPE=Debug`` in the command line.
101+
Note, if you don't specify ``CMAKE_INSTALL_PREFIX``, the HIP runtime is installed at
102+
``<ROCM_PATH>``.
102103

103-
Default paths and environment variables:
104+
By default, release version of HIP is built. If need debug version, you can
105+
put the option ``CMAKE_BUILD_TYPE=Debug`` in the command line.
104106

105-
* HIP is installed into ``<ROCM_PATH>``. This can be overridden by setting the ``INSTALL_PREFIX`` as the command option.
106-
environment variable.
107-
* HSA is in ``<ROCM_PATH>``. This can be overridden by setting the ``HSA_PATH``
108-
environment variable.
109-
* Clang is in ``<ROCM_PATH>/llvm/bin``. This can be overridden by setting the
110-
``HIP_CLANG_PATH`` environment variable.
111-
* The device library is in ``<ROCM_PATH>/lib``. This can be overridden by setting the
112-
``DEVICE_LIB_PATH`` environment variable.
113-
* Optionally, you can add ``<ROCM_PATH>/bin`` to your ``PATH``, which can make it easier to
114-
use the tools.
115-
* Optionally, you can set ``HIPCC_VERBOSE=7`` to output the command line for compilation.
107+
Default paths and environment variables:
116108

117-
After you run the ``make install`` command, HIP is installed to ``<ROCM_PATH>`` by default, or ``$PWD/install/hip`` while ``INSTALL_PREFIX`` is defined.
109+
* HIP is installed into ``<ROCM_PATH>``. This can be overridden by setting the ``INSTALL_PREFIX`` as the command option.
110+
111+
* HSA is in ``<ROCM_PATH>``. This can be overridden by setting the ``HSA_PATH`` environment variable.
112+
113+
* Clang is in ``<ROCM_PATH>/llvm/bin``. This can be overridden by setting the ``HIP_CLANG_PATH`` environment variable.
114+
115+
* The device library is in ``<ROCM_PATH>/lib``. This can be overridden by setting the ``DEVICE_LIB_PATH`` environment variable.
116+
117+
* Optionally, you can add ``<ROCM_PATH>/bin`` to your ``PATH``, which can make it easier to use the tools.
118+
119+
* Optionally, you can set ``HIPCC_VERBOSE=7`` to output the command line for compilation.
118120

119-
#. Generate a profiling header after adding/changing a HIP API.
121+
After you run the ``make install`` command, HIP is installed to ``<ROCM_PATH>`` by default, or ``$PWD/install/hip`` while ``INSTALL_PREFIX`` is defined.
120122

121-
When you add or change a HIP API, you may need to generate a new ``hip_prof_str.h`` header.
122-
This header is used by ROCm tools to track HIP APIs, such as ``rocprofiler`` and ``roctracer``.
123+
#. Generate a profiling header after adding/changing a HIP API.
123124

124-
To generate the header after your change, use the ``hip_prof_gen.py`` tool located in
125-
``hipamd/src``.
125+
When you add or change a HIP API, you may need to generate a new ``hip_prof_str.h`` header.
126+
This header is used by ROCm tools to track HIP APIs, such as ``rocprofiler`` and ``roctracer``.
126127

127-
Usage:
128+
To generate the header after your change, use the ``hip_prof_gen.py`` tool located in
129+
``hipamd/src``.
128130

129-
.. code-block:: shell
131+
Usage:
130132

131-
`hip_prof_gen.py [-v] <input HIP API .h file> <patched srcs path> <previous output> [<output>]`
133+
.. code-block:: shell
132134
133-
Flags:
135+
`hip_prof_gen.py [-v] <input HIP API .h file> <patched srcs path> <previous output> [<output>]`
134136
135-
* ``-v``: Verbose messages
136-
* ``-r``: Process source directory recursively
137-
* ``-t``: API types matching check
138-
* ``--priv``: Private API check
139-
* ``-e``: On error exit mode
140-
* ``-p``: ``HIP_INIT_API`` macro patching mode
137+
Flags:
141138
142-
Example usage:
139+
* ``-v``: Verbose messages
140+
* ``-r``: Process source directory recursively
141+
* ``-t``: API types matching check
142+
* ``--priv``: Private API check
143+
* ``-e``: On error exit mode
144+
* ``-p``: ``HIP_INIT_API`` macro patching mode
143145
144-
.. code-block:: shell
146+
Example usage:
145147

146-
hip_prof_gen.py -v -p -t --priv <hip>/include/hip/hip_runtime_api.h \
147-
<hipamd>/src <hipamd>/include/hip/amd_detail/hip_prof_str.h \
148-
<hipamd>/include/hip/amd_detail/hip_prof_str.h.new
148+
.. code-block:: shell
149149
150-
.. tab-item:: NVIDIA
151-
:sync: nvidia
150+
hip_prof_gen.py -v -p -t --priv <hip>/include/hip/hip_runtime_api.h \
151+
<hipamd>/src <hipamd>/include/hip/amd_detail/hip_prof_str.h \
152+
<hipamd>/include/hip/amd_detail/hip_prof_str.h.new
152153
153-
#. Get the HIP source code.
154+
.. tab-item:: NVIDIA
155+
:sync: nvidia
154156

155-
.. code-block:: shell
157+
#. Get the HIP source code.
156158

157-
git clone -b "$ROCM_BRANCH" https://github.com/ROCm/clr.git
158-
git clone -b "$ROCM_BRANCH" https://github.com/ROCm/hip.git
159-
git clone -b "$ROCM_BRANCH" https://github.com/ROCm/hipother.git
159+
.. code-block:: shell
160160
161-
#. Set the environment variables.
161+
git clone -b "$ROCM_BRANCH" https://github.com/ROCm/clr.git
162+
git clone -b "$ROCM_BRANCH" https://github.com/ROCm/hip.git
163+
git clone -b "$ROCM_BRANCH" https://github.com/ROCm/hipother.git
162164
163-
.. code-block:: shell
165+
#. Set the environment variables.
164166

165-
export CLR_DIR="$(readlink -f clr)"
166-
export HIP_DIR="$(readlink -f hip)"
167-
export HIP_OTHER="$(readlink -f hipother)"
167+
.. code-block:: shell
168168
169-
#. Build HIP.
169+
export CLR_DIR="$(readlink -f clr)"
170+
export HIP_DIR="$(readlink -f hip)"
171+
export HIP_OTHER="$(readlink -f hipother)"
170172
171-
.. code-block:: shell
173+
#. Build HIP.
172174

173-
cd "$CLR_DIR"
174-
mkdir -p build; cd build
175-
cmake -DHIP_COMMON_DIR=$HIP_DIR -DHIP_PLATFORM=nvidia -DCMAKE_INSTALL_PREFIX=$PWD/install -DHIP_CATCH_TEST=0 -DCLR_BUILD_HIP=ON -DCLR_BUILD_OCL=OFF -DHIPNV_DIR=$HIP_OTHER/hipnv ..
176-
make -j$(nproc)
177-
sudo make install
175+
.. code-block:: shell
176+
177+
cd "$CLR_DIR"
178+
mkdir -p build; cd build
179+
cmake -DHIP_COMMON_DIR=$HIP_DIR -DHIP_PLATFORM=nvidia -DCMAKE_INSTALL_PREFIX=$PWD/install -DHIP_CATCH_TEST=0 -DCLR_BUILD_HIP=ON -DCLR_BUILD_OCL=OFF -DHIPNV_DIR=$HIP_OTHER/hipnv ..
180+
make -j$(nproc)
181+
sudo make install
178182
179183
Build HIP tests
180184
=================================================
181185

182186
.. tab-set::
183187

184-
.. tab-item:: AMD
185-
:sync: amd
188+
.. tab-item:: AMD
189+
:sync: amd
186190

187-
* Build HIP catch tests.
191+
**Build HIP catch tests.**
188192

189-
HIP catch tests are separate from the HIP project and use Catch2.
193+
HIP catch tests are separate from the HIP project and use Catch2.
190194

191-
* Get HIP tests source code.
195+
#. Get HIP tests source code.
192196

193-
.. code-block:: shell
197+
.. code-block:: shell
194198
195-
git clone -b "$ROCM_BRANCH" https://github.com/ROCm/hip-tests.git
199+
git clone -b "$ROCM_BRANCH" https://github.com/ROCm/hip-tests.git
196200
197-
* Build HIP tests from source.
201+
#. Build HIP tests from source.
198202

199-
.. code-block:: shell
203+
.. code-block:: shell
200204
201-
export HIPTESTS_DIR="$(readlink -f hip-tests)"
202-
cd "$HIPTESTS_DIR"
203-
mkdir -p build; cd build
204-
cmake ../catch -DHIP_PLATFORM=amd -DHIP_PATH=$CLR_DIR/build/install # or any path where HIP is installed; for example: ``/opt/rocm``
205-
make build_tests
206-
ctest # run tests
205+
export HIPTESTS_DIR="$(readlink -f hip-tests)"
206+
cd "$HIPTESTS_DIR"
207+
mkdir -p build; cd build
208+
cmake ../catch -DHIP_PLATFORM=amd -DHIP_PATH=$CLR_DIR/build/install # or any path where HIP is installed; for example: ``/opt/rocm``
209+
make build_tests
210+
ctest # run tests
207211
208-
HIP catch tests are built in ``$HIPTESTS_DIR/build``.
212+
HIP catch tests are built in ``$HIPTESTS_DIR/build``.
209213

210-
To run any single catch test, use this example:
214+
To run any single catch test, use this example:
211215

212-
.. code-block:: shell
216+
.. code-block:: shell
213217
214-
cd $HIPTESTS_DIR/build/catch_tests/unit/texture
215-
./TextureTest
218+
cd $HIPTESTS_DIR/build/catch_tests/unit/texture
219+
./TextureTest
216220
217-
* Build a HIP Catch2 standalone test.
221+
#. Build a HIP Catch2 standalone test. (Optional)
218222

219-
.. code-block:: shell
223+
.. code-block:: shell
220224
221-
cd "$HIPTESTS_DIR"
222-
hipcc $HIPTESTS_DIR/catch/unit/memory/hipPointerGetAttributes.cc \
223-
-I ./catch/include ./catch/hipTestMain/standalone_main.cc \
224-
-I ./catch/external/Catch2 -o hipPointerGetAttributes
225-
./hipPointerGetAttributes
226-
...
225+
cd "$HIPTESTS_DIR"
226+
hipcc $HIPTESTS_DIR/catch/unit/memory/hipPointerGetAttributes.cc \
227+
-I ./catch/include ./catch/hipTestMain/standalone_main.cc \
228+
-I ./catch/external/Catch2 -o hipPointerGetAttributes
229+
./hipPointerGetAttributes
230+
...
227231
228-
All tests passed
232+
All tests passed
229233
230-
.. tab-item:: NVIDIA
231-
:sync: nvidia
234+
.. tab-item:: NVIDIA
235+
:sync: nvidia
232236

233-
The commands to build HIP tests on an NVIDIA platform are the same as on an AMD platform.
234-
However, you must first set ``-DHIP_PLATFORM=nvidia``.
237+
The commands to build HIP tests on an NVIDIA platform are the same as on an AMD platform.
238+
However, you must first set ``-DHIP_PLATFORM=nvidia``.
235239

236240

237241
Run HIP

0 commit comments

Comments
 (0)