Skip to content

Commit

Permalink
Add markdown docs to the project root
Browse files Browse the repository at this point in the history
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
friendlyanon committed May 2, 2021
1 parent 2a17601 commit 76e87f6
Show file tree
Hide file tree
Showing 4 changed files with 154 additions and 0 deletions.
47 changes: 47 additions & 0 deletions cmake-init/templates/common/BUILDING.md
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
5 changes: 5 additions & 0 deletions cmake-init/templates/common/CODE_OF_CONDUCT.md
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.
19 changes: 19 additions & 0 deletions cmake-init/templates/common/CONTRIBUTING.md
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.
83 changes: 83 additions & 0 deletions cmake-init/templates/common/HACKING.md
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/

0 comments on commit 76e87f6

Please sign in to comment.