From c9d3af9ed0fa28b674270616c17e732e2ffcd8eb Mon Sep 17 00:00:00 2001 From: Yann Collet Date: Sat, 20 Sep 2025 22:49:20 -0700 Subject: [PATCH 1/2] [cmake] root wrapper allow the existence of a `CMakeLists.txt` file at root, for easier integration with other projects expecting this file at root. Existing integration point, within `build/cmake/`, still works as expected. --- .gitignore | 21 +++++++++++---------- CMakeLists.txt | 11 +++++++++++ README.md | 43 +++++++++++++++++++++++++------------------ build/cmake/README.md | 9 +++++++++ 4 files changed, 56 insertions(+), 28 deletions(-) create mode 100644 CMakeLists.txt diff --git a/.gitignore b/.gitignore index 4b50bb186..03ecbde6a 100644 --- a/.gitignore +++ b/.gitignore @@ -22,16 +22,6 @@ zstdmt *.out *.app -# Test artefacts -tmp* -*.zst -*.zstd -dictionary. -dictionary -NUL -cmakebuild/ -install/ - # Build artefacts contrib/linux-kernel/linux/ projects/ @@ -40,6 +30,17 @@ bin/ buck-out/ build-* *.gcda +cmakebuild/ +cmake-build/ + +# Test artefacts +tmp* +*.zst +*.zstd +dictionary. +dictionary +NUL +install/ # IDE .clang_complete diff --git a/CMakeLists.txt b/CMakeLists.txt new file mode 100644 index 000000000..10fef39b9 --- /dev/null +++ b/CMakeLists.txt @@ -0,0 +1,11 @@ +cmake_minimum_required(VERSION 3.10) + +# Thin wrapper so `cmake -S .` behaves like `cmake -S build/cmake`. +# Policy lives in build/cmake; keep parent project language-less. +project(zstd-superbuild LANGUAGES NONE) + +if(CMAKE_SOURCE_DIR STREQUAL CMAKE_BINARY_DIR) + message(FATAL_ERROR "In-source builds are not supported. Specify -B .") +endif() + +add_subdirectory(build/cmake) diff --git a/README.md b/README.md index 5af79386f..3aa01a0c1 100644 --- a/README.md +++ b/README.md @@ -120,20 +120,20 @@ Dictionary gains are mostly effective in the first few KB. Then, the compression ## Build instructions -`make` is the officially maintained build system of this project. -All other build systems are "compatible" and 3rd-party maintained, -they may feature small differences in advanced options. -When your system allows it, prefer using `make` to build `zstd` and `libzstd`. +`make` is the main build system of this project. +It is the reference, and other build systems are periodically updated to stay compatible. +However, small drifts and feature differences can be present, since perfect synchronization is difficult. +For this reason, when your build system allows it, prefer employing `make`. ### Makefile Assuming your system supports standard `make` (or `gmake`), -invoking `make` in root directory will generate `zstd` cli in root directory. -It will also create `libzstd` into `lib/`. +just invoking `make` in root directory generates `zstd` cli at root, +and also generates `libzstd` into `lib/`. Other standard targets include: -- `make install` : create and install zstd cli, library and man pages -- `make check` : create and run `zstd`, test its behavior on local platform +- `make install` : install zstd cli, library and man pages +- `make check` : run `zstd`, test its essential behavior on local platform The `Makefile` follows the [GNU Standard Makefile conventions](https://www.gnu.org/prep/standards/html_node/Makefile-Conventions.html), allowing staged install, standard compilation flags, directory variables and command variables. @@ -144,9 +144,16 @@ and in [`programs/README.md`](programs/README.md#compilation-variables) for the ### cmake -A `cmake` project generator is provided within `build/cmake`. -It can generate Makefiles or other build scripts -to create `zstd` binary, and `libzstd` dynamic and static libraries. +A `cmake` project generator is available for generating Makefiles or other build scripts +to create the `zstd` binary as well as `libzstd` dynamic and static libraries. +The repository root now contains a minimal `CMakeLists.txt` that forwards to `build/cmake`, +so you can configure the project with a standard `cmake -S .` invocation, +while the historical `cmake -S build/cmake` entry point remains fully supported. + +```bash +cmake -S . -B build-cmake +cmake --build build-cmake +``` By default, `CMAKE_BUILD_TYPE` is set to `Release`. @@ -156,7 +163,7 @@ By default, `CMAKE_BUILD_TYPE` is set to `Release`. To perform a Fat/Universal2 build and install use the following commands: ```bash -cmake -B build-cmake-debug -S build/cmake -G Ninja -DCMAKE_OSX_ARCHITECTURES="x86_64;x86_64h;arm64" +cmake -S . -B build-cmake-debug -G Ninja -DCMAKE_OSX_ARCHITECTURES="x86_64;x86_64h;arm64" cd build-cmake-debug ninja sudo ninja install @@ -198,10 +205,11 @@ If the version is out of date, please [create an issue or pull request](https:// ### Visual Studio (Windows) Going into `build` directory, you will find additional possibilities: -- Projects for Visual Studio 2005, 2008 and 2010. +- Projects for Visual Studio 2008 and 2010. + VS2010 project is compatible with VS2012, VS2013, VS2015 and VS2017. - Automated build scripts for Visual compiler by [@KrzysFR](https://github.com/KrzysFR), in `build/VS_scripts`, which will build `zstd` cli and `libzstd` library without any need to open Visual Studio solution. +- It is now recommended to generate Visual Studio solutions from `cmake` ### Buck @@ -210,7 +218,7 @@ The output binary will be in `buck-out/gen/programs/`. ### Bazel -You easily can integrate zstd into your Bazel project by using the module hosted on the [Bazel Central Repository](https://registry.bazel.build/modules/zstd). +You can integrate zstd into your Bazel project by using the module hosted on the [Bazel Central Repository](https://registry.bazel.build/modules/zstd). ## Testing @@ -221,9 +229,9 @@ For information on CI testing, please refer to `TESTING.md`. ## Status -Zstandard is currently deployed within Facebook and many other large cloud infrastructures. -It is run continuously to compress large amounts of data in multiple formats and use cases. -Zstandard is considered safe for production environments. +Zstandard is deployed within Meta and many other large cloud infrastructures, +to compress humongous amounts of data in various formats and use cases. +It is also continuously fuzzed for security issues by Google's [oss-fuzz](https://github.com/google/oss-fuzz/tree/master/projects/zstd) program. ## License @@ -232,6 +240,5 @@ Zstandard is dual-licensed under [BSD](LICENSE) OR [GPLv2](COPYING). ## Contributing The `dev` branch is the one where all contributions are merged before reaching `release`. -If you plan to propose a patch, please commit into the `dev` branch, or its own feature branch. Direct commit to `release` are not permitted. For more information, please read [CONTRIBUTING](CONTRIBUTING.md). diff --git a/build/cmake/README.md b/build/cmake/README.md index 6baa5974b..41c8bbb1a 100644 --- a/build/cmake/README.md +++ b/build/cmake/README.md @@ -7,6 +7,15 @@ variables. ## How to build +You can configure the project from the repository root thanks to the forwarding +`CMakeLists.txt`: +```sh +cmake -S . -B build-cmake +cmake --build build-cmake +``` +The historical workflow that starts configuration from `build/cmake` continues +to work as described below. + As cmake doesn't support command like `cmake clean`, it's recommended to perform an "out of source build". To do this, you can create a new directory and build in it: ```sh From 7758cc3e7a9821ab2a3870d47204246c90ac602f Mon Sep 17 00:00:00 2001 From: Yann Collet Date: Wed, 24 Sep 2025 21:55:31 -0700 Subject: [PATCH 2/2] [cmake] add minimal build test for CMakeLists.txt at root --- .github/workflows/cmake-tests.yml | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/.github/workflows/cmake-tests.yml b/.github/workflows/cmake-tests.yml index f1ed1f850..5534cdf89 100644 --- a/.github/workflows/cmake-tests.yml +++ b/.github/workflows/cmake-tests.yml @@ -21,11 +21,26 @@ env: COMMON_CMAKE_FLAGS: "-DCMAKE_COMPILE_WARNING_AS_ERROR=ON -DZSTD_BUILD_TESTS=ON" jobs: + # Basic cmake build using the root CMakeLists.txt + # Provides a lightweight sanity check that the top-level project config builds + # with the default Unix Makefiles generator driven purely through cmake commands + cmake-root-basic: + name: "CMake Root Build" + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # tag=v5.0.0 + - name: Configure (Root) + run: | + cmake -S . -B cmake-build -DCMAKE_BUILD_TYPE=Release ${{ env.COMMON_CMAKE_FLAGS }} + - name: Build (Root) + run: | + cmake --build cmake-build --config Release + # Ubuntu-based cmake build using make wrapper # This test uses the make-driven cmake build to ensure compatibility # with the existing build system integration cmake-ubuntu-basic: - name: "CMake Ubuntu Basic Build" + name: "CMake build using make wrapper" runs-on: ubuntu-latest steps: - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # tag=v5.0.0