Skip to content

Commit 59141d3

Browse files
author
alexeev-dev
committed
docs: improve docs
1 parent 50cd028 commit 59141d3

File tree

3 files changed

+581
-63
lines changed

3 files changed

+581
-63
lines changed

‎BUILDING.md‎

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
# Building with CMake
2+
3+
## Dependencies
4+
5+
For a list of dependencies, please refer to [conanfile.py](conanfile.py).
6+
7+
## Build
8+
9+
This project doesn't require any special command-line flags to build to keep
10+
things simple.
11+
12+
Here are the steps for building in release mode with a single-configuration
13+
generator, like the Unix Makefiles one:
14+
15+
```sh
16+
cmake -S . -B build -D CMAKE_BUILD_TYPE=Release
17+
cmake --build build
18+
```
19+
20+
Here are the steps for building in release mode with a multi-configuration
21+
generator, like the Visual Studio ones:
22+
23+
```sh
24+
cmake -S . -B build
25+
cmake --build build --config Release
26+
```
27+
28+
### Building with MSVC
29+
30+
Note that MSVC by default is not standards compliant and you need to pass some
31+
flags to make it behave properly. See the `flags-msvc` preset in the
32+
[CMakePresets.json](CMakePresets.json) file for the flags and with what
33+
variable to provide them to CMake during configuration.
34+
35+
### Building on Apple Silicon
36+
37+
CMake supports building on Apple Silicon properly since 3.20.1. Make sure you
38+
have the [latest version][1] installed.
39+
40+
## Install
41+
42+
This project doesn't require any special command-line flags to install to keep
43+
things simple. As a prerequisite, the project has to be built with the above
44+
commands already.
45+
46+
The below commands require at least CMake 3.15 to run, because that is the
47+
version in which [Install a Project][2] was added.
48+
49+
Here is the command for installing the release mode artifacts with a
50+
single-configuration generator, like the Unix Makefiles one:
51+
52+
```sh
53+
cmake --install build
54+
```
55+
56+
Here is the command for installing the release mode artifacts with a
57+
multi-configuration generator, like the Visual Studio ones:
58+
59+
```sh
60+
cmake --install build --config Release
61+
```
62+
63+
### CMake package
64+
65+
This project exports a CMake package to be used with the [`find_package`][3]
66+
command of CMake:
67+
68+
* Package name: `libnumerixpp`
69+
* Target name: `libnumerixpp::libnumerixpp`
70+
71+
Example usage:
72+
73+
```cmake
74+
find_package(libnumerixpp REQUIRED)
75+
# Declare the imported target as a build requirement using PRIVATE, where
76+
# project_target is a target created in the consuming project
77+
target_link_libraries(
78+
project_target PRIVATE
79+
libnumerixpp::libnumerixpp
80+
)
81+
```
82+
83+
### Note to packagers
84+
85+
The `CMAKE_INSTALL_INCLUDEDIR` is set to a path other than just `include` if
86+
the project is configured as a top level project to avoid indirectly including
87+
other libraries when installed to a common prefix. Please review the
88+
[install-rules.cmake](cmake/install-rules.cmake) file for the full set of
89+
install rules.
90+
91+
[1]: https://cmake.org/download/
92+
[2]: https://cmake.org/cmake/help/latest/manual/cmake.1.html#install-a-project
93+
[3]: https://cmake.org/cmake/help/latest/command/find_package.html

‎HACKING.md‎

