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
NVIDIA · Nov 22, 2024 · f6ec34b · f6ec34b
1 parent ee46f3e
commit f6ec34b
Showing 1 changed file with 21 additions and 179 deletions.
diff --git 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 <https://github.com/NVIDIA/cccl/blob/main/CONTRIBUTING.md#building-and-testing>`_.
 
-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 <https://www.python.org/downloads/windows>`_.
-
-Download `the get-pip.py bootstrap
-script <https://bootstrap.pypa.io/get-pip.py>`_ 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