Merge pull request #1408 from mickem/ci-build-speedups

ci: Speed up the Linux builds (parallel make, ccache, docs out of ALL)

Author: mickem

.github/workflows/build-debian.yml

@@ -55,10 +55,46 @@ jobs:
           done
         }
         retry apt-get update
-        retry env DEBIAN_FRONTEND=noninteractive apt-get install -y git curl unzip libboost-all-dev libgtest-dev protobuf-compiler libprotobuf-dev openssl libssl-dev libgmock-dev libcrypto++-dev ${{ matrix.lua_package }} cmake build-essential python3-pip libdbus-1-dev libzip-dev libtinyxml2-dev libmariadb-dev pkg-config
+        # ccache: see the "Configure ccache" step below. zstd: actions/cache
+        # compresses with it when present and falls back to a slower gzip when
+        # it is not.
+        retry env DEBIAN_FRONTEND=noninteractive apt-get install -y git curl unzip libboost-all-dev libgtest-dev protobuf-compiler libprotobuf-dev openssl libssl-dev libgmock-dev libcrypto++-dev ${{ matrix.lua_package }} cmake build-essential python3-pip libdbus-1-dev libzip-dev libtinyxml2-dev libmariadb-dev pkg-config ccache zstd
 
     - uses: actions/checkout@v6
 
+    - name: Configure ccache
+      shell: bash
+      run: |
+        # Every push recompiles all ~820 translation units from scratch, six
+        # times over (four packages, the sanitizer job, three Windows builds),
+        # so a compiler cache is the biggest lever left after -j.
+        #
+        # The cache lives inside the workspace on purpose: `path:` in the cache
+        # step is resolved relative to it, and it is the one directory whose
+        # location is spelled the same way by actions/cache and by the build
+        # running inside this container. It has to be restored *after* checkout,
+        # which prunes untracked files from the workspace.
+        if command -v ccache > /dev/null; then
+          echo "CCACHE_DIR=$GITHUB_WORKSPACE/.ccache" >> "$GITHUB_ENV"
+          echo "CCACHE_MAXSIZE=500M" >> "$GITHUB_ENV"
+          # Read by the CMake step; stays empty when ccache is unavailable so
+          # the build still configures, just without a launcher.
+          echo "CCACHE_LAUNCHER=ccache" >> "$GITHUB_ENV"
+        else
+          echo "::warning::ccache not available - building without a compiler cache"
+        fi
+
+    - name: Restore ccache
+      uses: actions/cache@v4
+      with:
+        path: .ccache
+        # The sha in the key makes every run write a fresh entry; restore-keys
+        # then picks the most recent one for this distro/arch. A branch also
+        # sees main's caches, so a new branch starts warm.
+        key: ccache-deb-${{ matrix.distro }}-${{ matrix.distro_version }}-${{ matrix.arch }}-${{ github.sha }}
+        restore-keys: |
+          ccache-deb-${{ matrix.distro }}-${{ matrix.distro_version }}-${{ matrix.arch }}-
+
     - name: make dirs
       run: |
         mkdir -p tmp/nscp
@@ -108,6 +144,7 @@ jobs:
         # container; $GITHUB_WORKSPACE is set per-runtime to the
         # container-mounted workspace path (`/__w/nscp/nscp`).
         cmake ../.. \
+          ${CCACHE_LAUNCHER:+-DCMAKE_C_COMPILER_LAUNCHER=$CCACHE_LAUNCHER -DCMAKE_CXX_COMPILER_LAUNCHER=$CCACHE_LAUNCHER} \
           -DBUILD_VERSION=${{ inputs.version }} \
           -DCPACK_GENERATOR=DEB \
           -DCMAKE_BUILD_TYPE=Release \
@@ -121,7 +158,19 @@ jobs:
     - name: Build nsclient
       working-directory: tmp/nscp
       run: |
-        make
+        # -j matters more here than anywhere else in the build: this single
+        # step is ~96% of the job, and the 70-odd modules are independent, so
+        # the graph is wide enough to keep every core busy (a full build
+        # measured 1433% CPU at -j16). A bare `make` left three of the
+        # runner's four cores idle for 40+ minutes.
+        if [ -n "${CCACHE_LAUNCHER:-}" ]; then ccache --zero-stats; fi
+        make -j"$(nproc)"
+
+    - name: ccache statistics
+      if: always()
+      shell: bash
+      run: |
+        if [ -n "${CCACHE_LAUNCHER:-}" ]; then ccache --show-stats; fi
 
     - name: CPack
       working-directory: tmp/nscp

.github/workflows/build-redhat.yml

@@ -80,9 +80,33 @@ jobs:
         retry dnf update -y
         # Node.js / npm are no longer needed here: the web bundle ships
         # separately and is installed at runtime via `nscp web install-ui`.
