From f6ec34b40d69bc42c254de4aab8bda4008857c73 Mon Sep 17 00:00:00 2001 From: Michael Schellenberger Costa Date: Fri, 22 Nov 2024 13:31:30 +0100 Subject: [PATCH] Improve build instructions for libcu++ (#2881) * Improve build instructions for libcu++ * Add section about the options for the build script * Delegate more to the contributor guidelines --- .../libcudacxx/setup/building_and_testing.rst | 200 ++---------------- 1 file changed, 21 insertions(+), 179 deletions(-) diff --git a/docs/libcudacxx/setup/building_and_testing.rst b/docs/libcudacxx/setup/building_and_testing.rst index 7a420d0c09a..5b3b010a294 100644 --- a/docs/libcudacxx/setup/building_and_testing.rst +++ b/docs/libcudacxx/setup/building_and_testing.rst @@ -3,200 +3,42 @@ Building & Testing libcu++ ========================== -\*nix Systems, Native Build/Test --------------------------------- +libcu++ can be build and tested as shown in our `contributor guidelines `_. -The procedure is demonstrated for NVCC + GCC in C++11 mode on a -Debian-like Linux systems; the same basic steps are required on all -other platforms. - -Step 0: Install Build Requirements -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -In a Bash shell: - -.. code:: bash - - # Install LLVM (needed for LLVM's CMake modules) - apt-get -y install llvm - - # Install CMake - apt-get -y install cmake - - # Install the LLVM Integrated Tester (`lit`) - apt-get -y install python-pip - pip install lit - - # Env vars that should be set, or kept in mind for use later - export LIBCUDACXX_ROOT=/path/to/libcudacxx # Git repo root. - -Step 1: Generate the Build Files -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -In a Bash shell: +However, often only a small subset of the full test suite needs to be run during development. For that we rely on ``lit``. +After libcu++ has been configured either through the build scripts or directly via a cmake preset one can then run. .. code:: bash - cd ${LIBCUDACXX_ROOT} - cmake \ - -S ./ \ - -B build \ - -DCMAKE_CXX_COMPILER=$CXX \ - -DCMAKE_CUDA_COMPILER=$TOOLKIT/bin/nvcc \ - -DLIBCUDACXX_ENABLE_LIBCUDACXX_TESTS=ON - -Step 2: Build & Run the Tests -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + cd build + lit libcudacxx-cpp17/RELATIVE_PATH_TO_TEST_OR_SUBFOLDER -sv -In a Bash shell: +This will build and run all tests within ``RELATIVE_PATH_TO_TEST_OR_SUBFOLDER`` which must be a valid path within the CCCL. +Note that the name of the top level folder is the same as the name of the preset. For the build script the default is +``libcudacxx-cpp17``. As an example this is how to run all tests for ``cuda::std::span``, which are located in +``libcudacxx/test/libcudacxx/std/containers/views/views.span`` .. code:: bash - cd ${LIBCUDACXX_ROOT}/build # build directory of this repo - ../utils/nvidia/linux/perform_tests.bash --skip-libcxx-tests - -\*nix Systems, Cross Build/Test -------------------------------- - -The procedure is demonstrated for NVCC + GCC cross compiler in C++14 -mode on a Debian-like Linux systems targeting an aarch64 L4T system; the -same basic steps are required on all other platforms. - -Step 0: Install Build Prerequisites -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + cd build -Follow Step 0 for \*nix native builds/tests. + # Builds all tests within libcudacxx/test/libcudacxx/std/containers/views/views.span + lit libcudacxx-cpp17/libcudacxx/test/libcudacxx/std/containers/views/views.span -sv -.. _step-1-generate-the-build-files-1: + # Builds the individual test array.pass.cpp + lit libcudacxx-cpp17/libcudacxx/test/libcudacxx/std/containers/views/views.span/span.cons/array.pass.cpp -sv -Step 1: Generate the Build Files -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -In a Bash shell: +If only building the tests and not running them is desired one can pass ``-Dexecutor="NoopExecutor()"`` to the lit invocation. +This is especially usefull if the machine has no GPU or testing a different architecture .. code:: bash - export HOST=executor.nvidia.com - export USERNAME=ubuntu - - cd ${LIBCUDACXX_ROOT} - cmake \ - -S ./ \ - -B build \ - -DCMAKE_CUDA_COMPILER=$TOOLKIT/bin/nvcc \ - -DCMAKE_CXX_COMPILER=aarch64-linux-gnu-g++ \ - -DLIBCUDACXX_ENABLE_LIBCUDACXX_TESTS=ON \ - -DLIBCXX_EXECUTOR="SSHExecutor(host='${HOST}', username='${USERNAME}')" - -Ensure that you can SSH to the target system from the host system -without inputing a password (e.g. use SSH keys). - -.. _step-2-build-run-the-tests-1: - -Step 2: Build & Run the Tests -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Follow Step 2 for \*nix native builds/tests. - -\*nix Systems, NVRTC Build/Test -------------------------------- - -The procedure is demonstrated for NVRTC in C++11 mode on a Debian-like -Linux systems; the same basic steps are required on all other platforms. - -.. _step-0-install-build-prerequisites-1: - -Step 0: Install Build Prerequisites -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Follow Step 0 for \*nix native builds/tests. - -.. _step-1-generate-the-build-files-2: - -Step 1: Generate the Build Files -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + cd build + lit libcudacxx-cpp17/RELATIVE_PATH_TO_TEST_OR_SUBFOLDER -sv -Dexecutor="NoopExecutor()" -In a Bash shell: +Finally different standard modes can be tested by passing e.g ``--param=std=c++20`` .. code:: bash - cd ${LIBCUDACXX_ROOT} - cmake \ - -S ./ \ - -B build \ - -DCMAKE_CXX_COMPILER=$CC \ - -DCMAKE_CUDA_COMPILER=$TOOLKIT/bin/nvcc \ - -DLIBCUDACXX_ENABLE_LIBCUDACXX_TESTS=ON \ - -DLIBCUDACXX_TEST_WITH_NVRTC=ON - -.. _step-2-build-run-the-tests-2: - -Step 2: Build & Run the Tests -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Follow Step 2 for \*nix native builds/tests. - -Windows, Native Build/Test --------------------------- - -.. _step-0-install-build-requirements-1: - -Step 0: Install Build Requirements -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -`Install Python `_. - -Download `the get-pip.py bootstrap -script `_ and run it. - -Install the LLVM Integrated Tester (``lit``) using a Visual Studio -command prompt: - -.. code:: bat - - pip install lit - -Step 0.5: Launching a Build Environment -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Visual Studio comes with a few build environments that are appropriate -to use. - -The ``x64 Native Tools Command Prompt`` and other similarly named -environments will work. - -If Powershell is desired, it would be best to launch it from within the -native tools. This helps avoid configuration step issues. - -.. _step-1-generate-the-build-files-3: - -Step 1: Generate the Build Files -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -In a Visual Studio command prompt: - -.. code:: bat - - set LIBCUDACXX_ROOT=\path\to\libcudacxx # Helpful env var pointing to the git repo root. - cd %LIBCUDACXX_ROOT% - - cmake ^ - -S ./ ^ - -B build ^ - -G "Ninja" ^ - -DCMAKE_CXX_COMPILER=cl ^ - -DCMAKE_CUDA_COMPILER=nvcc ^ - -DCMAKE_CUDA_COMPILER_FORCED=ON ^ - -DLIBCUDACXX_ENABLE_LIBCUDACXX_TESTS=ON - -.. _step-2-build-run-the-tests-3: - -Step 2: Build & Run the Tests -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -``SM_ARCH`` can be set to any integer value (Ex: “80”, “86”) - -.. code:: bat - - set LIBCUDACXX_SITE_CONFIG=%LIBCUDACXX_ROOT%\build\test\lit.site.cfg - lit %LIBCUDACXX_ROOT%\test -Dcompute_archs=%SM_ARCH% -sv --no-progress-bar + cd build + lit libcudacxx-cpp17/RELATIVE_PATH_TO_TEST_OR_SUBFOLDER -sv --param=std=c++20