Library Structure

    Here is a discussion of how the Gromacs libraries will change in the near future. This page contains a status overview and guidelines for coding.

    New Source Tree Layout

    This section discusses the source tree layout where we want to aim in the long term. Concrete steps of how this could be reached are discussed in the next section.

    • A single library, libgromacs, is built from code under src/gromacs/.
    • Under src/gromacs/, we have subdirectories for modules. Each module consists of a set of routines that do some well-defined task or a collection of tasks, such as basic math functions, topology handling, or trajectory I/O.
    • Modules must have a well-defined hierarchy: cycles are not allowed in the (include) dependency graph for the modules, even if they would not create cycles when looked at the file level (separately forbidden below).
    • Each module directory contains one or more file.c/.cpp files, each of which have a corresponding file.h file that declares the external API in that file. There can also be a file-impl.h file that declares classes or functions that are not accessible outside the file/module. In most cases, declarations that are not used outside the file should go into the source file, though. If a file does not contain any symbols that are accessible outside the module, the -impl suffix can be omitted, but comments in the header file should indicate that it should not be used outside the module.
    • Each module has a header file src/gromacs/module.h that includes the public API headers from the module. This header is installed into include/gromacs/, and all headers it includes are installed under include/gromacs/module/. Other headers are not installed. Comments at the top of the header files should contain a note what's their visibility: public (installed), intra-library (can be used from inside the library), or intra-module/intra-file. See separate page on using Doxygen for documenting headers.
    • Unit tests, and data required for them, go into a tests/ subdirectory under the module directory.
    • When compiling, the include search path is set to src/. Source files should include headers as #include "gromacs/module/file.h". #include "file.h" is allowed for intra-module/intra-file headers. Include files should include headers like #include "../othermodule/file.h" (relative paths are mandatory for installed headers, the source file include syntax is allowed for other headers).
    • Every installed header should compile by itself, without any reference to variables defined in config.h or requiring other headers to be included before it. Cyclic include dependencies also cause this. This is best guaranteed by including every header in some source file as the first header, even before config.h. This will require moving GMX_DOUBLE and similar out of config.h into defines given to the compiler on the command-line.
    • Code inside the library should not unnecessarily include headers. In particular, headers should not include other headers if a forward declaration of a type is enough for the header. Within the library source files, include only headers from other modules that are necessary for that file. You can use the public API header if you really require everything declared in it.
    • Each executable is compiled from source files under src/programs/exename/. The main function should reside in exename.c/.cpp, and other code specific to that executable should be in files organized as in the module directories. Executables should only use the public API headers, and not include anything from the module directories directly. UPDATE: If we go all the way with #685, and have only a single binary (at least in the most common cases), then these guidelines will be largely obsolete. In particular if we implement it such that all logic except the launcher is actually in libgromacs. Also, depending on the answers to #988, the guidelines on usage of public API headers only may need to be revised.

    Points for discussion:

    • Where do we put larger-scale tests like regression tests for whole programs? Into a separate repository as it is now, or somewhere within the source tree?

    Migrating to New Layout

    To migrate from existing code to the new layout, the following steps are planned:

    • Create a src/gromacs/ directory and move the src/gmxlib/ and src/mdlib/ into src/gromacs/gmxlib/ and src/gromacs/mdlib/. Move the contents of include/ directory into src/gromacs/legacyheaders/. This is required to make it possible to include these headers from other installed headers using relative paths. Set up the build such that a single library is built from these files.
    • Move the source code from src/kernel/ into src/programs/mdrun/, src/programs/grompp/ etc. as appropriate and set up the build actions. Move stuff that is needed in more than one binary into src/gromacs/gmxpreprocess/, and include that in the library.
    • Gradually move and/or rewrite in C++ items from the directories under src/gromacs/ into separate module directories, moving the corresponding include files from src/gromacs/legacyheaders/ at the same time. At the same time, the code should be cleaned up (but do any substantial modifications in separate commit(s) from the rename, otherwise git will lose history), according to the new coding standards, as much as is reasonable (UPDATE: uncrustify will be run separately to do a batch clean-up for most coding style issues). Ideally, code that has been migrated should not reference any of the old files, but it can be easier to first migrate clear units from the higher-level code than all the misc. low-level stuff.
    • Gradually move tools from src/tools/ into subdirectories under src/programs/. At the same time, move common functionality into modules under src/gromacs/. A major rework of the tools that analyze trajectory frames is planned; moving them to the new layout does not have a high priority as they will need to change significantly when this new analysis framework will be in place, and that is the natural time to migrate them. UPDATE: depending on the answer to #685 and #1013, we may want to move the contents of src/tools/ to src/gromacs/tools/ and merge that into libgromacs. The master branch already builds nearly all the tools into a single binary.

    See also the page about Compilation for other changes that are imminent.

    Page last modified 05:41, 20 Feb 2014 by tmurtola