From 6bf73b52fba406bd56dc946c48255de19491e89a Mon Sep 17 00:00:00 2001 From: Alexander Penev Date: Sun, 3 Dec 2023 10:26:52 +0000 Subject: [PATCH 01/14] Add test build of documentation --- .github/workflows/ci.yml | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 7b38ba666..9e2371e48 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -388,6 +388,12 @@ jobs: clang-runtime: '16' debug_build: true + - name: ubu22-clang15-runtime16-doc + os: ubuntu-22.04 + compiler: clang-15 + clang-runtime: '16' + doc_build: true + steps: - uses: actions/checkout@v3 with: @@ -779,6 +785,23 @@ jobs: done cd .. + - name: Test build sphinx documentation (clad.readthedocs.io) + if: ${{ (matrix.doc_build == true) }} + run: | + sudo apt-get install -y doxygen + 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 doxygen-clad -- -j4 - name: Failed job config if: ${{ failure() && runner.os != 'windows' }} env: From 0731fb556a25751e5f7d23edde5d885d8c0b8a61 Mon Sep 17 00:00:00 2001 From: Alexander Penev Date: Sun, 3 Dec 2023 10:37:10 +0000 Subject: [PATCH 02/14] Use latest ubuntu in doc duild matrix --- .github/workflows/ci.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 9e2371e48..a6dadb9d2 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -388,8 +388,8 @@ jobs: clang-runtime: '16' debug_build: true - - name: ubu22-clang15-runtime16-doc - os: ubuntu-22.04 + - name: ubuntu-clang15-runtime16-doc + os: ubuntu-latest compiler: clang-15 clang-runtime: '16' doc_build: true From 672cb5738f0bdeebf6c3d24c3226bf6cef827aae Mon Sep 17 00:00:00 2001 From: Alexander Penev Date: Sun, 3 Dec 2023 10:49:54 +0000 Subject: [PATCH 03/14] Fix doc build --- .github/workflows/ci.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index a6dadb9d2..b09d0227a 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -789,6 +789,7 @@ jobs: if: ${{ (matrix.doc_build == true) }} run: | sudo apt-get install -y doxygen + pip install --upgrade pip pip install -r requirements.txt mkdir -p obj && cd obj cmake \ From b89ba22181c801eb3280d6727f8a4cc7aa3ef34b Mon Sep 17 00:00:00 2001 From: Alexander Penev Date: Sun, 3 Dec 2023 11:01:26 +0000 Subject: [PATCH 04/14] Extend tmate debug time --- .github/workflows/ci.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index b09d0227a..cea378fd0 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -828,7 +828,7 @@ jobs: if: ${{ failure() }} uses: mxschmitt/action-tmate@v3 # When debugging increase to a suitable value! - timeout-minutes: ${{ github.event.pull_request && 1 || 20 }} + timeout-minutes: ${{ github.event.pull_request && 100 || 20 }} - name: Prepare code coverage report if: ${{ success() && (matrix.coverage == true) }} run: | From 975e0d5f9b807da3212d3a306f78f5f20ace7104 Mon Sep 17 00:00:00 2001 From: Alexander Penev Date: Sun, 3 Dec 2023 11:32:22 +0000 Subject: [PATCH 05/14] Fix doc build --- .github/workflows/ci.yml | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index cea378fd0..56a13fa92 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -399,9 +399,15 @@ jobs: with: fetch-depth: 0 - name: Set up Python + if: ${{ (matrix.doc_build != true) }} uses: actions/setup-python@v4 with: python-version: 3.7 + - name: Set up Python + if: ${{ (matrix.doc_build == true) }} + uses: actions/setup-python@v4 + with: + python-version: 3.11 - name: Save PR Info if: ${{ matrix.coverage == true }} run: | @@ -785,7 +791,7 @@ jobs: done cd .. - - name: Test build sphinx documentation (clad.readthedocs.io) + - name: Test build sphinx & doxygen documentation if: ${{ (matrix.doc_build == true) }} run: | sudo apt-get install -y doxygen @@ -800,7 +806,7 @@ jobs: -DCLAD_ENABLE_SPHINX=ON \ -DCMAKE_INSTALL_PREFIX=../inst \ -DCMAKE_BUILD_TYPE=Debug \ - -DLLVM_EXTERNAL_LIT="``which lit``" \ + -DLLVM_EXTERNAL_LIT="`which lit`" \ .. cmake --build . --target sphinx-clad doxygen-clad -- -j4 - name: Failed job config From c390108451ea6ca855a4db9890348947404baba7 Mon Sep 17 00:00:00 2001 From: Alexander Penev Date: Sun, 3 Dec 2023 13:36:37 +0000 Subject: [PATCH 06/14] Fix doc build --- .github/workflows/ci.yml | 8 +------- 1 file changed, 1 insertion(+), 7 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 56a13fa92..fc83d3383 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -399,15 +399,9 @@ jobs: with: fetch-depth: 0 - name: Set up Python - if: ${{ (matrix.doc_build != true) }} uses: actions/setup-python@v4 with: - python-version: 3.7 - - name: Set up Python - if: ${{ (matrix.doc_build == true) }} - uses: actions/setup-python@v4 - with: - python-version: 3.11 + python-version: ${{ matrix.doc_build && 3.11 || 3.11 }} - name: Save PR Info if: ${{ matrix.coverage == true }} run: | From e00cf72f6fbf9e1782141a5455ead14a9e3eb870 Mon Sep 17 00:00:00 2001 From: Alexander Penev Date: Sun, 3 Dec 2023 13:50:27 +0000 Subject: [PATCH 07/14] Fix doc build --- .github/workflows/ci.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index fc83d3383..344c04b02 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -401,7 +401,7 @@ jobs: - name: Set up Python uses: actions/setup-python@v4 with: - python-version: ${{ matrix.doc_build && 3.11 || 3.11 }} + python-version: 3.11 - name: Save PR Info if: ${{ matrix.coverage == true }} run: | From f49922d8e2eea209b925539f844244a217ea18b7 Mon Sep 17 00:00:00 2001 From: Alexander Penev Date: Sun, 3 Dec 2023 14:05:00 +0000 Subject: [PATCH 08/14] Fix doc build --- .github/workflows/ci.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 344c04b02..a3d334c15 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -828,7 +828,7 @@ jobs: if: ${{ failure() }} uses: mxschmitt/action-tmate@v3 # When debugging increase to a suitable value! - timeout-minutes: ${{ github.event.pull_request && 100 || 20 }} + timeout-minutes: ${{ github.event.pull_request && 1 || 20 }} - name: Prepare code coverage report if: ${{ success() && (matrix.coverage == true) }} run: | From d8bc322d97a804cac9abe37ad89491ccb5abf8c4 Mon Sep 17 00:00:00 2001 From: Alexander Penev Date: Sun, 3 Dec 2023 20:46:32 +0000 Subject: [PATCH 09/14] Remove -q param --- .github/workflows/ci.yml | 3 ++- cmake/CreateSphinxTarget.cmake | 2 +- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index a3d334c15..afc16c045 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -802,7 +802,8 @@ jobs: -DCMAKE_BUILD_TYPE=Debug \ -DLLVM_EXTERNAL_LIT="`which lit`" \ .. - cmake --build . --target sphinx-clad doxygen-clad -- -j4 + 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 From b47a8de9134e0a508e0a8b553d0daaeb16ab99f4 Mon Sep 17 00:00:00 2001 From: Alexander Penev Date: Sun, 3 Dec 2023 21:20:08 +0000 Subject: [PATCH 10/14] Fix debug time --- .github/workflows/ci.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index afc16c045..fac4199b2 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -829,7 +829,7 @@ jobs: if: ${{ failure() }} uses: mxschmitt/action-tmate@v3 # When debugging increase to a suitable value! - timeout-minutes: ${{ github.event.pull_request && 1 || 20 }} + timeout-minutes: ${{ github.event.pull_request && 100 || 20 }} - name: Prepare code coverage report if: ${{ success() && (matrix.coverage == true) }} run: | From 3dd4cc5af7e0969a9f0af81aa4625d86f8152032 Mon Sep 17 00:00:00 2001 From: Alexander Penev Date: Sun, 3 Dec 2023 21:28:12 +0000 Subject: [PATCH 11/14] Fix build --- .github/workflows/ci.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index fac4199b2..c525f2061 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -804,6 +804,7 @@ jobs: .. cmake --build . --target sphinx-clad -- -j4 cmake --build . --target doxygen-clad -- -j4 + exit 1 - name: Failed job config if: ${{ failure() && runner.os != 'windows' }} env: From 230eee62571bf9dd29f284ba5da74587607f567f Mon Sep 17 00:00:00 2001 From: Alexander Penev Date: Mon, 4 Dec 2023 06:35:37 +0000 Subject: [PATCH 12/14] Fix build --- .github/workflows/ci.yml | 2 +- requirements.txt | 1 + 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index c525f2061..bc8ae2214 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -788,7 +788,7 @@ jobs: - name: Test build sphinx & doxygen documentation if: ${{ (matrix.doc_build == true) }} run: | - sudo apt-get install -y doxygen + sudo apt-get install -y doxygen graphviz pip install --upgrade pip pip install -r requirements.txt mkdir -p obj && cd obj diff --git a/requirements.txt b/requirements.txt index abb5e1168..7e814a83b 100644 --- a/requirements.txt +++ b/requirements.txt @@ -18,4 +18,5 @@ sphinxcontrib-htmlhelp==2.0.1 sphinxcontrib-jsmath==1.0.1 sphinxcontrib-qthelp==1.0.3 sphinxcontrib-serializinghtml==1.1.5 +sphinxcontrib-comments urllib3==2.0.7 From 64ba2a8ba6f7b93e360ef695914aba1ac2e44ec5 Mon Sep 17 00:00:00 2001 From: Alexander Penev Date: Mon, 4 Dec 2023 08:38:02 +0000 Subject: [PATCH 13/14] Fix build --- requirements.txt | 1 - 1 file changed, 1 deletion(-) diff --git a/requirements.txt b/requirements.txt index 7e814a83b..abb5e1168 100644 --- a/requirements.txt +++ b/requirements.txt @@ -18,5 +18,4 @@ sphinxcontrib-htmlhelp==2.0.1 sphinxcontrib-jsmath==1.0.1 sphinxcontrib-qthelp==1.0.3 sphinxcontrib-serializinghtml==1.1.5 -sphinxcontrib-comments urllib3==2.0.7 From b20441da421cade439f73c64c5d73e93fee64819 Mon Sep 17 00:00:00 2001 From: Alexander Penev Date: Tue, 5 Dec 2023 03:46:17 +0000 Subject: [PATCH 14/14] Fix doc --- docs/userDocs/source/index.rst | 2 +- .../source/user/DevelopersDocumentation.rst | 126 +++++++++--------- .../source/user/InstallationAndUsage.rst | 75 ++++++----- docs/userDocs/source/user/UsingClad.rst | 6 +- .../source/user/UsingEnzymeWithinClad.rst | 2 +- docs/userDocs/source/user/UsingVectorMode.rst | 4 +- 6 files changed, 108 insertions(+), 107 deletions(-) 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<