diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 0000000000000..6ab2bca1a4cc8 --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,11 @@ +version: 2 +updates: + - package-ecosystem: "pip" # See documentation for possible values + directory: "/amd/hipcc/docs/sphinx" # Location of package manifests + open-pull-requests-limit: 10 + schedule: + interval: "daily" + labels: + - "documentation" + reviewers: + - "samjwu" diff --git a/amd/hipcc/README.md b/amd/hipcc/README.md index 6212a9bc0d024..bc8895f8a1e17 100644 --- a/amd/hipcc/README.md +++ b/amd/hipcc/README.md @@ -5,28 +5,47 @@ - [hipcc](#hipcc) - * [Documentation](#documentation) - * [Environment Variables](#envVar) - * [Usage](#hipcc-usage) - * [Building](#building) - * [Testing](#testing) + - [Documentation](#documentation) + - [Environment Variables](#envVar) + - [Usage](#usage) + - [Building](#building) + - [Testing](#testing) ## 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. Historically, `hipcc` was provided as a script in the HIP repo ( https://github.com/ROCm-Developer-Tools/HIP/blob/main/bin/hipcc ). The `hipcc` provided in this project provides the same functionality, but is a binary rather than a script. At some point in the future, the hipcc script will be deprecated and ultimately removed from the HIP repo. +`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. `hipcc` will pass-through options to the target compiler. The tools calling hipcc must ensure the compiler options are appropriate for the target compiler. +### Building + +Building on Linux: + +```bash +mkdir build +cd build + +cmake .. + +make -j4 +``` + +The hipcc and hipconfig executables are created in the current build folder. +You may also create installable packages with : +```bash +make package +``` + ## Documentation Run the steps below to build documentation locally. -``` +```shell cd docs -pip3 install -r .sphinx/requirements.txt +pip3 install -r sphinx/requirements.txt python3 -m sphinx -T -E -b html -d _build/doctrees -D language=en . _build/html ``` @@ -34,17 +53,15 @@ python3 -m sphinx -T -E -b html -d _build/doctrees -D language=en . _build/html ### 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: -- HIP_PATH : Path to HIP directory, default is one dir level above location of hipcc. + - CUDA_PATH : Path to CUDA SDK (default /usr/local/cuda). Used on NVIDIA platforms only. -- HSA_PATH : Path to HSA dir (defaults to ../../hsa relative to abs_path of hipcc). Used on AMD platforms only. -- HIP_ROCCLR_HOME : Path to HIP/ROCclr directory. Used on AMD platforms only. -- HIP_CLANG_PATH : Path to HIP-Clang (default to ../../llvm/bin relative to hipcc's abs_path). Used on AMD platforms only. -### hipcc: usage +### 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 - @@ -56,22 +73,6 @@ Example: ./hipconfig --full ``` -when the excutables are copied to /opt/rocm/hip/bin or hip/bin. -The ./ is not required as the HIP path is added to the envirnoment variables list. - -### hipcc: 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. - ### hipcc: testing -Currently hipcc/hipconfig executables are tested by building and executing HIP tests. Separate tests for hipcc/hipconfig is currently not planned. +Currently hipcc/hipconfig executables are tested by building and executing HIP tests: https://github.com/ROCm/hip-tests diff --git a/amd/hipcc/docs/build.md b/amd/hipcc/docs/build.md deleted file mode 100644 index 67a974dca8f00..0000000000000 --- 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 0000000000000..ada0f5f42c160 --- /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 09e82e7ae541d..0000000000000 --- a/amd/hipcc/docs/env.md +++ /dev/null @@ -1,11 +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: -- HIP_PATH : Path to HIP directory, default is one dir level above location of hipcc. -- CUDA_PATH : Path to CUDA SDK (default /usr/local/cuda). Used on NVIDIA platforms only. -- HIP_ROCCLR_HOME : Path to HIP/ROCclr directory. Used on AMD platforms only. -- HIP_CLANG_PATH : Path to HIP-Clang (default to ../../llvm/bin relative to hipcc's abs_path). Used on AMD platforms only. diff --git a/amd/hipcc/docs/env.rst b/amd/hipcc/docs/env.rst new file mode 100644 index 0000000000000..5d65397b1a646 --- /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 b5ed99880414a..0000000000000 --- 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 0000000000000..0d3bdb0bd6c74 --- /dev/null +++ b/amd/hipcc/docs/index.rst @@ -0,0 +1,34 @@ +.. 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``. + + +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/license.md b/amd/hipcc/docs/license.md new file mode 100644 index 0000000000000..bfc65acd0326f --- /dev/null +++ b/amd/hipcc/docs/license.md @@ -0,0 +1,4 @@ +# License + +```{include} ../LICENSE.txt +``` diff --git a/amd/hipcc/docs/sphinx/_toc.yml.in b/amd/hipcc/docs/sphinx/_toc.yml.in index 0dbd7788147f5..35c421540c687 100644 --- a/amd/hipcc/docs/sphinx/_toc.yml.in +++ b/amd/hipcc/docs/sphinx/_toc.yml.in @@ -1,10 +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: 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 ec376cce19046..0000000000000 --- 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 f928af28fc3b8..0000000000000 --- 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 0000000000000..b3ac11f2003bd --- /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 +