Lines changed: 163 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,163 @@
1+
# Hacking
2+
3+
Here is some wisdom to help you build and test this project as a developer and
4+
potential contributor.
5+
6+
If you plan to contribute, please read the [CONTRIBUTING](CONTRIBUTING.md)
7+
guide.
8+
9+
## Developer mode
10+
11+
Build system targets that are only useful for developers of this project are
12+
hidden if the `libnumerixpp_DEVELOPER_MODE` option is disabled. Enabling this
13+
option makes tests and other developer targets and options available. Not
14+
enabling this option means that you are a consumer of this project and thus you
15+
have no need for these targets and options.
16+
17+
Developer mode is always set to on in CI workflows.
18+
19+
### Presets
20+
21+
This project makes use of [presets][1] to simplify the process of configuring
22+
the project. As a developer, you are recommended to always have the [latest
23+
CMake version][2] installed to make use of the latest Quality-of-Life
24+
additions.
25+
26+
You have a few options to pass `libnumerixpp_DEVELOPER_MODE` to the configure
27+
command, but this project prefers to use presets.
28+
29+
As a developer, you should create a `CMakeUserPresets.json` file at the root of
30+
the project:
31+
32+
```json
33+
{
34+
"version": 2,
35+
"cmakeMinimumRequired": {
36+
"major": 3,
37+
"minor": 14,
38+
"patch": 0
39+
},
40+
"configurePresets": [
41+
{
42+
"name": "dev",
43+
"binaryDir": "${sourceDir}/build/dev",
44+
"inherits": ["dev-mode", "conan", "ci-<os>"],
45+
"cacheVariables": {
46+
"CMAKE_BUILD_TYPE": "Debug"
47+
}
48+
}
49+
],
50+
"buildPresets": [
51+
{
52+
"name": "dev",
53+
"configurePreset": "dev",
54+
"configuration": "Debug"
55+
}
56+
],
57+
"testPresets": [
58+
{
59+
"name": "dev",
60+
"configurePreset": "dev",
61+
"configuration": "Debug",
62+
"output": {
63+
"outputOnFailure": true
64+
}
65+
}
66+
]
67+
}
68+
```
69+
70+
You should replace `<os>` in your newly created presets file with the name of
71+
the operating system you have, which may be `win64`, `linux` or `darwin`. You
72+
can see what these correspond to in the
73+
[`CMakePresets.json`](CMakePresets.json) file.
74+
75+
`CMakeUserPresets.json` is also the perfect place in which you can put all
76+
sorts of things that you would otherwise want to pass to the configure command
77+
in the terminal.
78+
79+
> **Note**
80+
> Some editors are pretty greedy with how they open projects with presets.
81+
> Some just randomly pick a preset and start configuring without your consent,
82+
> which can be confusing. Make sure that your editor configures when you
83+
> actually want it to, for example in CLion you have to make sure only the
84+
> `dev-dev preset` has `Enable profile` ticked in
85+
> `File > Settings... > Build, Execution, Deployment > CMake` and in Visual
86+
> Studio you have to set the option `Never run configure step automatically`
87+
> in `Tools > Options > CMake` **prior to opening the project**, after which
88+
> you can manually configure using `Project > Configure Cache`.
89+
90+
### Dependency manager
91+
92+
The above preset will make use of the [conan][conan] dependency manager. After
93+
installing it, make sure you have a [Conan profile][profile] setup, then
94+
download the dependencies and generate the necessary CMake files by running
95+
this command in the project root:
96+
97+
```sh
98+
conan install . -s build_type=Debug -b missing
99+
```
100+
101+
Note that if your conan profile does not specify the same compiler, standard
102+
level, build type and runtime library as CMake, then that could potentially
103+
cause issues. See the link above for profiles documentation.
104+
105+
[conan]: https://conan.io/
106+
[profile]: https://docs.conan.io/2/reference/config_files/profiles.html
107+
108+
### Configure, build and test
109+
110+
If you followed the above instructions, then you can configure, build and test
111+
the project respectively with the following commands from the project root on
112+
any operating system with any build system:
113+
114+
```sh
115+
cmake --preset=dev
116+
cmake --build --preset=dev
117+
ctest --preset=dev
118+
```
119+
120+
If you are using a compatible editor (e.g. VSCode) or IDE (e.g. CLion, VS), you
121+
will also be able to select the above created user presets for automatic
122+
integration.
123+
124+
Please note that both the build and test commands accept a `-j` flag to specify
125+
the number of jobs to use, which should ideally be specified to the number of
126+
threads your CPU has. You may also want to add that to your preset using the
127+
`jobs` property, see the [presets documentation][1] for more details.
128+
129+
### Developer mode targets
130+
131+
These are targets you may invoke using the build command from above, with an
132+
additional `-t <target>` flag:
133+
134+
#### `coverage`
135+
136+
Available if `ENABLE_COVERAGE` is enabled. This target processes the output of
137+
the previously run tests when built with coverage configuration. The commands
138+
this target runs can be found in the `COVERAGE_TRACE_COMMAND` and
139+
`COVERAGE_HTML_COMMAND` cache variables. The trace command produces an info
140+
file by default, which can be submitted to services with CI integration. The
141+
HTML command uses the trace command's output to generate an HTML document to
142+
`<binary-dir>/coverage_html` by default.
143+
144+
#### `docs`
145+
146+
Available if `BUILD_MCSS_DOCS` is enabled. Builds to documentation using
147+
Doxygen and m.css. The output will go to `<binary-dir>/docs` by default
148+
(customizable using `DOXYGEN_OUTPUT_DIRECTORY`).
149+
150+
#### `format-check` and `format-fix`
151+
152+
These targets run the clang-format tool on the codebase to check errors and to
153+
fix them respectively. Customization available using the `FORMAT_PATTERNS` and
154+
`FORMAT_COMMAND` cache variables.
155+
156+
#### `spell-check` and `spell-fix`
157+
158+
These targets run the codespell tool on the codebase to check errors and to fix
159+
them respectively. Customization available using the `SPELL_COMMAND` cache
160+
variable.
161+
162+
[1]: https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html
163+
[2]: https://cmake.org/download/

0 commit comments

Comments
 (0)