Increase verbosity of buildsystem documentation
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 14.4k
- Forks
- 1.3k
- PR merge metrics
- No merged PRs in 30d
Description
As I'm finding my way around the buildsystem in the last weeks I feel that we could add some more information to the documentation. Some first thoughts (more added later):
I think we should create an own folder doc/buildsystem and explain the different parts in detail. For example, how the find_package-System works, where to find the modules. How to add a new one or how to refactor a module. Maybe even some basic call/caller-graphs[1] to find the way more easy or to see where optimisation could be needed. I think that could be a long-term profit for everyone. For new people coming in to understand it and for people using it every day to find their way around faster.
In addition to that, as we will probably need it more often, we should document processes like how to create a new Makefile-target and how to deal within CMake with these. What to do, if you want to add a new feature within openage and/or libopenage. How is the buildsystem involved with the c++/python interface etc.
Our documentation for the buildsystem is here right now:
https://github.com/SFTtech/openage/blob/master/doc/buildsystem.md
Here is explained how a make target for a dependency-graph could look like. While the repository here has the DependencyGraph.cmake (and some other cool tooling).
[1]: cmake <PATH_TO_SOURCES> --graphviz=graph/test.dot
https://cmake.org/cmake/help/latest/module/CMakeGraphVizOptions.html
Graphviz example:

Project to visualize cpp dependencies
https://github.com/tomtom-international/cpp-dependencies#using-cpp-dependencies-to-make-visualized-graphs
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with doc/buildsystem.md and inventory the proposed topics: find_package modules, Makefile targets, dependency graphs, and the C++/Python interface. Review the linked CMake and Graphviz references before defining a bounded documentation scope; completion is not specified because this issue proposes a long-term documentation effort.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- cmake, cpp, python
- Domain
- build-system, documentation
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100