-        retry dnf install -y --allowerasing coreutils bash file findutils git boost-devel gtest-devel protobuf-compiler protobuf-devel openssl openssl-devel gmock-devel cryptopp-devel lua-devel cmake gcc-c++ python3-pip rpm-build python3-devel dbus-devel bash libzip-devel tinyxml2-devel mariadb-connector-c-devel pkgconf-pkg-config
+        # ccache comes from EPEL, which is already enabled above. zstd lets
+        # actions/cache compress with zstd instead of falling back to gzip.
+        retry dnf install -y --allowerasing coreutils bash file findutils git boost-devel gtest-devel protobuf-compiler protobuf-devel openssl openssl-devel gmock-devel cryptopp-devel lua-devel cmake gcc-c++ python3-pip rpm-build python3-devel dbus-devel bash libzip-devel tinyxml2-devel mariadb-connector-c-devel pkgconf-pkg-config ccache zstd
     - uses: actions/checkout@v6
 
+    - name: Configure ccache
+      shell: bash
+      run: |
+        # See build-debian.yml for the rationale and for why the cache lives
+        # inside the workspace. ccache is an EPEL package here, so the guard
+        # below is what keeps the build working if it ever goes missing.
+        if command -v ccache > /dev/null; then
+          echo "CCACHE_DIR=$GITHUB_WORKSPACE/.ccache" >> "$GITHUB_ENV"
+          echo "CCACHE_MAXSIZE=500M" >> "$GITHUB_ENV"
+          echo "CCACHE_LAUNCHER=ccache" >> "$GITHUB_ENV"
+        else
+          echo "::warning::ccache not available - building without a compiler cache"
+        fi
+
+    - name: Restore ccache
+      uses: actions/cache@v4
+      with:
+        path: .ccache
+        key: ccache-rpm-${{ matrix.distro }}-${{ matrix.distro_version }}-${{ matrix.arch }}-${{ github.sha }}
+        restore-keys: |
+          ccache-rpm-${{ matrix.distro }}-${{ matrix.distro_version }}-${{ matrix.arch }}-
+
     - name: make dirs
       run: |
         mkdir -p tmp/nscp
@@ -122,6 +146,7 @@ jobs:
         # resolve to the container-mounted workspace, not the runner
         # host's view. See build-debian.yml for the full rationale.
         cmake ../.. \
+          ${CCACHE_LAUNCHER:+-DCMAKE_C_COMPILER_LAUNCHER=$CCACHE_LAUNCHER -DCMAKE_CXX_COMPILER_LAUNCHER=$CCACHE_LAUNCHER} \
           -DBUILD_VERSION=${{ inputs.version }} \
           -DCPACK_GENERATOR=RPM \
           -DCMAKE_BUILD_TYPE=Release \
@@ -135,7 +160,16 @@ jobs:
     - name: Build nsclient
       working-directory: tmp/nscp
       run: |
-        make
+        # See build-debian.yml: this step is ~97% of the job and the module
+        # graph is wide, so a serial `make` wasted three of the four cores.
+        if [ -n "${CCACHE_LAUNCHER:-}" ]; then ccache --zero-stats; fi
+        make -j"$(nproc)"
+
+    - name: ccache statistics
+      if: always()
+      shell: bash
+      run: |
+        if [ -n "${CCACHE_LAUNCHER:-}" ]; then ccache --show-stats; fi
 
     - name: CPack
       working-directory: tmp/nscp

.github/workflows/tests-sanitizers.yml

@@ -44,10 +44,32 @@ jobs:
           protobuf-compiler libprotobuf-dev \
           openssl libssl-dev libcrypto++-dev \
           liblua5.4-dev libdbus-1-dev \
-          libzip-dev libtinyxml2-dev libmariadb-dev
+          libzip-dev libtinyxml2-dev libmariadb-dev \
+          ccache zstd
 
     - uses: actions/checkout@v6
 
+    - name: Configure ccache
+      shell: bash
+      run: |
+        # See build-debian.yml. This job is the slowest of the Linux three
+        # (sanitizer instrumentation plus -g), so it has the most to gain.
+        if command -v ccache > /dev/null; then
+          echo "CCACHE_DIR=$GITHUB_WORKSPACE/.ccache" >> "$GITHUB_ENV"
+          echo "CCACHE_MAXSIZE=500M" >> "$GITHUB_ENV"
+          echo "CCACHE_LAUNCHER=ccache" >> "$GITHUB_ENV"
+        else
+          echo "::warning::ccache not available - building without a compiler cache"
+        fi
+
+    - name: Restore ccache
+      uses: actions/cache@v4
+      with:
+        path: .ccache
+        key: ccache-asan-ubuntu-24.04-x64-${{ github.sha }}
+        restore-keys: |
+          ccache-asan-ubuntu-24.04-x64-
+
     - uses: actions/setup-node@v6
       with:
         node-version: 20
@@ -74,6 +96,7 @@ jobs:
         # binary — sanitizer tests don't need it, and building the Rust
         # client just for this run is wasteful.
         cmake ../.. \
