diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 7b38ba666..a2b737671 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -388,6 +388,12 @@ jobs: clang-runtime: '16' debug_build: true + - name: ubuntu-clang15-runtime16-doc + os: ubuntu-latest + compiler: clang-15 + clang-runtime: '16' + doc_build: true + steps: - uses: actions/checkout@v3 with: @@ -395,7 +401,7 @@ jobs: - name: Set up Python uses: actions/setup-python@v4 with: - python-version: 3.7 + python-version: 3.11 - name: Save PR Info if: ${{ matrix.coverage == true }} run: | @@ -779,6 +785,25 @@ jobs: done cd .. + - name: Test build sphinx & doxygen documentation + if: ${{ (matrix.doc_build == true) }} + run: | + sudo apt-get install -y doxygen graphviz + pip install --upgrade pip + pip install -r requirements.txt + mkdir -p obj && cd obj + cmake \ + -DClang_DIR="$PATH_TO_LLVM_BUILD" \ + -DLLVM_DIR="$PATH_TO_LLVM_BUILD" \ + -DCLAD_INCLUDE_DOCS=ON \ + -DCLAD_ENABLE_DOXYGEN=ON \ + -DCLAD_ENABLE_SPHINX=ON \ + -DCMAKE_INSTALL_PREFIX=../inst \ + -DCMAKE_BUILD_TYPE=Debug \ + -DLLVM_EXTERNAL_LIT="`which lit`" \ + .. + cmake --build . --target sphinx-clad -- -j4 + cmake --build . --target doxygen-clad -- -j4 - name: Failed job config if: ${{ failure() && runner.os != 'windows' }} env: diff --git a/cmake/CreateSphinxTarget.cmake b/cmake/CreateSphinxTarget.cmake index 2c5b1ba60..f3c489240 100644 --- a/cmake/CreateSphinxTarget.cmake +++ b/cmake/CreateSphinxTarget.cmake @@ -16,7 +16,7 @@ function(create_sphinx_target) add_custom_target(${SPHINX_TARGET_NAME} COMMAND - ${SPHINX_EXECUTABLE} -b html -d ${SPHINX_DOC_TREE_DIR} -q ${SPHINX_SOURCE_DIR} ${SPHINX_BUILD_DIR} + ${SPHINX_EXECUTABLE} -b html -d ${SPHINX_DOC_TREE_DIR} ${SPHINX_SOURCE_DIR} ${SPHINX_BUILD_DIR} COMMENT "Generating sphinx user documentation into \"${SPHINX_BUILD_DIR}\"" VERBATIM diff --git a/docs/userDocs/source/index.rst b/docs/userDocs/source/index.rst index af4e79265..344903b93 100644 --- a/docs/userDocs/source/index.rst +++ b/docs/userDocs/source/index.rst @@ -70,7 +70,7 @@ Features automatic differentiation is not feasible. -.. comment:: +.. comment .. todo:: diff --git a/docs/userDocs/source/user/DevelopersDocumentation.rst b/docs/userDocs/source/user/DevelopersDocumentation.rst index 986b29ef8..0f3187ef5 100644 --- a/docs/userDocs/source/user/DevelopersDocumentation.rst +++ b/docs/userDocs/source/user/DevelopersDocumentation.rst @@ -9,12 +9,12 @@ Linux (Ubuntu) .. code-block:: bash - sudo apt install clang-11 libclang-11-dev llvm-11-tools llvm-11-dev - sudo -H pip install lit - git clone https://github.com/vgvassilev/clad.git clad - mkdir build_dir inst; cd build_dir - cmake ../clad -DClang_DIR=/usr/lib/llvm-11 -DLLVM_DIR=/usr/lib/llvm-11 -DCMAKE_INSTALL_PREFIX=../inst -DCMAKE_BUILD_TYPE=Debug -DLLVM_EXTERNAL_LIT="``which lit``" - make && make install + sudo apt install clang-11 libclang-11-dev llvm-11-tools llvm-11-dev + sudo -H pip install lit + git clone https://github.com/vgvassilev/clad.git clad + mkdir build_dir inst; cd build_dir + cmake ../clad -DClang_DIR=/usr/lib/llvm-11 -DLLVM_DIR=/usr/lib/llvm-11 -DCMAKE_INSTALL_PREFIX=../inst -DCMAKE_BUILD_TYPE=Debug -DLLVM_EXTERNAL_LIT="``which lit``" + make && make install Instructions to build documentation @@ -27,7 +27,7 @@ This will also install the correct version of `sphinx` : .. code-block:: bash - pip install -r requirements.txt + pip install -r requirements.txt Make sure `doxygen` is installed if you want to build the internal documentation : @@ -40,8 +40,8 @@ To build clad and its documentation, use the following CMake command: .. code-block:: bash - cmake ../clad -DClang_DIR=/usr/lib/llvm-11 -DLLVM_DIR=/usr/lib/llvm-11 -DCLAD_INCLUDE_DOCS=ON -DCLAD_ENABLE_DOXYGEN=ON -DCLAD_ENABLE_SPHINX=ON -DCMAKE_INSTALL_PREFIX=../inst -DCMAKE_BUILD_TYPE=Debug -DLLVM_EXTERNAL_LIT="``which lit``" - make sphinx-clad doxygen-clad + cmake ../clad -DClang_DIR=/usr/lib/llvm-11 -DLLVM_DIR=/usr/lib/llvm-11 -DCLAD_INCLUDE_DOCS=ON -DCLAD_ENABLE_DOXYGEN=ON -DCLAD_ENABLE_SPHINX=ON -DCMAKE_INSTALL_PREFIX=../inst -DCMAKE_BUILD_TYPE=Debug -DLLVM_EXTERNAL_LIT="``which lit``" + make sphinx-clad doxygen-clad The built user documentation can be found in `build/docs/userDocs/build`; while the built internal documentation can be found in `build/docs/internalDocs/build`. @@ -61,16 +61,16 @@ In brief, debug build of LLVM with Clang enabled can be built using the followin instructions: .. code-block:: bash - - sudo -H pip install lit - git clone https://github.com/llvm/llvm-project.git - cd llvm-project - git checkout release/12.x - cd ../ - mkdir obj inst - cd obj - cmake ../llvm-project/llvm -DCMAKE_BUILD_TYPE=Debug -DLLVM_TARGETS_TO_BUILD=host -DLLVM_ENABLE_PROJECTS=clang -DCMAKE_INSTALL_PREFIX=../inst - make install + + sudo -H pip install lit + git clone https://github.com/llvm/llvm-project.git + cd llvm-project + git checkout release/12.x + cd ../ + mkdir obj inst + cd obj + cmake ../llvm-project/llvm -DCMAKE_BUILD_TYPE=Debug -DLLVM_TARGETS_TO_BUILD=host -DLLVM_ENABLE_PROJECTS=clang -DCMAKE_INSTALL_PREFIX=../inst + make install Please note that it is recommended to have at least 16 GB of total memory (RAM + swap) to build LLVM in debug mode. @@ -98,7 +98,7 @@ After incorporating all of these tweaks, the CMake command should look like this .. code-block:: bash - cmake -G Ninja /path/to/llvm-project/llvm -DLLVM_USE_LINKER=gold -DCMAKE_BUILD_TYPE=Debug -DLLVM_TARGETS_TO_BUILD=host -DBUILD_SHARED_LIBS=On -DLLVM_USE_SPLIT_DWARF=On -DLLVM_OPTIMIZED_TABLEGEN=On -DLLVM_ENABLE_PROJECTS=clang -DCMAKE_INSTALL_PREFIX=../inst + cmake -G Ninja /path/to/llvm-project/llvm -DLLVM_USE_LINKER=gold -DCMAKE_BUILD_TYPE=Debug -DLLVM_TARGETS_TO_BUILD=host -DBUILD_SHARED_LIBS=On -DLLVM_USE_SPLIT_DWARF=On -DLLVM_OPTIMIZED_TABLEGEN=On -DLLVM_ENABLE_PROJECTS=clang -DCMAKE_INSTALL_PREFIX=../inst Clad Internal Documentation ================================= @@ -159,50 +159,50 @@ For example, .. code-block:: bash - clang++ -g hello-world.cpp -fsyntax-only -v + clang++ -g hello-world.cpp -fsyntax-only -v This command will give output similar to .. code-block:: bash - Ubuntu clang version 11.1.0-6 - Target: x86_64-pc-linux-gnu - Thread model: posix - InstalledDir: /home/parth/Programs/bin - Found candidate GCC installation: /usr/lib/gcc/x86_64-linux-gnu/11 - Selected GCC installation: /usr/lib/gcc/x86_64-linux-gnu/11 - Candidate multilib: .;@m64 - Selected multilib: .;@m64 - (in-process) - "/usr/lib/llvm-11/bin/clang" -cc1 -triple x86_64-pc-linux-gnu - -fsyntax-only -disable-free -disable-llvm-verifier -discard-value-names - -main-file-name hello-world.cpp -mrelocation-model static - -mframe-pointer=all -fmath-errno -fno-rounding-math -mconstructor-aliases - -munwind-tables -target-cpu x86-64 -fno-split-dwarf-inlining - -debug-info-kind=limited -dwarf-version=4 -debugger-tuning=gdb - -v -resource-dir /usr/lib/llvm-11/lib/clang/11.1.0 - -internal-isystem /usr/lib/gcc/x86_64-linux-gnu/11/../../../../include/c++/11 - -internal-isystem /usr/lib/gcc/x86_64-linux-gnu/11/../../../../include/x86_64-linux-gnu/c++/11 - -internal-isystem /usr/lib/gcc/x86_64-linux-gnu/11/../../../../include/x86_64-linux-gnu/c++/11 - -internal-isystem /usr/lib/gcc/x86_64-linux-gnu/11/../../../../include/c++/11/backward - -internal-isystem /usr/local/include -internal-isystem /usr/lib/llvm-11/lib/clang/11.1.0/include - -internal-externc-isystem /usr/include/x86_64-linux-gnu -internal-externc-isystem /include - -internal-externc-isystem /usr/include -fdeprecated-macro -fdebug-compilation-dir /home/parth - -ferror-limit 19 -fgnuc-version=4.2.1 -fcxx-exceptions -fexceptions -faddrsig -x c++ hello-world.cpp - - clang -cc1 version 11.1.0 based upon LLVM 11.1.0 default target x86_64-pc-linux-gnu - ignoring nonexistent directory "/include" - ignoring duplicate directory "/usr/lib/gcc/x86_64-linux-gnu/11/../../../../include/x86_64-linux-gnu/c++/11" - #include "..." search starts here: - #include <...> search starts here: - /usr/lib/gcc/x86_64-linux-gnu/11/../../../../include/c++/11 - /usr/lib/gcc/x86_64-linux-gnu/11/../../../../include/x86_64-linux-gnu/c++/11 - /usr/lib/gcc/x86_64-linux-gnu/11/../../../../include/c++/11/backward - /usr/local/include - /usr/lib/llvm-11/lib/clang/11.1.0/include - /usr/include/x86_64-linux-gnu - /usr/include - End of search list. + Ubuntu clang version 11.1.0-6 + Target: x86_64-pc-linux-gnu + Thread model: posix + InstalledDir: /home/parth/Programs/bin + Found candidate GCC installation: /usr/lib/gcc/x86_64-linux-gnu/11 + Selected GCC installation: /usr/lib/gcc/x86_64-linux-gnu/11 + Candidate multilib: .;@m64 + Selected multilib: .;@m64 + (in-process) + "/usr/lib/llvm-11/bin/clang" -cc1 -triple x86_64-pc-linux-gnu + -fsyntax-only -disable-free -disable-llvm-verifier -discard-value-names + -main-file-name hello-world.cpp -mrelocation-model static + -mframe-pointer=all -fmath-errno -fno-rounding-math -mconstructor-aliases + -munwind-tables -target-cpu x86-64 -fno-split-dwarf-inlining + -debug-info-kind=limited -dwarf-version=4 -debugger-tuning=gdb + -v -resource-dir /usr/lib/llvm-11/lib/clang/11.1.0 + -internal-isystem /usr/lib/gcc/x86_64-linux-gnu/11/../../../../include/c++/11 + -internal-isystem /usr/lib/gcc/x86_64-linux-gnu/11/../../../../include/x86_64-linux-gnu/c++/11 + -internal-isystem /usr/lib/gcc/x86_64-linux-gnu/11/../../../../include/x86_64-linux-gnu/c++/11 + -internal-isystem /usr/lib/gcc/x86_64-linux-gnu/11/../../../../include/c++/11/backward + -internal-isystem /usr/local/include -internal-isystem /usr/lib/llvm-11/lib/clang/11.1.0/include + -internal-externc-isystem /usr/include/x86_64-linux-gnu -internal-externc-isystem /include + -internal-externc-isystem /usr/include -fdeprecated-macro -fdebug-compilation-dir /home/parth + -ferror-limit 19 -fgnuc-version=4.2.1 -fcxx-exceptions -fexceptions -faddrsig -x c++ hello-world.cpp + + clang -cc1 version 11.1.0 based upon LLVM 11.1.0 default target x86_64-pc-linux-gnu + ignoring nonexistent directory "/include" + ignoring duplicate directory "/usr/lib/gcc/x86_64-linux-gnu/11/../../../../include/x86_64-linux-gnu/c++/11" + #include "..." search starts here: + #include <...> search starts here: + /usr/lib/gcc/x86_64-linux-gnu/11/../../../../include/c++/11 + /usr/lib/gcc/x86_64-linux-gnu/11/../../../../include/x86_64-linux-gnu/c++/11 + /usr/lib/gcc/x86_64-linux-gnu/11/../../../../include/c++/11/backward + /usr/local/include + /usr/lib/llvm-11/lib/clang/11.1.0/include + /usr/include/x86_64-linux-gnu + /usr/include + End of search list. With the compiler invocation command in hand, we are ready to debug the compiler. @@ -210,10 +210,10 @@ A typical example that demonstrates debugging of a program using ``lldb`` .. code-block:: bash - lldb clang - # set breakpoints - breakpoint set -n "clang::Sema::BuildDeclRefExpr" - process launch -- {compiler-invocation-arguments} + lldb clang + # set breakpoints + breakpoint set -n "clang::Sema::BuildDeclRefExpr" + process launch -- {compiler-invocation-arguments} Replace ``{compiler-invocation-arguments}`` with the compiler invocation arguments obtained by executing the Clang driver command with ``-v`` option. diff --git a/docs/userDocs/source/user/InstallationAndUsage.rst b/docs/userDocs/source/user/InstallationAndUsage.rst index 89aedd86f..6814bccb9 100644 --- a/docs/userDocs/source/user/InstallationAndUsage.rst +++ b/docs/userDocs/source/user/InstallationAndUsage.rst @@ -12,15 +12,15 @@ Clad is available using conda : .. code-block:: bash - conda install -c conda-forge clad + conda install -c conda-forge clad If you have already added ``conda-forge`` as a channel, the ``-c conda-forge`` is unnecessary. Adding the channel is recommended because it ensures that all of your packages use compatible versions: .. code-block:: bash - conda config --add channels conda-forge - conda update --all + conda config --add channels conda-forge + conda update --all Building from source @@ -31,43 +31,43 @@ Building from source (example was tested on Ubuntu 20.04 LTS) .. code-block:: bash - #sudo apt install clang-11 libclang-11-dev llvm-11-tools llvm-11-dev - sudo bash -c "$(wget -O - https://apt.llvm.org/llvm.sh)" - sudo -H pip install lit - git clone https://github.com/vgvassilev/clad.git clad - mkdir build_dir inst; cd build_dir - cmake ../clad -DClang_DIR=/usr/lib/llvm-11 -DLLVM_DIR=/usr/lib/llvm-11 -DCMAKE_INSTALL_PREFIX=../inst -DLLVM_EXTERNAL_LIT="``which lit``" - make && make install - + #sudo apt install clang-11 libclang-11-dev llvm-11-tools llvm-11-dev + sudo bash -c "$(wget -O - https://apt.llvm.org/llvm.sh)" + sudo -H pip install lit + git clone https://github.com/vgvassilev/clad.git clad + mkdir build_dir inst; cd build_dir + cmake ../clad -DClang_DIR=/usr/lib/llvm-11 -DLLVM_DIR=/usr/lib/llvm-11 -DCMAKE_INSTALL_PREFIX=../inst -DLLVM_EXTERNAL_LIT="``which lit``" + make && make install + Building from source (example was tested on macOS Catalina 10.15.7) -------------------------------------------------------------------- .. code-block:: bash - brew install llvm@12 - brew install python - python -m pip install lit - git clone https://github.com/vgvassilev/clad.git clad - mkdir build_dir inst; cd build_dir - cmake ../clad -DLLVM_DIR=/usr/local/Cellar/llvm/12.0.0_1/lib/cmake/llvm -DClang_DIR=/usr/local/Cellar/llvm/12.0.0_1/lib/cmake/clang -DCMAKE_INSTALL_PREFIX=../inst -DLLVM_EXTERNAL_LIT="``which lit``" - make && make install - make check-clad - + brew install llvm@12 + brew install python + python -m pip install lit + git clone https://github.com/vgvassilev/clad.git clad + mkdir build_dir inst; cd build_dir + cmake ../clad -DLLVM_DIR=/usr/local/Cellar/llvm/12.0.0_1/lib/cmake/llvm -DClang_DIR=/usr/local/Cellar/llvm/12.0.0_1/lib/cmake/clang -DCMAKE_INSTALL_PREFIX=../inst -DLLVM_EXTERNAL_LIT="``which lit``" + make && make install + make check-clad + Building from source LLVM, Clang and Clad (development environment) -------------------------------------------------------------------- .. code-block:: bash - sudo -H pip install lit - git clone https://github.com/llvm/llvm-project.git src - cd src; git chekout llvmorg-13.0.0 - cd /tools - git clone https://github.com/vgvassilev/clad.git clad - cd ../../../ - mkdir obj inst - cd obj - cmake -S ../src/llvm -DLLVM_ENABLE_PROJECTS="clang" -DCMAKE_BUILD_TYPE="Debug" -DLLVM_TARGETS_TO_BUILD=host -DCMAKE_INSTALL_PREFIX=../inst - make && make install + sudo -H pip install lit + git clone https://github.com/llvm/llvm-project.git src + cd src; git chekout llvmorg-13.0.0 + cd /tools + git clone https://github.com/vgvassilev/clad.git clad + cd ../../../ + mkdir obj inst + cd obj + cmake -S ../src/llvm -DLLVM_ENABLE_PROJECTS="clang" -DCMAKE_BUILD_TYPE="Debug" -DLLVM_TARGETS_TO_BUILD=host -DCMAKE_INSTALL_PREFIX=../inst + make && make install How to use Clad ================= @@ -80,9 +80,10 @@ xeus-cling provides a Jupyter kerne To set up your environment, use: .. code-block:: bash - mamba create -n xeus-clad -c conda-forge clad xeus-cling jupyterlab - conda activate xeus-clad - jupyter notebook + + mamba create -n xeus-clad -c conda-forge clad xeus-cling jupyterlab + conda activate xeus-clad + jupyter notebook The above will launch Jupyter with 3 Clad attached kernels for C++ 11/14/17. @@ -95,25 +96,25 @@ Since Clad is a Clang plugin, it must be properly attached when the Clang compil .. code-block:: bash - clang -cc1 -x c++ -std=c++11 -load /full/path/to/lib/clad.so -plugin clad SourceFile.cpp + clang -cc1 -x c++ -std=c++11 -load /full/path/to/lib/clad.so -plugin clad SourceFile.cpp To compile using Clang < 10 , for example with clang-9, use: .. code-block:: bash - clang-9 -I /full/path/to/include/ -x c++ -std=c++11 -fplugin=/full/path/to/lib/clad.so SourceFile.cpp -o sourcefile -lstdc++ -lm + clang-9 -I /full/path/to/include/ -x c++ -std=c++11 -fplugin=/full/path/to/lib/clad.so SourceFile.cpp -o sourcefile -lstdc++ -lm To save the Clad generated derivative code to `Derivatives.cpp` add: .. code-block:: bash - -Xclang -plugin-arg-clad -Xclang -fgenerate-source-file + -Xclang -plugin-arg-clad -Xclang -fgenerate-source-file To print the Clad generated derivative add: .. code-block:: bash - -Xclang -plugin-arg-clad -Xclang -fdump-derived-fn + -Xclang -plugin-arg-clad -Xclang -fdump-derived-fn Note: Clad does not work with the Apple releases of Clang diff --git a/docs/userDocs/source/user/UsingClad.rst b/docs/userDocs/source/user/UsingClad.rst index 52104a635..0036f178a 100644 --- a/docs/userDocs/source/user/UsingClad.rst +++ b/docs/userDocs/source/user/UsingClad.rst @@ -65,7 +65,7 @@ An example that demonstrates the usage of int main() { // differentiate 'fn' w.r.t 'x'. auto d_fn_1 = clad::differentiate(fn, "x"); - + // computes derivative of 'fn' w.r.t 'x' when (x, y) = (3, 4). std::cout<