Skip to content

Commit 0bd06fb

Browse files
KonradBreitsprecherBkdKonradBreitsprecherBkd
committed
Add dev wiki
1 parent 545d1bd commit 0bd06fb

8 files changed

Lines changed: 2077 additions & 0 deletions

‎docs/dev-wiki/README.md‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
# SIL Kit Developer Wiki
2+
3+
This wiki is the internal developer-oriented knowledge base for working on the SIL Kit repository.
4+
It focuses on repository structure, engineering workflows, implementation details, and the practical
5+
knowledge needed to make changes safely.
6+
7+
## What This Wiki Is For
8+
9+
- helping developers get productive in the repository quickly
10+
- documenting architecture and subsystem boundaries
11+
- capturing build, test, debugging, and release workflows
12+
- recording project-specific conventions that are easy to miss when reading code alone
13+
14+
## Suggested Reading Path
15+
16+
1. Read [Repository Layout](./repository-layout.md) to understand the tree and major modules.
17+
2. Read [Build and Test](./build-and-test.md) to get a local development workflow.
18+
3. Read [Core Architecture](./core-architecture.md) and [Networking and Transport](./networking-and-transport.md).
19+
4. Use [Utilities and Processes](./utilities-and-processes.md), [Release and Versioning](./release-and-versioning.md), and [Debugging and Common Failures](./debugging-and-common-failures.md) as needed.
20+
21+
## Current Pages
22+
23+
- [Repository Layout](./repository-layout.md)
24+
- [Build and Test](./build-and-test.md)
25+
- [Core Architecture](./core-architecture.md)
26+
- [Networking and Transport](./networking-and-transport.md)
27+
- [Utilities and Processes](./utilities-and-processes.md)
28+
- [Release and Versioning](./release-and-versioning.md)
29+
- [Debugging and Common Failures](./debugging-and-common-failures.md)
30+
31+
## Proposed Wiki Topics
32+
33+
The following pages are intended to be added over time as repository knowledge evolves.
34+
35+
## Scope
36+
37+
This wiki should prefer practical repository knowledge over end-user documentation.
38+
It should stand on its own as a developer and AI-facing knowledge base rather than acting as a navigation
39+
layer into the separate docs set.
40+
41+
## Status
42+
43+
This is the initial front page. Additional pages can be added incrementally as repository knowledge
44+
is collected and validated.

‎docs/dev-wiki/build-and-test.md‎

