diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 0000000..9cdf2d6 --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,12 @@ +# To get started with Dependabot version updates, you'll need to specify which +# package ecosystems to update and where the package manifests are located. +# Please see the documentation for all configuration options: +# https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates + +version: 2 +updates: + - package-ecosystem: "pip" # See documentation for possible values + directory: "/docs/.sphinx" # Location of package manifests + open-pull-requests-limit: 10 + schedule: + interval: "daily" diff --git a/.gitignore b/.gitignore index 17f1f1f..3c2e310 100644 --- a/.gitignore +++ b/.gitignore @@ -5,3 +5,13 @@ # Nested build directory. /build* + +# documentation artifacts +build/ +_build/ +_images/ +_static/ +_templates/ +_toc.yml +docBin/ +_doxygen/ diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 0000000..43a0890 --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,14 @@ +# Read the Docs configuration file +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +version: 2 + +sphinx: + configuration: docs/conf.py + +formats: [htmlzip] + +python: + version: "3.8" + install: + - requirements: docs/.sphinx/requirements.txt diff --git a/README.md b/README.md index 7f5a031..6212a9b 100644 --- a/README.md +++ b/README.md @@ -5,12 +5,11 @@ - [hipcc](#hipcc) + * [Documentation](#documentation) * [Environment Variables](#envVar) * [Usage](#hipcc-usage) * [Building](#building) * [Testing](#testing) - * [Linux](#linux) - * [Windows](#windows) @@ -20,6 +19,18 @@ `hipcc` will pass-through options to the target compiler. The tools calling hipcc must ensure the compiler options are appropriate for the target compiler. +## Documentation + +Run the steps below to build documentation locally. + +``` +cd docs + +pip3 install -r .sphinx/requirements.txt + +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: @@ -63,4 +74,4 @@ The hipcc and hipconfig executables are created in the current build folder. The ### hipcc: testing -Currently hipcc/hipconfig executables are tested by building and executing HIP tests. Seperate tests for hipcc/hipconfig is currently not planned. \ No newline at end of file +Currently hipcc/hipconfig executables are tested by building and executing HIP tests. Separate tests for hipcc/hipconfig is currently not planned. diff --git a/docs/.sphinx/_toc.yml.in b/docs/.sphinx/_toc.yml.in new file mode 100644 index 0000000..0dbd778 --- /dev/null +++ b/docs/.sphinx/_toc.yml.in @@ -0,0 +1,10 @@ +# Anywhere {branch} is used, the branch name will be substituted. +# These comments will also be removed. +root: index +subtrees: + - numbered: False + entries: + - file: env + - file: usage + - file: build + - file: test diff --git a/docs/.sphinx/requirements.in b/docs/.sphinx/requirements.in new file mode 100644 index 0000000..f2b692a --- /dev/null +++ b/docs/.sphinx/requirements.in @@ -0,0 +1 @@ +rocm-docs-core==0.10.3 diff --git a/docs/.sphinx/requirements.txt b/docs/.sphinx/requirements.txt new file mode 100644 index 0000000..acd74da --- /dev/null +++ b/docs/.sphinx/requirements.txt @@ -0,0 +1,152 @@ +# +# This file is autogenerated by pip-compile with Python 3.8 +# by the following command: +# +# pip-compile requirements.in +# +accessible-pygments==0.0.3 + # via pydata-sphinx-theme +alabaster==0.7.13 + # via sphinx +babel==2.12.1 + # via + # pydata-sphinx-theme + # sphinx +beautifulsoup4==4.11.2 + # via pydata-sphinx-theme +breathe==4.34.0 + # via rocm-docs-core +certifi==2022.12.7 + # via requests +cffi==1.15.1 + # via + # cryptography + # pynacl +charset-normalizer==3.1.0 + # via requests +click==8.1.3 + # via sphinx-external-toc +cryptography==40.0.2 + # via pyjwt +deprecated==1.2.13 + # via pygithub +docutils==0.19 + # via + # breathe + # myst-parser + # pydata-sphinx-theme + # sphinx +gitdb==4.0.10 + # via gitpython +gitpython==3.1.31 + # via rocm-docs-core +idna==3.4 + # via requests +imagesize==1.4.1 + # via sphinx +importlib-metadata==6.0.0 + # via sphinx +importlib-resources==5.12.0 + # via rocm-docs-core +jinja2==3.1.2 + # via + # myst-parser + # sphinx +linkify-it-py==1.0.3 + # via myst-parser +markdown-it-py==2.2.0 + # via + # mdit-py-plugins + # myst-parser +markupsafe==2.1.2 + # via jinja2 +mdit-py-plugins==0.3.5 + # via myst-parser +mdurl==0.1.2 + # via markdown-it-py +myst-parser[linkify]==1.0.0 + # via rocm-docs-core +packaging==23.0 + # via + # pydata-sphinx-theme + # sphinx +pycparser==2.21 + # via cffi +pydata-sphinx-theme==0.13.3 + # via + # rocm-docs-core + # sphinx-book-theme +pygithub==1.58.1 + # via rocm-docs-core +pygments==2.14.0 + # via + # accessible-pygments + # pydata-sphinx-theme + # sphinx +pyjwt[crypto]==2.6.0 + # via pygithub +pynacl==1.5.0 + # via pygithub +pytz==2023.3 + # via babel +pyyaml==6.0 + # via + # myst-parser + # sphinx-external-toc +requests==2.28.2 + # via + # pygithub + # sphinx +rocm-docs-core==0.10.3 + # via -r requirements.in +smmap==5.0.0 + # via gitdb +snowballstemmer==2.2.0 + # via sphinx +soupsieve==2.4 + # via beautifulsoup4 +sphinx==5.3.0 + # via + # breathe + # myst-parser + # pydata-sphinx-theme + # rocm-docs-core + # sphinx-book-theme + # sphinx-copybutton + # sphinx-design + # sphinx-external-toc + # sphinx-notfound-page +sphinx-book-theme==1.0.1 + # via rocm-docs-core +sphinx-copybutton==0.5.1 + # via rocm-docs-core +sphinx-design==0.4.1 + # via rocm-docs-core +sphinx-external-toc==0.3.1 + # via rocm-docs-core +sphinx-notfound-page==0.8.3 + # via rocm-docs-core +sphinxcontrib-applehelp==1.0.4 + # via sphinx +sphinxcontrib-devhelp==1.0.2 + # via sphinx +sphinxcontrib-htmlhelp==2.0.1 + # via sphinx +sphinxcontrib-jsmath==1.0.1 + # via sphinx +sphinxcontrib-qthelp==1.0.3 + # via sphinx +sphinxcontrib-serializinghtml==1.1.5 + # via sphinx +typing-extensions==4.5.0 + # via pydata-sphinx-theme +uc-micro-py==1.0.1 + # via linkify-it-py +urllib3==1.26.15 + # via requests +wrapt==1.15.0 + # via deprecated +zipp==3.15.0 + # via + # importlib-metadata + # importlib-resources diff --git a/docs/build.md b/docs/build.md new file mode 100644 index 0000000..67a974d --- /dev/null +++ b/docs/build.md @@ -0,0 +1,12 @@ +# 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/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..bfd7011 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,13 @@ +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +from rocm_docs import ROCmDocs + +docs_core = ROCmDocs("HIPCC Documentation") +docs_core.setup() + +for sphinx_var in ROCmDocs.SPHINX_VARS: + globals()[sphinx_var] = getattr(docs_core, sphinx_var) diff --git a/docs/env.md b/docs/env.md new file mode 100644 index 0000000..09e82e7 --- /dev/null +++ b/docs/env.md @@ -0,0 +1,11 @@ +# 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/docs/index.md b/docs/index.md new file mode 100644 index 0000000..b5ed998 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,5 @@ +# 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/docs/test.md b/docs/test.md new file mode 100644 index 0000000..ec376cc --- /dev/null +++ b/docs/test.md @@ -0,0 +1,3 @@ +# 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/docs/usage.md b/docs/usage.md new file mode 100644 index 0000000..f928af2 --- /dev/null +++ b/docs/usage.md @@ -0,0 +1,11 @@ +# 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 +```