Definition of "public API" - Redmine #988
Archive from user: Teemu Murtola
One of the goals stated on the wiki for 5.0 is for libgromacs
to
behave more like a real library. To this end, we should think about what
we want to expose as the “public API” of libgromacs
and how fixed are
we ready to keep those parts between releases.
There are at least the following aspects to consider:
- Which symbols (classes/functions/types) we want to export from our shared library/libraries? (see #701)
- Which symbols we document as being part of our public API? (see Doxygen documentation instructions in the Doxygen-generated documentation for the current approach)
- Which symbols are declared in installed headers?
- Should symbols that are not part of a public API, but are
declared in installed headers, be within a separate namespace
such as
internal
ordetail
?
- Should symbols that are not part of a public API, but are
declared in installed headers, be within a separate namespace
such as
- Which symbols are used in our executables?
- What is the division between the library and the executables?
- Which symbols are used in our unit tests?
This issue is mostly about discussing the above aspects. The outcome should be a clear definition of how the above-mentioned aspects should relate to each other in our code.
A few points to support the discussion:
- Symbols used in installed binaries must be exported.
- Symbols used in unit tests should be exported to avoid a lot of headaches and build system complications.
- If we have our library internally divided into modules, it may also make a lot of sense to unit test also some of the interfaces between modules, even if they are not public.
- Currently, with the exception of
mdrun
andgmx view
, essentially all the code for the programs is withinlibgromacs
, and the executable is only a shell. If we move more content into the executables, can we support things like Python bindings to the analysis tools?
(from redmine: issue id 988, created on 2012-08-03 by gmxdefault)
- Relations:
- relates #701 (closed)
- relates #999 (closed)
- relates #1013 (closed)
- relates #2045 (closed)
- relates #2698 (closed)
- relates #2912 (closed)
- relates #3034 (closed)
- Changesets:
- Revision 91ea2482 by Paul Bauer on 2019-08-23T14:21:45Z:
Removes checker for installed files
As the plan is to remove the current handling of installed header files,
this removes the checker parts from the doxygen check-source script for
this attribute.
Refs #2382, #2139, #988
Change-Id: I76b519f39a5c793c9f1ea8c1eb5eebb39b4a9352
- Revision 52e3d670 by Paul Bauer on 2019-08-26T13:26:07Z:
Remove installed headers from CMake
Removed the gmx_install_header sections from CMake files, as well as the
CMake code used to add and check them.
Refs #2382, #2139, #988
Change-Id: I4525ea14d2967f83d940300daeb2ade08717ed5d
- Revision 393f214e by Paul Bauer on 2019-08-26T14:10:16Z:
Remove section checking api level
Removes the check for api levels in check-source to allow modernization
without having to account for the legacy api layout.
Refs #988
Change-Id: I12cd3f6765bc57801ff4dd81583b7836dc4f18fb
- Revision feba5ffb by Christoph Junghans on 2019-09-13T09:21:23Z:
cmake: add option to install legacy headers
This is needed for package like VOTCA to use the C-API until
a real GMX API got established.
Refs #988
Change-Id: I87b6f81641cb5bcac5ceb6ff6fb3dbd9e6650ea5