Lines changed: 237 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,237 @@
1+
# Build and Test
2+
3+
This page summarizes the practical build and test workflows for local development in this repository.
4+
5+
## Prerequisites
6+
7+
At minimum, local development requires:
8+
9+
- Git
10+
- CMake
11+
- a supported C++ toolchain such as Visual Studio, GCC, or Clang
12+
- initialized submodules
13+
14+
Initialize submodules after cloning:
15+
16+
```powershell
17+
git submodule update --init --recursive
18+
```
19+
20+
Documentation builds additionally require:
21+
22+
- Python 3
23+
- dependencies from `SilKit/ci/docker/docs_requirements.txt`
24+
- `pipenv`
25+
- Doxygen
26+
27+
## Preferred Local Flow: CMake Presets
28+
29+
The repository already defines presets in `CMakePresets.json`.
30+
For day-to-day development, presets are the easiest way to stay aligned with the intended build layout.
31+
32+
Useful configure presets include:
33+
34+
- `debug`
35+
- `release`
36+
- `relwithdebinfo`
37+
- `distrib`
38+
- `x86-debug`
39+
- `vs141-x64-debug`
40+
41+
The presets use these default directory conventions:
42+
43+
- build tree: `_build/<preset>`
44+
- install tree: `_install/<preset>`
45+
46+
Typical local debug build:
47+
48+
```powershell
49+
cmake --preset debug
50+
cmake --build --preset debug
51+
```
52+
53+
Typical release build:
54+
55+
```powershell
56+
cmake --preset release
57+
cmake --build --preset release
58+
```
59+
60+
## Important CMake Options
61+
62+
The root `CMakeLists.txt` defines the main switches developers usually care about:
63+
64+
- `SILKIT_BUILD_TESTS`: build unit, integration, and functional tests
65+
- `SILKIT_BUILD_UTILITIES`: build utilities such as registry, monitor, and system controller
66+
- `SILKIT_BUILD_DEMOS`: build demo applications
67+
- `SILKIT_BUILD_DOCS`: build Sphinx and Doxygen documentation
68+
- `SILKIT_INSTALL_SOURCE`: install and package the source tree
69+
- `SILKIT_WARNINGS_AS_ERRORS`: treat compiler warnings as errors
70+
- `SILKIT_BUILD_DASHBOARD`: build the dashboard client code
71+
- `SILKIT_BUILD_STATIC`: build SIL Kit as a static library instead of shared
72+
73+
Most local development can start from the `debug` preset and only override options when needed.
74+
75+
## Manual Configure Flow
76+
77+
If you do not want to use presets, a manual configure still works.
78+
79+
Example:
80+
81+
```powershell
82+
cmake -S . -B _build/manual-debug -G Ninja -DCMAKE_BUILD_TYPE=Debug
83+
cmake --build _build/manual-debug
84+
```
85+
86+
To enable docs explicitly:
87+
88+
```powershell
89+
cmake -S . -B _build/docs -G Ninja -DCMAKE_BUILD_TYPE=Debug -DSILKIT_BUILD_DOCS=ON
90+
cmake --build _build/docs --target Doxygen
91+
```
92+
93+
## Build Outputs
94+
95+
A few output conventions are helpful to know:
96+
97+
- build trees usually live under `_build/`
98+
- presets install into `_install/`
99+
- test executables are configured to run from the build output directory
100+
- demo binaries are emitted into the common build output directory when built in-tree
101+
102+
The library project sets a debug postfix of `d`, so debug binaries can sit alongside release binaries.
103+
104+
## Running Tests
105+
106+
Testing is enabled globally in the root build with `enable_testing()`.
107+
The library creates several aggregate GoogleTest executables, and CTest registers suites through helper macros in `SilKit/cmake/SilKitTest.cmake`.
108+
109+
If you configured with a preset that enables tests, run all tests with:
110+
111+
```powershell
112+
ctest --preset debug --output-on-failure
113+
```
114+
115+
Or from a specific build directory:
116+
117+
```powershell
118+
ctest --test-dir _build/debug --output-on-failure
119+
```
120+
121+
Useful variants:
122+
123+
```powershell
124+
ctest --test-dir _build/debug -R Lin --output-on-failure
125+
ctest --test-dir _build/debug -R PubSub --output-on-failure
126+
ctest --test-dir _build/debug -N
127+
```
128+
129+
What these do:
130+
131+
- `-R <regex>` filters tests by CTest test name
132+
- `-N` lists tests without running them
133+
- `--output-on-failure` prints failing test output immediately
134+
135+
## How Tests Are Structured
136+
137+
The main test executables are:
138+
139+
- `SilKitUnitTests`
140+
- `SilKitIntegrationTests`
141+
- `SilKitInternalIntegrationTests`
142+
- `SilKitFunctionalTests`
143+
- `SilKitInternalFunctionalTests`
144+
145+
Tests are added through `add_silkit_test_to_executable(...)`.
146+
That helper usually creates one CTest entry per test suite, using a GoogleTest filter.
147+
148+
Practical implications:
149+
150+
- CTest test names usually map to suites rather than binary names
151+
- adding a new integration or functional test often means adding a source file in `SilKit/IntegrationTests/` and registering it in the corresponding `CMakeLists.txt`
152+
- if a test seems missing from CTest, check whether it was wired through the helper macro
153+
154+
## Running A Narrow Slice During Development
155+
156+
For fast iteration, prefer a narrow configure and a filtered test run.
157+
158+
Examples:
159+
160+
- build one preset once, then rebuild incrementally with `cmake --build --preset debug`
161+
- run only matching suites with `ctest --test-dir _build/debug -R <name> --output-on-failure`
162+
- list available tests first with `ctest --test-dir _build/debug -N`
163+
164+
This is usually faster and more predictable than repeatedly creating fresh build directories.
165+
166+
## Building Utilities and Demos
167+
168+
Utilities are included when `SILKIT_BUILD_UTILITIES=ON`.
169+
That includes:
170+
171+
- `SilKitRegistry`
172+
- `SilKitSystemController`
173+
- `SilKitMonitor`
174+
175+
Demos are included when `SILKIT_BUILD_DEMOS=ON`.
176+
The `Demos` project contains communication demos, API demos, and benchmark tooling.
177+
178+
For many feature changes, building both tests and utilities is more useful than building demos.
179+
For changes affecting example flows or protocol behavior, demos may also be worth rebuilding.
180+
181+
## Building Documentation
182+
183+
The docs build is optional and uses both Doxygen and Sphinx.
184+
185+
Install dependencies:
186+
187+
```powershell
188+
pip3 install -r SilKit/ci/docker/docs_requirements.txt
189+
pip3 install pipenv
190+
```
191+
192+
Configure and build docs:
193+
194+
```powershell
195+
cmake -S . -B _build/docs -G Ninja -DSILKIT_BUILD_DOCS=ON
196+
cmake --build _build/docs --target Doxygen
197+
```
198+
199+
The docs target named `Doxygen` actually drives both Doxygen extraction and the Sphinx HTML build.
200+
201+
## Packaging
202+
203+
Packaging is handled through CPack.
204+
205+
Typical packaging command after configuration:
206+
207+
```powershell
208+
cmake --build _build/distrib --target package
209+
```
210+
211+
The `distrib` preset is the closest existing preset to a packaging-oriented build.
212+
213+
## Practical Recommendations
214+
215+
For everyday code changes:
216+
217+
1. Use `cmake --preset debug` once.
218+
2. Rebuild incrementally with `cmake --build --preset debug`.
219+
3. Run only the relevant CTest slice while iterating.
220+
4. Run a broader `ctest --preset debug --output-on-failure` before finishing.
221+
222+
For documentation changes:
223+
224+
1. Enable `SILKIT_BUILD_DOCS`.
225+
2. Build the `Doxygen` target.
226+
3. Check the generated Sphinx output and warnings.
227+
228+
For release-like validation:
229+
230+
1. Use the `distrib` preset.
231+
2. Build and test from that preset.
232+
3. Run the `package` target if needed.
233+
234+
## Related Pages
235+
236+
- [Repository Layout](./repository-layout.md)
237+
- [Developer Wiki Front Page](./README.md)

0 commit comments

Comments
 (0)