-
Notifications
You must be signed in to change notification settings - Fork 78
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
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.
- Loading branch information
1 parent
2a17601
commit 76e87f6
Showing
4 changed files
with
154 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,19 @@ | ||
# Contributing | ||
|
||
<!-- | ||
Short overview, rules, general guidelines, notes about pull requests and | ||
style should go here. | ||
--> | ||
|
||
## 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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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-<os>"], | ||
"cacheVariables": { | ||
"%(name)s_DEVELOPER_MODE": "ON" | ||
} | ||
} | ||
] | ||
} | ||
``` | ||
|
||
You should replace `<os>` 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/ |