Add CMake build workflow and documentation

[FranzBusch]

Motivation

Swift projects that support CMake as a build system need automated validation to ensure their CMakeLists files stay in sync with the source tree. Without this, CMakeLists files can become stale as source files are added or removed, leading to build failures for users relying on the CMake build path. A reusable workflow helps enforce this validation consistently across Swiftlang projects.

Modifications

This change introduces a new reusable CMake build workflow that validates and builds Swift projects using CMake. The workflow includes two shell scripts: cmake-build.sh which builds projects using CMake and Ninja, and cmake-update-cmake-lists.sh which verifies that CMakeLists files accurately reflect the source tree based on a JSON configuration. The workflow runs in a Docker container and accepts inputs for the CMakeLists update configuration, the target directory to build, and the container image to use.

Result

Projects can now use the cmake_build workflow to automatically verify their CMake build system on every pull request. The workflow ensures CMakeLists files stay up-to-date and that the project builds successfully with CMake, preventing CMake build regressions from being merged.

[etcwilde]

I'm pretty strongly against using a script to automatically updating the source lists. It's ok for repos that are just mirroring SwiftPM builds, but will break things like the compiler and runtimes pretty horribly (not to mention that it's not pleasant figuring out what is going wrong when it gets it wrong).

[FranzBusch]

I'm pretty strongly against using a script to automatically updating the source lists. It's ok for repos that are just mirroring SwiftPM builds, but will break things like the compiler and runtimes pretty horribly (not to mention that it's not pleasant figuring out what is going wrong when it gets it wrong).

I understand your concerns for the compiler or the runtime. The intended audience are packages that are also offering a cmake build for the toolchain. We have this exact check running in many of our repos already and this PR is just brining it to a central place. Would you be happy if we call this package-cmake-check or something similar and position it like that in the README?

[etcwilde]

When CMake builds break, it's usually gets assigned either to me or @compnerd. I can't speak for him, but having had to help folks debug builds where this script is running, I am not willing to take on that responsibility going forward. If you're going to maintain the CMake configuration for any project using this script, maybe. I'm not comfortable accepting it as an official swiftlang workflow due to the difficulty of fixing things when it breaks them.

This conversation has been brought up before: #115

[compnerd]

Similar to @etcwilde's position, I don't think that I am comfortable with supporting users of this workflow who might rely on this for updating their CMakeLists.txt. I think that we should adhere to CMake's recommendation that this be the developer's responsibility. There are often small details that require explicit modelling.

[FranzBusch]

When CMake builds break, it's usually gets assigned either to me or @compnerd. I can't speak for him, but having had to help folks debug builds where this script is running, I am not willing to take on that responsibility going forward. If you're going to maintain the CMake configuration for any project using this script, maybe. I'm not comfortable accepting it as an official swiftlang workflow due to the difficulty of fixing things when it breaks them.

Interesting. I don't think any maintainer of the projects where this currently runs sees this as your or @compnerd responsibility. Rather, we started to add these workflows to our projects because we saw it as our responsibility to maintain the correct set of source files in these CMakeLists.txt. Honestly, the goal here is to reduce the burden on you and give the repo maintainers the right CI checks.

Would you be more open if this just ran a cmake based build instead and we remove the cmake list update part?

[compnerd]

Would you be more open if this just ran a cmake based build instead and we remove the cmake list update part?

Absolutely! I would love to see more of the projects routinely test the CMake based build. The fact that it would be through the workflows means that it is also likely going to go through that part as a standalone build rather than through the toolchain build, which makes this even more helpful because it will force more rigorous evaluation of any added dependency.

It is specifically the automated updating of the CMake rules that concerns me, not the testing of the CMake based build.

[etcwilde]

Would you be more open if this just ran a cmake based build instead and we remove the cmake list update part?

Yeah, I think that would be better. There's a CMake action on the github marketplace that at face value seems to do pretty much everything we would want, but I don't know the policies around it. Though at the same time, the PR testing on swift-cmake-examples is running:

          "${{ steps.install-cmake.outputs.cmake }}" -G Ninja -B test -S swift-cmake-examples -DCMAKE_BUILD_TYPE=Release
          "${{ steps.install-cmake.outputs.ctest }}" --output-on-failure --test-timeout 150 --test-dir test -j

And the workflow on swift-subprocess is invoking it directly:

  cmake_build:
    name: CMake Build
    runs-on: ubuntu-latest
    container: swiftlang/swift:nightly-noble
    steps:
      - name: checkout sources
        uses: actions/checkout@v1
      - name: Install dependencies
        shell: bash
        run: apt update && apt install -y cmake ninja-build
      - name: Configure Project
        shell: bash
        run: cmake -G 'Ninja' -B build -S . -DCMAKE_C_COMPILER=clang -DCMAKE_Swift_COMPILER=swiftc -DCMAKE_BUILD_TYPE=Release -DBUILD_SHARED_LIBS=YES
      - name: Build Project
        shell: bash
        run: cmake --build build

I wasn't sure how much abstracting that would actually help improve things.

Edit: I do think the abstraction becomes more valuable when it works across macOS, Linux, and Windows. If it's just one, calling CMake directly isn't really the hard part.