diff options
Diffstat (limited to 'readme.md')
| -rw-r--r-- | readme.md | 87 |
1 files changed, 53 insertions, 34 deletions
@@ -10,14 +10,58 @@ microcontrollers, and a recommendation is made in the [design document](docs/design.adoc). Please see the [handover document](docs/handover.adoc) first for more details. +## Libraries + +Libraries are stored in the [lib](lib/) folder, and this folder is symlinked to +from each subfolder in the project for convenience (allows CMake to include +out-of-tree modules). The lib folder contains a mix of direct Git submodules +and custom libraries specific to this project. (Most) external dependencies are +tracked as git submodules, exceptions are in the [puzzle](puzzle/) folder. + +> [!NOTE] +> Please note that symbolic links may not work correctly if you clone the +> repository under a filesystem or operating system that does not support +> these. MinGW/Windows are known to have issues with symlinks, so please verify +> symlinks are recognised as such before attempting to build or initialize the +> submodules. + +TL;DR: If something is complaining about missing files + +``` +git submodule update --init --recursive --depth 1 +``` + +until your problems go away. + +## Building + +All subfolders/modules/libraries use CMake, and build in roughly the same way. +All documentation assumes CMake is used in combination with Ninja, though other +generators may also work. The following commands can be used inside each +subfolder to compile (make sure you have initialized the submodules before +compiling): + +``` +$ cmake -B build -G Ninja +$ ninja -C build +``` + +Target-specific flashing/uploading commands are detailed in the respective +folder's README. + > [!NOTE] -> This project was mostly developed on Linux. All subfolders/modules/libraries -> use CMake, and *should* build cross-platform when using CMake+Ninja. This has -> not yet been verified. -> -> Please note that most subfolders use symbolic links to the [lib](lib/) -> folder, which may not work correctly if you clone the repository under a -> filesystem or operating system that does not support these. +> Cross-platform compilation should be supported, though this has not been +> verified. Most of this project was developed on Linux, and Windows +> compatibility has not been verified. + +### lazy\.mk + +[`lazy.mk`](./lazy.mk) is a file made by Loek, and includes some rules for +forwarding `make` calls to `cmake` and `ninja`. **This is purely for +convenience, and should not become an essential part of the build system**. +This file should be included at the end of a regular makefile. Any targets +defined in a makefile can be used as-is, while targets that would otherwise be +unknown will be forwarded to Ninja. ## Documentation @@ -43,35 +87,10 @@ Please keep this repository tidy by being aware of the following conventions: - An `.editorconfig` file is provided in this repository. Please install the [EditorConfig](https://editorconfig.org/) plugin for your text editor of choice to automatically use these. -- There are also `.clang-tidy` and `.clang-format` files, which can be enforced - by running +- There are also `.clang-tidy` and `.clang-format` files which define specific + code style attributes. These can be enforced by running ``` $ make format ``` -## Libraries - -Libraries are stored in the [lib](lib/) folder, and this folder is symlinked to -from each subfolder in the project for convenience (allows CMake to include -out-of-tree modules). The lib folder contains a mix of direct Git submodules -and custom libraries specific to this project. (Most) external dependencies are -tracked as git submodules, exceptions are in the [puzzle](puzzle/) folder. - -TL;DR: If something is complaining about missing files - -``` -git submodule update --init --recursive --depth 1 -``` - -until your problems go away. - -## lazy\.mk - -[`lazy.mk`](./lazy.mk) is a file made by Loek, and includes some rules for -forwarding `make` calls to `cmake` and `ninja`. **This is purely for -convenience, and should not become an essential part of the build system**. -This file should be included at the end of a regular makefile. Any targets -defined in a makefile can be used as-is, while targets that would otherwise be -unknown will be forwarded to Ninja. - |