From 59ab2fd51fc8e147ca564a0ba7a882ddb9d03013 Mon Sep 17 00:00:00 2001 From: randyh62 <42045079+randyh62@users.noreply.github.com> Date: Mon, 23 Sep 2024 15:44:54 -0700 Subject: [PATCH] merge docs/6.2.0 into docs/6.2.1 (#1) * Update doc reqs * Update doc reqs * Port hipcc doc reorg to docs/6.2.0 (#130) * hipcc docs update * minor edit * remove note about llvm * fix syntax * Conditionally skip docs PR build If there is no change to the docs folder or RTD YAML compared to the amd-staging branch --------- Co-authored-by: randyh62 Co-authored-by: Sam Wu <22262939+samjwu@users.noreply.github.com> * change default version from Perl to C++ --------- Co-authored-by: Sam Wu <22262939+samjwu@users.noreply.github.com> Co-authored-by: Young Hui - AMD <145490163+yhuiYH@users.noreply.github.com> --- amd/hipcc/docs/build.md | 12 ----------- amd/hipcc/docs/build.rst | 28 ++++++++++++++++++++++++++ amd/hipcc/docs/env.md | 8 -------- amd/hipcc/docs/env.rst | 20 +++++++++++++++++++ amd/hipcc/docs/index.md | 5 ----- amd/hipcc/docs/index.rst | 33 +++++++++++++++++++++++++++++++ amd/hipcc/docs/sphinx/_toc.yml.in | 25 ++++++++++++++--------- amd/hipcc/docs/test.md | 3 --- amd/hipcc/docs/usage.md | 11 ----------- amd/hipcc/docs/usage.rst | 21 ++++++++++++++++++++ 10 files changed, 118 insertions(+), 48 deletions(-) delete mode 100644 amd/hipcc/docs/build.md create mode 100644 amd/hipcc/docs/build.rst delete mode 100644 amd/hipcc/docs/env.md create mode 100644 amd/hipcc/docs/env.rst delete mode 100644 amd/hipcc/docs/index.md create mode 100644 amd/hipcc/docs/index.rst delete mode 100644 amd/hipcc/docs/test.md delete mode 100644 amd/hipcc/docs/usage.md create mode 100644 amd/hipcc/docs/usage.rst diff --git a/amd/hipcc/docs/build.md b/amd/hipcc/docs/build.md deleted file mode 100644 index 67a974dca8f00c..00000000000000 --- a/amd/hipcc/docs/build.md +++ /dev/null @@ -1,12 +0,0 @@ -# Building - -```bash -mkdir build -cd build - -cmake .. - -make -j -``` - -The hipcc and hipconfig executables are created in the current build folder. These executables need to be copied to /opt/rocm/hip/bin folder location. Packaging and installing will be handled in future releases. diff --git a/amd/hipcc/docs/build.rst b/amd/hipcc/docs/build.rst new file mode 100644 index 00000000000000..ada0f5f42c1605 --- /dev/null +++ b/amd/hipcc/docs/build.rst @@ -0,0 +1,28 @@ +.. meta:: + :description: HIPCC environment variables + :keywords: HIPCC, ROCm, HIP tools, HIP compiler + +.. _hipcc_build: + +****************************************** +Building and testing HIPCC +****************************************** + +To build the ``hipcc`` and ``hipconfig`` executables, use the following commands. + +.. code-block:: bash + + mkdir build + cd build + + cmake .. + + make -j + +.. note:: + The tools are created in the current build folder, and will need to be copied to ``/opt/rocm/hip/bin`` folder location. + +Testing HIPCC +============= + +Currently ``hipcc`` and ``hipconfig`` tools are tested by building and running test samples that can be found at `HIP-tests `_. diff --git a/amd/hipcc/docs/env.md b/amd/hipcc/docs/env.md deleted file mode 100644 index 1c6d000846380d..00000000000000 --- a/amd/hipcc/docs/env.md +++ /dev/null @@ -1,8 +0,0 @@ -# Environment Variables - -The environment variable HIP_PLATFORM may be used to specify amd/nvidia: -- HIP_PLATFORM='amd' or HIP_PLATFORM='nvidia'. -- If HIP_PLATFORM is not set, then hipcc will attempt to auto-detect based on if nvcc is found. - -Other environment variable controls: -- CUDA_PATH : Path to CUDA SDK (default /usr/local/cuda). Used on NVIDIA platforms only. diff --git a/amd/hipcc/docs/env.rst b/amd/hipcc/docs/env.rst new file mode 100644 index 00000000000000..5d65397b1a6465 --- /dev/null +++ b/amd/hipcc/docs/env.rst @@ -0,0 +1,20 @@ +.. meta:: + :description: HIPCC environment variables + :keywords: HIPCC, ROCm, HIP tools, HIP compiler + +.. _hipcc_vars: + +****************************************** +HIPCC environment variables +****************************************** + +The environment variable ``HIP_PLATFORM`` can be used to specify ``amd`` or ``nvidia`` depending on the available backend tool flows: + +* ``HIP_PLATFORM`` = ``amd`` or ``HIP_PLATFORM`` = ``nvidia`` + +.. note:: + If ``HIP_PLATFORM`` is not set, then ``hipcc`` will attempt to auto-detect based on if the ``nvcc`` tool is found. + +Additional environment variable controls: + +* ``CUDA_PATH`` : Path to the CUDA SDK. The default is ``/usr/local/cuda``. This is only used for NVIDIA platforms. diff --git a/amd/hipcc/docs/index.md b/amd/hipcc/docs/index.md deleted file mode 100644 index b5ed99880414a7..00000000000000 --- a/amd/hipcc/docs/index.md +++ /dev/null @@ -1,5 +0,0 @@ -# HIPCC - -`hipcc` is a compiler driver utility that will call clang or nvcc, depending on target, and pass the appropriate include and library options for the target compiler and HIP infrastructure. - -There is both a Perl version, and a C++ executable version of the hipcc/hipconfig compiler driver utilities provided. Currently, by default the Perl version is used when 'hipcc' is called. To enable the C++ executable versions, set the environment variable `HIP_USE_PERL_SCRIPTS=0`. diff --git a/amd/hipcc/docs/index.rst b/amd/hipcc/docs/index.rst new file mode 100644 index 00000000000000..90bce96f62fa13 --- /dev/null +++ b/amd/hipcc/docs/index.rst @@ -0,0 +1,33 @@ +.. meta:: + :description: HIPCC command + :keywords: HIPCC, ROCm, HIP tools, HIP compiler + +.. _hipcc-docs: + +****************************************** +HIPCC documentation +****************************************** + +``hipcc`` is a compiler driver utility that will call clang or nvcc, depending on target, and pass the appropriate include and library options for the target compiler and HIP infrastructure. + +There are both Perl and C++ executable versions of the ``hipcc`` and ``hipconfig`` compiler driver utilities provided. By default the C++ version is used when ``hipcc`` is run. To enable the Perl versions of these commands set the environment variable ``HIP_USE_PERL_SCRIPTS=1``. + +The documentation is structured as follows: + +.. grid:: 2 + :gutter: 3 + + .. grid-item-card:: Installation + + * :ref:`hipcc_build` + * :ref:`hipcc_vars` + + .. grid-item-card:: How to + + * :ref:`hipcc_use` + +To contribute to the documentation, refer to +`Contributing to ROCm `_. + +You can find licensing information on the +`Licensing `_ page. diff --git a/amd/hipcc/docs/sphinx/_toc.yml.in b/amd/hipcc/docs/sphinx/_toc.yml.in index 2d55ecdef5cb4c..35c421540c687d 100644 --- a/amd/hipcc/docs/sphinx/_toc.yml.in +++ b/amd/hipcc/docs/sphinx/_toc.yml.in @@ -1,13 +1,20 @@ # Anywhere {branch} is used, the branch name will be substituted. # These comments will also be removed. +defaults: + numbered: False + maxdepth: 6 root: index subtrees: - - numbered: False - entries: - - file: env - - file: usage - - file: build - - file: test - - caption: About - entries: - - file: license + +- caption: Install + entries: + - file: build + - file: env + +- caption: How to + entries: + - file: usage + +- caption: About + entries: + - file: license.md diff --git a/amd/hipcc/docs/test.md b/amd/hipcc/docs/test.md deleted file mode 100644 index ec376cce19046b..00000000000000 --- a/amd/hipcc/docs/test.md +++ /dev/null @@ -1,3 +0,0 @@ -# Testing - -Currently hipcc/hipconfig executables are tested by building and executing HIP tests. Separate tests for hipcc/hipconfig is currently not planned. diff --git a/amd/hipcc/docs/usage.md b/amd/hipcc/docs/usage.md deleted file mode 100644 index f928af28fc3b8d..00000000000000 --- a/amd/hipcc/docs/usage.md +++ /dev/null @@ -1,11 +0,0 @@ -# Usage - -The built executables can be used the same way as the hipcc/hipconfig perl scripts. -To use the newly built executables from the build folder use ./ in front of the executable name - -Example: -```shell -./hipconfig --help -./hipcc --help -./hipcc --version -./hipconfig --full -``` diff --git a/amd/hipcc/docs/usage.rst b/amd/hipcc/docs/usage.rst new file mode 100644 index 00000000000000..b3ac11f2003bd7 --- /dev/null +++ b/amd/hipcc/docs/usage.rst @@ -0,0 +1,21 @@ +.. meta:: + :description: HIPCC environment variables + :keywords: HIPCC, ROCm, HIP tools, HIP compiler + +.. _hipcc_use: + +****************************************** +Using HIPCC +****************************************** + +The built executables can be used the same way as the ``hipcc`` and ``hipconfig`` Perl scripts. +To use the newly built executables from the build folder use ``./`` in front of the executable name. +For example: + +.. code-block:: shell + + ./hipconfig --help + ./hipcc --help + ./hipcc --version + ./hipconfig --full +