diff options
Diffstat (limited to 'readme.md')
| -rw-r--r-- | readme.md | 69 |
1 files changed, 42 insertions, 27 deletions
@@ -5,45 +5,60 @@ implemented during the 2023-2024 run of the Puzzlebox project. This year's run of the project consists of only software students, and was developed using the hardware from the 21-22 run of the project. -Improved hardware was designed but not realised during the 22-23 run of the -project. This hardware is recommended for future groups participating in the -project. The software in this repository should be easily portable to various -other microcontrollers, and a recommendation is made in the [design -document](docs/design.adoc). +The software in this repository should be easily portable to various other +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. -## Tidyness +> [!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. + +## Documentation -Please keep this repository tidy by being aware of the following conventions! +If you are viewing this page from Doxygen, please take a look at the +[components](topics.html) tab for a comprehensive list of components within +this project. -### Folder structure +Project documentation is available in the [docs](docs/) folder, and all code is +documented using Doxygen. To generate HTML docs, run ``` -/client desktop PC application for controlling the puzzle box -/docs project documentation in AsciiDoc(tor) format -/lib custom libraries and submodules -├───/i2ctcp I2C over TCP protocol functions (used by main and client) -├───/mpack MsgPack CMake configuration and extension -└───/pbdrv puzzle bus driver (module driver + (de)serializing functions) -/main main controller (RPi pico) software -/puzzle/<name> puzzle sources, each puzzle has its own subdirectory -/shared (unused) shared code -/test unit tests +$ make doxygen ``` -### Code style +and open [the generated HTML files](doxygen/html/index.html) in a browser. A +rendered copy of this documentation is also hosted unofficially at +[pipeframe](https://media.pipeframe.xyz/puzzlebox/23-24/doxygen). + +## Tidyness + +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. +- 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 -Currently, no linter/formatter is configured for maintaining consistent code -style. + ``` + $ make format + ``` -## Submodules +## Libraries -This repository tracks (most) dependencies via git submodules. +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. -If something is complaining about missing files +TL;DR: If something is complaining about missing files ``` git submodule update --init --recursive --depth 1 |