SFTtech / SFTtech/openage

Increase verbosity of buildsystem documentation

Open
#1,244 2 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

area: buildsystem documentation just do it
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

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.