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.

Folder structure

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.

CI

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.

Questions:

• 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.

doc

Documentation, that is not individual module help files.

• doc

src

All source of GRASS. Should contain everything worth compiling.

Questions:

• 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.
• Should include be 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):

• include contains things for make, so any includes would go here? E.g., Jinja templates if we would have some or more realistic example *.cmake files.
• include does 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/*.h but include/grass/*.h. This makes it easier for many code editing tools.
• Python code in lib/python is next to C libraries which may look like it is a C library to communicate with Python.
• lib/python suffers 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 grass should be inserted before the dir with the subpackages.
  • ​https://github.com/OSGeo/grass/issues/1100
• gui/wxpython again similar to include and lib/python because 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.

Subdirectories:

• db
• display
• general
• gui
• imagery
• include
• lib
• locale or should go to the top level?
• misc
• ps
• raster
• raster3d
• scripts
• temporal
• vector

packaging

Every distribution or platform specific scripts, build recipes etc.

Questions:

• 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.

Subdirectories:

• docker
• macos
• mswindows
• rpm
• singularity
• tools/vagrant => vagrant

utils

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).
• Other utilities from man, doc, etc.

tests

Testing infrastructure.

Questions:

• 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.

Subdirectories:

• demolocation
  • It is used for more than just testing, namely as default location/data/project.
• testsuite
  • Since we take the approach of tests being close to the source code, this could likely be distributed to most relevant directories.