From 6e62a0873199c20c1f12186540734ed523d19c29 Mon Sep 17 00:00:00 2001 From: randyh62 Date: Wed, 1 May 2024 15:50:05 -0700 Subject: [PATCH 1/5] hipcc docs update --- amd/hipcc/docs/build.md | 12 ----------- amd/hipcc/docs/build.rst | 28 ++++++++++++++++++++++++ amd/hipcc/docs/env.md | 8 ------- amd/hipcc/docs/env.rst | 23 ++++++++++++++++++++ amd/hipcc/docs/index.md | 5 ----- amd/hipcc/docs/index.rst | 36 +++++++++++++++++++++++++++++++ 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, 124 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..6891f828add8ab --- /dev/null +++ b/amd/hipcc/docs/env.rst @@ -0,0 +1,23 @@ +.. 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: + +* ``HIP_PATH`` : Path to HIP directory. The default is one dir level above the location of ``hipcc``. +* ``CUDA_PATH`` : Path to the CUDA SDK. The default is ``/usr/local/cuda``. This is only used for NVIDIA platforms. +* ``HIP_ROCCLR_HOME`` : Path to ``HIP/ROCclr`` directory. This is only used for AMD platforms. +* ``HIP_CLANG_PATH`` : Path to HIP-Clang. The default is ``../../llvm/bin`` relative to the absolute path of ``hipcc``). This is only used for AMD 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..3a5a929cc64480 --- /dev/null +++ b/amd/hipcc/docs/index.rst @@ -0,0 +1,36 @@ +.. 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 is both a Perl version, and a C++ executable version of the ``hipcc`` and ``hipconfig`` compiler driver utilities provided. By default the Perl version is used when ``hipcc`` is run. To enable the C++ versions, set the environment variable ``HIP_USE_PERL_SCRIPTS=0``. + +.. note:: + This is a deprecated, read-only mirror. It is kept up-to-date to facilitate transition to its new home under the ``amd/`` subdirectory in the `llvm-project `_ repository. Refer to that location for additional details. + +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 + From c1c264ed97a68a93a72a2d44325f75cc5603de99 Mon Sep 17 00:00:00 2001 From: randyh62 Date: Wed, 1 May 2024 15:57:08 -0700 Subject: [PATCH 2/5] minor edit --- amd/hipcc/docs/env.rst | 3 --- 1 file changed, 3 deletions(-) diff --git a/amd/hipcc/docs/env.rst b/amd/hipcc/docs/env.rst index 6891f828add8ab..6829f62ee18902 100644 --- a/amd/hipcc/docs/env.rst +++ b/amd/hipcc/docs/env.rst @@ -17,7 +17,4 @@ The environment variable ``HIP_PLATFORM`` can be used to specify ``amd`` or ``nv Additional environment variable controls: -* ``HIP_PATH`` : Path to HIP directory. The default is one dir level above the location of ``hipcc``. * ``CUDA_PATH`` : Path to the CUDA SDK. The default is ``/usr/local/cuda``. This is only used for NVIDIA platforms. -* ``HIP_ROCCLR_HOME`` : Path to ``HIP/ROCclr`` directory. This is only used for AMD platforms. -* ``HIP_CLANG_PATH`` : Path to HIP-Clang. The default is ``../../llvm/bin`` relative to the absolute path of ``hipcc``). This is only used for AMD platforms. From 3fd1b384f577d310fddd607f0800d1ca01fca749 Mon Sep 17 00:00:00 2001 From: randyh62 Date: Thu, 2 May 2024 09:47:45 -0700 Subject: [PATCH 3/5] remove note about llvm --- amd/hipcc/docs/index.rst | 2 -- 1 file changed, 2 deletions(-) diff --git a/amd/hipcc/docs/index.rst b/amd/hipcc/docs/index.rst index 3a5a929cc64480..0d3bdb0bd6c745 100644 --- a/amd/hipcc/docs/index.rst +++ b/amd/hipcc/docs/index.rst @@ -12,8 +12,6 @@ HIPCC documentation There is both a Perl version, and a C++ executable version of the ``hipcc`` and ``hipconfig`` compiler driver utilities provided. By default the Perl version is used when ``hipcc`` is run. To enable the C++ versions, set the environment variable ``HIP_USE_PERL_SCRIPTS=0``. -.. note:: - This is a deprecated, read-only mirror. It is kept up-to-date to facilitate transition to its new home under the ``amd/`` subdirectory in the `llvm-project `_ repository. Refer to that location for additional details. The documentation is structured as follows: From 06cc505b20c949cd231d6431218325412ecd882e Mon Sep 17 00:00:00 2001 From: Young Hui Date: Wed, 22 May 2024 21:51:43 -0400 Subject: [PATCH 4/5] fix syntax --- amd/hipcc/docs/env.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/amd/hipcc/docs/env.rst b/amd/hipcc/docs/env.rst index 6829f62ee18902..5d65397b1a6465 100644 --- a/amd/hipcc/docs/env.rst +++ b/amd/hipcc/docs/env.rst @@ -10,7 +10,7 @@ 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'. +* ``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. From 5e81ab50788a8a674598565edb17ac981de419b6 Mon Sep 17 00:00:00 2001 From: Sam Wu <22262939+samjwu@users.noreply.github.com> Date: Tue, 16 Jul 2024 11:23:25 -0600 Subject: [PATCH 5/5] Conditionally skip docs PR build If there is no change to the docs folder or RTD YAML compared to the amd-staging branch --- amd/hipcc/.readthedocs.yaml | 13 +++++++++++++ openmp/.readthedocs.yaml | 13 +++++++++++++ 2 files changed, 26 insertions(+) diff --git a/amd/hipcc/.readthedocs.yaml b/amd/hipcc/.readthedocs.yaml index 173be2324e82d0..523980fe04cd0c 100644 --- a/amd/hipcc/.readthedocs.yaml +++ b/amd/hipcc/.readthedocs.yaml @@ -16,3 +16,16 @@ build: os: ubuntu-22.04 tools: python: "3.10" + jobs: + post_checkout: + # Cancel building pull requests when there aren't changed in the docs directory or YAML file. + # You can add any other files or directories that you'd like here as well, + # like your docs requirements file, or other files that will change your docs build. + # + # If there are no changes (git diff exits with 0) we force the command to return with 183. + # This is a special exit code on Read the Docs that will cancel the build immediately. + - | + if [ "$READTHEDOCS_VERSION_TYPE" = "external" ] && git diff --quiet origin/amd-staging -- docs/ .readthedocs.yaml; + then + exit 183; + fi diff --git a/openmp/.readthedocs.yaml b/openmp/.readthedocs.yaml index 6620c7abff2445..a3dda80bd22097 100644 --- a/openmp/.readthedocs.yaml +++ b/openmp/.readthedocs.yaml @@ -16,3 +16,16 @@ build: os: ubuntu-22.04 tools: python: "3.10" + jobs: + post_checkout: + # Cancel building pull requests when there aren't changed in the docs directory or YAML file. + # You can add any other files or directories that you'd like here as well, + # like your docs requirements file, or other files that will change your docs build. + # + # If there are no changes (git diff exits with 0) we force the command to return with 183. + # This is a special exit code on Read the Docs that will cancel the build immediately. + - | + if [ "$READTHEDOCS_VERSION_TYPE" = "external" ] && git diff --quiet origin/amd-staging -- docs/ .readthedocs.yaml; + then + exit 183; + fi