From 76e87f6f9bab4cef443f5ffd0e8c8fe4cbba7ce8 Mon Sep 17 00:00:00 2001 From: friendlyanon Date: Sun, 2 May 2021 04:19:15 +0200 Subject: [PATCH] Add markdown docs to the project root These documents explain how to build the code and how to contribute using the developer mode of the project. This is helpful even for the person who generated the project, in case the CMakeUserPresets.json file somehow gets lost. --- cmake-init/templates/common/BUILDING.md | 47 +++++++++++ .../templates/common/CODE_OF_CONDUCT.md | 5 ++ cmake-init/templates/common/CONTRIBUTING.md | 19 +++++ cmake-init/templates/common/HACKING.md | 83 +++++++++++++++++++ 4 files changed, 154 insertions(+) create mode 100644 cmake-init/templates/common/BUILDING.md create mode 100644 cmake-init/templates/common/CODE_OF_CONDUCT.md create mode 100644 cmake-init/templates/common/CONTRIBUTING.md create mode 100644 cmake-init/templates/common/HACKING.md diff --git a/cmake-init/templates/common/BUILDING.md b/cmake-init/templates/common/BUILDING.md new file mode 100644 index 0000000..088fb8c --- /dev/null +++ b/cmake-init/templates/common/BUILDING.md @@ -0,0 +1,47 @@ +# Building with CMake + +## Build + +This project doesn't require any special command-line flags to build to keep +things simple. + +Here are the steps for building in release mode with a single-configuration +generator, like the Unix Makefiles one: + +```sh +cmake -S . -B build -D CMAKE_BUILD_TYPE=Release +cmake --build build +``` + +Here are the steps for building in release mode with a multi-configuration +generator, like the Visual Studio ones: + +```sh +cmake -S . -B build +cmake --build build --config Release +``` + +## Install + +This project doesn't require any special command-line flags to install to keep +things simple. As a prerequisite, the project has to be built with the above +commands already. + +The below commands require at least CMake 3.15 to run, because that is the +version in which [Install a Project][1] was added. + +Here is the command for installing the release mode artifacts with a +single-configuration generator, like the Unix Makefiles one: + +```sh +cmake --install build +``` + +Here is the command for installing the release mode artifacts with a +multi-configuration generator, like the Visual Studio ones: + +```sh +cmake --install build --config Release +``` + +[1]: https://cmake.org/cmake/help/latest/manual/cmake.1.html#install-a-project diff --git a/cmake-init/templates/common/CODE_OF_CONDUCT.md b/cmake-init/templates/common/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..d120231 --- /dev/null +++ b/cmake-init/templates/common/CODE_OF_CONDUCT.md @@ -0,0 +1,5 @@ +# Code of Conduct + +* You will be judged by your contributions first, and your sense of humor + second. +* Nobody owes you anything. diff --git a/cmake-init/templates/common/CONTRIBUTING.md b/cmake-init/templates/common/CONTRIBUTING.md new file mode 100644 index 0000000..10cccf3 --- /dev/null +++ b/cmake-init/templates/common/CONTRIBUTING.md @@ -0,0 +1,19 @@ +# Contributing + + + +## Code of Conduct + +Please see the [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md) document. + +## Getting started + +Helpful notes for developers can be found in the [`HACKING.md`](HACKING.md) +document. + +In addition to he above, if you use the presets file as instructed, then you +should NOT check it into source control, just as the CMake documentation +suggests. diff --git a/cmake-init/templates/common/HACKING.md b/cmake-init/templates/common/HACKING.md new file mode 100644 index 0000000..2238d61 --- /dev/null +++ b/cmake-init/templates/common/HACKING.md @@ -0,0 +1,83 @@ +# Hacking + +Here is some wisdom to help you build and test this project as a developer and +potential contributor. + +If you plan to contribute, please read the [CONTRIBUTING](CONTRIBUTING.md) +guide. + +## Developer mode + +Build system targets that are only useful for developers of this project are +hidden if the `%(name)s_DEVELOPER_MODE` option is disabled. Enabling this +option makes tests and other developer targets and options available. Not +enabling this option means that you are a consumer of this project and thus you +have no need for these targets and options. + +Developer mode is forced to be on when the `CI` environment variable is set to +a value that CMake recognizes as "on", which is set to `true` in all of the CI +workflows. + +### Presets + +This project makes use of [presets][1] to simplify the process of configuring +the project. As a developer, you are recommended to always have the [latest +CMake version][2] installed to make use of the latest Quality-of-Life +additions. + +You have a few options to pass `%(name)s_DEVELOPER_MODE` to the configure +command, but this project prefers to use presets. + +As a developer, you should create a `CMakeUserPresets.json` file at the root of +the project: + +```json +{ + "version": 1, + "cmakeMinimumRequired": { + "major": 3, + "minor": 14, + "patch": 0 + }, + "configurePresets": [ + { + "name": "dev", + "inherits": ["ci-"], + "cacheVariables": { + "%(name)s_DEVELOPER_MODE": "ON" + } + } + ] +} +``` + +You should replace `` in your newly created presets file with the name of +the operating system you have, which may be `win64` or `unix`. You can see what +these correspond to in the [`CMakePresets.json`](CMakePresets.json) file. + +`CMakeUserPresets.json` is also the perfect place in which you can put all +sorts of things that you would otherwise want to pass to the configure command +in the terminal. + +### Configure, build and test + +If you followed the above instructions, then you can configure, build and test +the project respectively with the following commands from the project root on +Windows: + +```sh +cmake --preset=dev +cmake --build build --config Release +cd build && ctest -C Release +``` + +And here is the same on a Unix based system (Linux, macOS): + +```sh +cmake --preset=dev +cmake --build build +cd build && ctest +``` + +[1]: https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html +[2]: https://cmake.org/download/