+          ${CCACHE_LAUNCHER:+-DCMAKE_C_COMPILER_LAUNCHER=$CCACHE_LAUNCHER -DCMAKE_CXX_COMPILER_LAUNCHER=$CCACHE_LAUNCHER} \
           -DBUILD_VERSION=${{ inputs.version }} \
           -DCMAKE_BUILD_TYPE=RelWithDebInfo \
           -DNSCP_SANITIZE=address,undefined \
@@ -90,7 +113,15 @@ jobs:
         # its arena on exit. Disable leak-check during the build phase only;
         # we re-enable it for the test phase below.
         ASAN_OPTIONS: detect_leaks=0
-      run: cmake --build . -j$(nproc)
+      run: |
+        if [ -n "${CCACHE_LAUNCHER:-}" ]; then ccache --zero-stats; fi
+        cmake --build . -j$(nproc)
+
+    - name: ccache statistics
+      if: always()
+      shell: bash
+      run: |
+        if [ -n "${CCACHE_LAUNCHER:-}" ]; then ccache --show-stats; fi
 
     - name: Run unit tests under sanitizers
       working-directory: tmp/nscp

build.md

@@ -95,6 +95,7 @@ with `-DNSCP_CMAKE_CONFIG=<file>`).
 | `NSCP_WEB_BACKEND`          | `mongoose`       | HTTP/REST backend for `WEBServer`: `mongoose` (needs the vendored Mongoose source) or `beast` (header-only, **requires OpenSSL**). The Linux package builds use `beast`. |
 | `NSCP_BOOST_PYTHON_VERSION` | —                | Boost.Python component matching your Python, e.g. `python311`, `python312`, `python313`. Only relevant when building `PythonScript`.                                     |
 | `NSCP_SANITIZE`             | `off`            | Comma-separated sanitizer list for gcc/clang on Linux: `address`, `undefined`, `address,undefined`, `thread`. See `tools/sanitizers/run.sh`.                             |
+| `NSCP_BUILD_DOCS_HTML`      | `ON` on Windows, `OFF` elsewhere | Build the mkdocs HTML site as part of the default target. Only the Windows installer ships the site; elsewhere build it on demand with `cmake --build . --target build_docs_html`. |
 | `USE_STATIC_RUNTIME`        | `OFF`            | Link the C/C++ runtime statically (used by the Win32 static build).                                                                                                      |
 | `USE_SYSTEMD`               | `ON` (Linux)     | Install systemd service files in the package.                                                                                                                            |
 | `USE_INITD`                 | `OFF` (Linux)    | Install legacy init.d scripts in the package.                                                                                                                            |

docs/CMakeLists.txt

@@ -129,9 +129,40 @@ if(MKDOCS_FOUND)
                 "docs"
     )
 
+    # Step 3: render the HTML site with mkdocs.
+    #
+    # Only the Windows installer ships it (the install() below, and the
+    # installer target which lists build_docs_html among its dependencies but
+    # is built with /p:BuildProjectReferences=false in CI - so on Windows this
+    # has to be part of `ALL`). Everywhere else the site was built on every
+    # single build and then thrown away, and because it sat in `ALL` a mkdocs
+    # hiccup failed the entire build rather than just the docs.
+    #
+    # The target itself still exists on every platform: run
+    # `cmake --build . --target build_docs_html` when you want the site.
+    if(WIN32)
+        set(NSCP_BUILD_DOCS_HTML_DEFAULT ON)
+    else()
+        set(NSCP_BUILD_DOCS_HTML_DEFAULT OFF)
+    endif()
+    option(
+        NSCP_BUILD_DOCS_HTML
+        "Build the mkdocs HTML site as part of the default build target"
+        ${NSCP_BUILD_DOCS_HTML_DEFAULT}
+    )
+    set(DOCS_HTML_ALL)
+    if(NSCP_BUILD_DOCS_HTML)
+        set(DOCS_HTML_ALL ALL)
+        message(STATUS "HTML documentation will be built as part of ALL")
+    else()
+        message(
+            STATUS
+            "HTML documentation is available via the build_docs_html target (not part of ALL)"
+        )
+    endif()
     add_custom_target(
         build_docs_html
-        ALL
+        ${DOCS_HTML_ALL}
         ${MKDOCS_EXECUTABLE} build --site-dir "${CMAKE_CURRENT_BINARY_DIR}/html"
         WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}"
         COMMENT "Building HTML documentation"
@@ -144,7 +175,10 @@ if(MKDOCS_FOUND)
             FOLDER
                 "docs"
     )
-    if(WIN32)
+    # Guarded by the option as well: with the site not built there is no
+    # directory to install, and install(DIRECTORY) on a missing source is a
+    # hard error at package time.
+    if(WIN32 AND NSCP_BUILD_DOCS_HTML)
         install(
             DIRECTORY
                 "${CMAKE_CURRENT_BINARY_DIR}/html/"