Merge pull request #4491 from facebook/cmake_root

[cmake] propose a root wrapper

.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

.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

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 <build-dir>.")
+endif()
+
+add_subdirectory(build/cmake)

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).

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