GRASS 8 new source layout
Rationale: At the moment source directory top level is a mess — distribution / OS specific folders are mixed with source code folders. Moving all source to src would make directory layout cleaner. G8 release is a great opportunity to break everything to make life better. Keep in mind — this is just a proposal to start discussion! Add your input to make it happen.
How to read: new folder name at the top level, current folders listed below. How to write: add your comments to any item you think should be moved somewhere else etc.
Continuous Integration: scripts, lists of dependencies, configurations which are not part of the specific CI configuration files.
Not all files will be here. For example workflows of GitHub Actions will be in their dedicated directory.
- Do we need this as a separate entry or it should go into packaging?
- It is not clear which dependencies go.
- CI is also running tests which is not necessarily (main focus of) packaging.
Documentation, that is not individual module help files.
All source of GRASS. Should contain everything worth compiling.
- What would qualify as compiling or source code?
- Is it "everything worth compiling" or perhaps just C, C++ and Python code or even just C and C++ code?
- Example is locale. But also docs is compiled.
includebe part of this?
- Some projects have it at the top level.
- Some projects divide code into src, include and apps. Should we use that too?
- This may help separating dirs for module families (raster, vector, ...) from the rest of the source code.
Current challenges (strangenesses):
includecontains things for make, so any includes would go here? E.g., Jinja templates if we would have some or more realistic example
includedoes not contain grass, but the header files are there directly. Common source code layout nowadays is to have a directory named as the resulting directory in the distribution, i.e., not
include/grass/*.h. This makes it easier for many code editing tools.
- Python code in
lib/pythonis next to C libraries which may look like it is a C library to communicate with Python.
lib/pythonsuffers from the same as header files in
include. In this case it is even little more serious because it breaks rules on how a Python package should look like. Again, dir named
grassshould be inserted before the dir with the subpackages.
gui/wxpythonagain similar to
lib/pythonbecause there is no "package" directory, but a greater reorganization may be needed as the "wxgui package" is not even in the distribution and the subdirectories are all top-level packages.
- locale or should go to the top level?
Every distribution or platform specific scripts, build recipes etc.
- Are there some packaging systems that require its related files to live on the top level?
- Not strictly packaging, but related, if we have a Binder (mybinder.org) setup, it would require a top-level directory, so in general, there are cases like this.
- tools/vagrant => vagrant
Helper scripts not intended to be installed as a part of GRASS package.
- Content of tools (which should not be called tools, that's too close in meaning to modules).
- The main tools to utils rename done in PR:1348 (merged).
- Other utilities from man, doc, etc.
- We don't really have a separate tests directory now with all tests. We have tests spread in the individual directories they test. So the question is if there is enough on the top level to go into this dir.
- It is used for more than just testing, namely as default location/data/project.
- Since we take the approach of tests being close to the source code, this could likely be distributed to most relevant directories.