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

Author: Cyan4973

.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