Agnesoft central development repository.
Run (use Git Bash on Windows):
./adev.sh
This will show all available actions: building, running various checks, installation of prerequisites & tools etc. E.g.
To build simply run any of:
./adev.sh build
./adev.sh build <toolchain>
./adev.sh build <project> <toolchain>
Available toolchains are:
- clang
- gcc* (default, Linux only)
- msvc (default, Windows only)
*see Known Issues
The binaries will be output to build/<toolchain>.
| Name | Path | Description |
|---|---|---|
| acommandline | projects/acommandline/ | c++ command line parser |
| aprocess | projects/aprocess/ | c++ process management library |
| astl | projects/astl/ | c++ standard template library module wrapper |
| atest | projects/atest/ | c++ testing framework |
| athreadpool | projects/athreadpool/ | c++ thread pool |
| awinapi | projects/awinapi/ | c++ winapi module wrapper |
| yamlcpp | projects/yamlcpp/ | c++ yaml-cpp module wrapper, LICENSE |
| Windows | Installation | Note |
|---|---|---|
| (Git) Bash | - | |
| Visual Studio 2022 | manual | |
| clang 13 | ./adev.sh install llvm |
|
| gcc 11* | ./adev.sh install gcc |
See Known Issues |
| clang-tidy | ./adev.sh install llvm |
|
| llvm-cov | ./adev.sh install llvm |
|
| Doxygen | ./adev.sh install doxygen |
|
| clang-format | ./adev.sh install llvm |
|
| Docker Desktop | manual | Required only for Continuous Integration |
Please refer to contribution.md and style_guide.md for general information.
For development you can use the docker image (preferred) or setup your environment with ./adev.sh install <package> actions or install the tools manually.
Workflow summary:
- Open and issue
- Create a branch for that issue
- observe the naming rules in the style_guide.md, i.e. use
[project tag]and name the branch after your issue, including the issue #
- observe the naming rules in the style_guide.md, i.e. use
- Work on the branch
- build & run checks via
./adev.sh
- build & run checks via
- Push the branch to GitHub & open PR from your branch to
main - Merge to
main- requires 1 approval & all Continous Integration checks to pass
The adev is using GitHub Actions. The .adev.sh script actions are run as part of the continuous integration (CI) on every pull request and subsequent merge to main. Most actions are run on Ubuntu based custom docker image that comes with preinstalled prerequisites & tools listed above:
The docker image is rebuilt if it changes in a PR and the checks are run on such an image. If the PR with a changed dockerfile is merged to main the build will rebuild & push the latest tag of that image to the repository.
Every CI run uploads artifacts (binaries, documentation, coverage report) for usage or inspection even if it failed for easier debugging.
There are two workflows:
- runs on every pull request (pr)
- checks are run only on the diff to the latest
main - skips irrelevant checks.
- runs on every push (merge) to
main - all checks are run fully
| Platform | Action | Tool | Version | Description | Workaround | Date |
|---|---|---|---|---|---|---|
| any | coverage | llvm | 13 | LLVM instrumentation has difficulties with if constexpr and some other entities showing them "uncovered" even though they are executed. |
None. Increase coverage thresholds as needed. | 29/09/2021 |
| any | coverage | llvm | 13 | LLVM source code based coverage has difficulties with spawned processes. The resulting profraw file is reported as corrupted and cannot be used by llvm-profdata. |
None. Exclude affected projects from coverage. | 25/11/2021 |
| any | analysis | llvm | 13 | clang-tidy cannot use TemplateParameterCase style parameter along with other style checks citing "invalid style". |
None. Do not use for now. | 02/10/2021 |
| Linux | build | gcc | 11 | Unable to use its own STL (libstdc++) as header units. Build fails on internal compiler error. The libc++ does not work either. |
None. GCC is not usable with modules and STL. | 31/08/2021 |
| Linux | analysis | llvm | 13 | clang-tidy has difficulties using Unix headers such as wait.h as header units even with correct module.modulemap. The build si ok. |
Specify the headers in module.modulemap manually. |
25/11/2021 |
| Linux | address-sanitizer | llvm | 13.0.1 | Address sanitizer produces alloc-dealloc-mismatch false positives coming from libc++. |
Set export ASAN_OPTIONS=alloc_dealloc_mismatch=0 before running the tests built with asan. |
18/01/2022 |
| Linux | memory-sanitizer | llvm | 13.0.1 | Memory sanitizer detects uninitialized variables in libc++ in std::filesystem (/llvm/libcxx/src/filesystem/operations.cpp). |
Set fun:*create_file_status* in ignorelist.txt and use -fsanitize-ignorelist=ignorelist.txt during the memsan build of libc++. |
14/02/2022 |
| Windows | docker | Docker Desktop | 4.1 | It cannot be installed if there is an existing WSL 2 image. Docker Desktop must be installed when there are no other WSL 2 images. | Remove all WSL2 images before installing Docker Desktop. | 02/10/2021 |
| Windows | build | msvc | 16.11.5 | Using <Windows.h> as a header unit produces warnings 4005, 5105 and 5106 transitively (i.e. all uses even indirect ones). |
Suppress 4005, 5105 and 5106 for all direct and indirect usages of windows.h. |
03/11/2021 |
| Windows | analysis | llvm | 14 | clang-tidy with -bugprone-exception-escape mishandles std::string from MSVC STL and flags all usage of potentially throwing rendering this check useless. |
None. Do not use for now. | 02/10/2021 |