index.rst
download.rst
dev-manual/index.rst
+ dev-manual/codelayout.rst
dev-manual/doxygen.rst
dev-manual/doxygen-links.rst
dev-manual/formatting.rst
dev-manual/gmxtree.rst
dev-manual/includestyle.rst
dev-manual/naming.rst
+ dev-manual/overview.rst
dev-manual/style.rst
+ dev-manual/testutils.rst
dev-manual/tools.rst
dev-manual/uncrustify.rst
install-guide/index.rst
--- /dev/null
+General organization of the code and documentation
+==================================================
+
+Source code organization
+------------------------
+
+The source code for |Gromacs| is under the ``src/`` subdirectory
+(except for an analysis tool template, which is under ``share/template/``).
+The subfolders under this directory are:
+
+``src/gromacs/``
+ The code under this directory is built into a single library,
+ `libgromacs`. Installed headers are also located in this hierarchy.
+ This is the main part of the code, and is organized into further subdirectories
+ as *modules* (see below).
+``src/programs/``
+ |Gromacs| executables are built from code under this directory.
+ Although some build options can change this, there is typically only a single
+ binary, ``gmx``, built.
+
+``src/testutils/``
+ Shared utility code for writing unit tests is found under this directory.
+``src/external/``
+ This directory contains bundled source code for various libraries and
+ components that |Gromacs| uses internally.
+``src/contrib/``
+ This directory contains collection of less well maintained code that may or may
+ not compile. It is not included in the build.
+
+Organization under ``src/gromacs/``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+There is no code directly under ``src/gromacs/``, except for some public API
+convenience headers. The code is organized into subdirectories, denoted
+*modules*. Each module consists of a set of routines that do some well-defined
+task or a collection of tasks. Installed headers are a subset of the headers
+in ``src/gromacs/`` and in the module subdirectories. They are installed into a
+corresponding hierarchy under ``include/gromacs/`` in the installation directory.
+Comments at the top of the header files contain a note about their visibility:
+public (installed), intra-library (can be used from inside the library), or
+intra-module/intra-file.
+
+Each module directory contains one or more :file:`{file}.c/.cpp` files, each of which
+has a corresponding :file:`{file}.h` file that declares the external API in that file
+(there are some exceptions, but this gives a general picture).
+Typically, a C++ file declares a class of the same or similar name, but may
+also declare some related classes.
+There can also be a :file:`{file}-impl.h` file that declares classes or functions that
+are not accessible outside the module. In most cases, declarations that
+are not used outside a single source file are in the source file.
+
+Unit tests, and data required for them, are in a ``tests/`` subdirectory under
+the module directory.
+See :doc:`testutils` for more details.
+
+When compiling, the include search path is set to ``src/``. This means that
+files include headers as ::
+
+ #include "gromacs/<module>/<file>.h"
+
+The following is also possible for intra-module headers::
+
+ #include "<file>.h"
+
+See :doc:`includestyle` for more details.
+
+For historical reasons, there are directories ``src/gromacs/gmxana/``,
+``src/gromacs/gmxlib/`, ``src/gromacs/mdlib/``, and ``src/gromacs/gmxpreprocess/``
+that do not follow the above rules. The installed headers for these are in
+`src/gromacs/legacyheaders/``. The aim is to gradually get rid of these
+directories and move code into proper modules.
+
+.. _dev-doc-layout:
+
+Documentation organization
+--------------------------
+
+This Doxygen documentation is made of a few different parts. Use the list
+below as a guideline on where to look for a particular kind of content.
+Since the documentation has been written over a long period of time and the
+approach has evolved, not all the documentation yet follows these guidelines,
+but this is where we are aiming at.
+
+documentation pages
+ These contain mainly overview content, from general-level introduction down
+ into explanation of some particular areas of individual modules.
+ These are generally the place to start familiarizing with the code or a new
+ area of the code.
+ They can be reached by links from the main page, and also through cross-links
+ from places in the documentation where that information is relevant to
+ understand the context.
+module documentation
+ These contain mainly techical content, explaining the general implementation of
+ a particular module and listing the classes, functions etc. in the module.
+ They complement pages that describe the concepts.
+ They can be reached from the Modules tab, and also from all individual classes,
+ functions etc. that make up the module.
+class documentation
+ These document the usage of an individual class, and in some cases that of
+ closely related classes. Where necessary (and time allowing), a broader
+ overview is given on a separate page and/or in the module documentation.
+method documentation
+ These document the individual method. Typically, the class documentation or
+ other overview content is the place to look for how different methods interact.
+file and namespace documentation
+ These are generally only placeholders for links, and do not contain much else.
+ The main content is the list of classes and other entities declared in that
+ file.
-.. _doxygen-page-codelayout: ../doxygen/html-lib/page_codelayout.xhtml
+.. _doxygen-module-testutils: ../doxygen/html-lib/group__module__testutils.xhtml
.. _doxygen-page-modulegraph: ../doxygen/html-lib/page_modulegraph.xhtml
-.. _doxygen-page-unittesting: ../doxygen/html-lib/page_unittesting.xhtml
.. _doxygen-page-wrapperbinary: ../doxygen/html-lib/page_wrapperbinary.xhtml
Parts of the guidelines are still applicable to documenting older code (e.g.,
within ``gmxlib/`` or ``mdlib/``), in particular the guidelines about formatting
the Doxygen comments and the use of ``\internal``.
-See `Doxygen documentation on code layout`__ for
-the overall structure of the documentation.
-
-__ doxygen-page-codelayout_
+See :ref:`dev-doc-layout` for the overall structure of the documentation.
To get started quickly, you only need to read the first two sections to
understand the overall structure of the documentation, and take a look at the
Modules as Doxygen groups
^^^^^^^^^^^^^^^^^^^^^^^^^
-As described in `Doxygen documentation for code layout`__
-each subdirectory under ``src/gromacs/``
+As described in :doc:`codelayout`, each subdirectory under ``src/gromacs/``
represents a *module*, i.e., a somewhat coherent collection of routines.
Doxygen cannot automatically generate a list of routines in a module; it only
extracts various alphabetical indexes that contain more or less all documented
functions and classes. To help reading the documentation, the routines for a
module should be visible in one place.
-__ doxygen-page-codelayout_
-
|Gromacs| uses Doxygen groups to achieve this: for each documented module, there
is a ``\defgroup`` definition for the module, and all the relevant classes and
functions need to be manually added to this group using ``\ingroup`` and
This section describes the techical details and some tips and tricks for
documenting specific code constructs such that useful documentation is
produced. If you are wondering where to document a certain piece of
-information, see the documentation structure section in
-`Doxygen documentation for code layout`__.
+information, see the documentation structure section in :ref:`dev-doc-layout`.
The focus of the documentation should be on the overview content: Doxygen pages
and the module documentation. An experienced developer can relatively easily
read and understand individual functions, but the documentation should help
in getting the big picture.
-__ doxygen-page-codelayout_
-
Doxygen pages
^^^^^^^^^^^^^
http://www.gromacs.org/Developer_Zone contain additional information (much of
it outdated, though), and can be linked from relevant locations in this guide.
-The guide is currently split into two main parts:
+The guide is currently split into a few main parts:
- * Generic guidelines to follow when developing |Gromacs|.
- For some of the guidelines, scripts exist (see below) to automatically
- reformat the code and/or enforce the guidelines for each commit.
- * Instructions on what tools are used, and how to use them.
+* Overview of the |Gromacs| codebase.
+* Generic guidelines to follow when developing |Gromacs|.
+ For some of the guidelines, scripts exist (see below) to automatically
+ reformat the code and/or enforce the guidelines for each commit.
+* Instructions on what tools are used, and how to use them.
.. toctree::
:maxdepth: 2
+ overview
style
tools
common prefix to every file name in the directory) and the remaining part of
the name is unique enough.
-.. TODO: Copy/move relevant content from Doxygen page_codelayout here, and add
+.. TODO: Copy/move relevant content from codelayout.rst here, and add
details.
.. TODO: Consider usage of underscores vs dashes in file names.
--- /dev/null
+Overview of |Gromacs| codebase
+==============================
+
+.. toctree::
+ :maxdepth: 2
+
+ codelayout
--- /dev/null
+Unit testing
+============
+
+The main goal of unit tests in |Gromacs| is to help developers while developing
+the code. They focus on testing functionality of a certain module or a group
+of closely related modules. They are designed for quick execution, such that
+they are easy to run after every change to check that nothing has been broken.
+
+Finding, building and running
+-----------------------------
+
+As described in :doc:`codelayout`, ``src/gromacs/`` is divided into modules,
+each corresponding to a subdirectory. If available, unit tests for that module
+can be found in a ``tests/`` subdirectory under the top-level module directory.
+Typically, tests for code in :file:`{file}.h` in the module is in a corresponding
+:file:`tests/{file}.cpp`. Not all files have corresponding tests, as it may not
+make sense to test that individual file in isolation. Focus of the tests is on
+functionality exposed outside the module. Some of the tests, in particular for
+higher-level modules, are more like integration tests, and test the
+functionality of multiple modules.
+Shared code used to implement the tests is in ``src/external/gmock-1.7.0/`` and
+``src/testutils/`` (see below).
+
+The tests are built if ``BUILD_TESTING=ON`` (the default) and
+``GMX_BUILD_UNITTESTS=ON`` (the default if ``libxml2`` is available) in CMake.
+Each module produces a separate unit test binary (:file:`{module}-test`) under
+``bin/``, which can execute all the tests for that module.
+
+The tests can be executed in a few different ways:
+
+- Build the ``test`` target (e.g., ``make test``):
+ This runs all the tests using CTest. This includes also the regression
+ tests if CMake has been told where to find them (regression tests are not
+ discussed further on this page).
+ If some of the tests fail, this only prints basic summary information (only
+ a pass/fail status for each test binary or regression test class).
+ You can execute the failing test binaries individually to get more
+ information on the failure.
+ Note that ``make test`` does not rebuild the test binaries if you have changed
+ the source code, so you need to separately run ``make`` or ``make tests``.
+ The latter only builds the test binaries and their dependencies.
+- Build the ``check`` target (e.g., ``make check``):
+ This behaves the same as the ``test`` target, with a few extensions:
+
+ 1. Test binaries are rebuilt if they are outdated before the tests are run.
+ 2. If a test fails, the output of the test binary is shown.
+ 3. If unit tests and/or regression tests are not available, a message is
+ printed.
+
+- Directly executing a test binary. This provides the most useful output for
+ diagnosing failures, and allows debugging test failures. The output
+ identifies the individual test(s) that fail, and shows the results of all
+ failing assertions. Some tests also add extra information to failing
+ assertions to make it easier to identify the reason. It is possible to
+ control which tests are run using command line options. Execute the binary
+ with ``-h`` to get additional information.
+
+When executed using CTest, the tests produce XML output in
+``Testing/Temporary/``, containing the result of each test as well as failure
+messages. This XML is used by Jenkins for reporting the test status for
+individual tests. Note that if a test crashes or fails because of an assert or
+a gmx_fatal() call, no XML is produced for the binary, and Jenkins does not
+report anything for the test binary. The actual error is only visible in the
+console output.
+
+Unit testing framework
+----------------------
+
+The tests are written using `Google Test`_, which provides a framework for
+writing unit tests and compiling them into a test binary. Most of the command
+line options provided by the test binaries are implemented by Google Test. See
+the `Google Test Primer`_ for an introduction.
+Some tests also use `Google Mock`_, which provides a framework for creating
+mock implementations of C++ classes. Both components are included in the
+source tree under ``src/external/gmock-1.7.0/``, and are compiled as part of the
+unit test build.
+
+``src/testutils/`` contains |Gromacs|-specific shared test code. This includes
+a few parts:
+
+- CMake macros for declaring test binaries. These take care of providing the
+ ``main()`` method for the test executables and initializing the other parts of
+ the framework, so that the test code in modules can focus on the actual
+ tests. This is the only part of the framework that you need to know to be
+ able to write simple tests: you can use ``gmx_add_unit_test()`` in CMake to
+ create your test binary and start writing the actual tests right away.
+ See ``src/testutils/TestMacros.cmake`` and existing CMake code for examples
+ how to use them.
+
+- Generic test fixtures and helper classes. The C++ API is documented on
+ `Doxygen page for testutils`__. Functionality here includes
+ locating test input files from the source directory and constructing
+ temporary files, adding custom command line
+ options to the test binary, some custom test assertions
+ for better exception and floating-point handling, utilities
+ for constructing command line argument arrays, and
+ test fixtures for tests that need to test long strings for correctness
+ and for tests that execute legacy code where
+ `stdin` reading etc. cannot be easily mocked.
+
+ __ doxygen-module-testutils_
+
+- Some classes and functions to support the above. This code is for internal
+ use of the CMake machinery to build and set up the test binaries, and to
+ customize Google Test to suit our environment.
+
+- Simple framework for building tests that check the results against reference
+ data that is generated by the same test code. This can be used if it is not
+ easy to verify the results of the code with C/C++ code alone, but manual
+ inspection of the results is manageable. The C++ API for this is also
+ documented on the `Doxygen page for testutils`__.
+
+ __ doxygen-module-testutils_
+
+ When the test using the framework is first executed, ``-ref-data create`` can
+ be passed on command line to create the reference data (also options
+ starting with double dashes are accepted).
+ On later executions, the tests read the reference data and fail if the
+ results are not the same. It is possible to update existing reference data
+ with ``-ref-data update``.
+
+ The reference data is stored in XML files under
+ :file:`src/gromacs/{module}/tests/refdata/`. This part of the framework
+ depends on ``libxml2``. For inspecting the reference data in a browser, there
+ are XSLT stylesheets that transform the XML files into HTML. Such custom
+ transformations need to be written for each type of test if the output is
+ not easy to check otherwise. Because of security features in browsers, the
+ transformations may not work for all browsers. For the same reason, the
+ XSLT files must be in the same folder as the XML files. For cases where the
+ XSLT files are shared between multiple modules, ``src/testutils/copy_xsl.sh``
+ takes care to synchronize the files after a master copy is edited.
+
+ The current reference data functionality is quite basic, but it can be extended
+ if/when more control over, e.g., comparison tolerances is needed.
+
+In addition to ``src/testutils/``, some of the module test directories may
+provide reusable test code that is used in higher-level tests. For example,
+the ``src/gromacs/analysisdata/tests/`` provides test fixtures, a mock
+implementation for gmx::AnalysisDataModuleInterface, and some helper classes
+that are also used in ``src/gromacs/trajectoryanalysis/tests/``.
+These cases are handled using CMake object libraries that are linked to all the
+test binaries that need them.
+
+Getting started with new tests
+------------------------------
+
+To start working with new tests, you should first read the `Google Test`_
+documentation to get a basic understanding of the testing framework, and read
+the above description to understand how the tests are organized in |Gromacs|.
+It is not necessary to understand all the details, but an overall understanding
+helps to get started.
+
+Writing a basic test is straightforward, and you can look at existing tests for
+examples. The existing tests have a varying level of complexity, so here are
+some pointers to find tests that use certain functionality:
+
+- ``src/gromacs/utility/tests/stringutil.cpp`` contains very simple tests for
+ functions. These do
+ not use any fancy functionality, only plain Google Test assertions.
+ The only thing required for these tests is the ``TEST()`` macro and the block
+ following it, plus headers required to make them compile.
+- The same file contains also simple tests using the reference framework to
+ check line wrapping (the tests for ``gmx::TextLineWrapper``). The test fixture
+ for these tests is in ``src/testutils/stringtest.h``/``.cpp``. The string test
+ fixture also demonstrates how to add a custom command line option to the
+ test binary to influence the test execution.
+- ``src/gromacs/selection/tests/`` contains more complex use of the
+ reference framework. This is the code the reference framework was
+ originally written for.
+ ``src/gromacs/selection/tests/selectioncollection.cpp`` is the main file to
+ look at.
+- For more complex tests that do not use the reference framework, but instead
+ do more complex verification in code, you can look at
+ ``src/gromacs/selection/tests/nbsearch.cpp``.
+- For complex tests with mock-up classes and the reference framework, you can
+ look at ``src/gromacs/analysisdata/tests/``.
+
+Here are some things to keep in mind when working with the unit tests:
+
+- Try to keep the execution time for the tests as short as possible, while
+ covering the most important paths in the code under test. Generally, tests
+ should take seconds instead of minutes to run, so that no one needs to
+ hesitate before running the tests after they have done some changes.
+ Long-running tests should go somewhere else than in the unit test set.
+ Note that Jenkins runs many of the tests under Valgrind, so heavy tests are
+ going to slow down also that part of the verification.
+- Try to produce useful messages when a test assertion fails. The assertion
+ message should tell what went wrong, with no need to run the *test itself*
+ under a debugger (e.g., if the assertion is within a loop, and the loop
+ index is relevant for understanding why the assertion fails, it should be
+ included in the message). Even better if even a user can understand what
+ goes wrong, but the main audience for the messages is the developer who
+ caused the test to fail.
+
+.. _Google Test: http://code.google.com/p/googletest/
+.. _Google Test Primer: http://code.google.com/p/googletest/wiki/V1_7_Primer
+.. _Google Mock: http://code.google.com/p/googlemock/
+
+.. include:: doxygen-links.rst
doxygen
gmxtree
uncrustify
+ testutils
.. TODO: Add details for most of the tools, either in the form of links to wiki,
or to a separate page that explains more details.
|Gromacs| uses a unit testing framework based on Google C++ Testing
Framework (gtest) and CTest. All unit tests are automatically run on Jenkins
for each commit.
- Details can be found on a separate page on
- `unit testing in the Doxygen documentation`__
-
-__ doxygen-page-unittesting_
+ Details can be found on a separate page on :doc:`testutils`.
regression tests
EXTRACT_STATIC = YES
ALIASES += Gromacs=GROMACS
+ALIASES += linktodevmanual{2}="<A HREF=\"../../dev-manual/\1.html\">\2</A>"
DOT_IMAGE_FORMAT = svg
DOT_MULTI_TARGETS = YES
+++ /dev/null
-Unit testing {#page_unittesting}
-============
-
-The main goal of unit tests in \Gromacs is to help developers while developing
-the code. They focus on testing functionality of a certain module or a group
-of closely related modules. They are designed for quick execution, such that
-they are easy to run after every change to check that nothing has been broken.
-
-Finding, building and running
-=============================
-
-As described in \ref page_codelayout, `src/gromacs/` is divided into modules,
-each corresponding to a subdirectory. If available, unit tests for that module
-can be found in a `tests/` subdirectory under the top-level module directory.
-Typically, tests for code in _file_.h in the module is in a corresponding
-`tests/`<em>file</em>`.cpp`. Not all files have corresponding tests, as it may not
-make sense to test that individual file in isolation. Focus of the tests is on
-functionality exposed outside the module. Some of the tests, in particular for
-higher-level modules, are more like integration tests, and test the
-functionality of multiple modules.
-Shared code used to implement the tests is in `src/external/gmock-1.7.0/` and
-`src/testutils/` (see below).
-
-The tests are built if `BUILD_TESTING=ON` (the default) and
-`GMX_BUILD_UNITTESTS=ON` (the default if `libxml2` is available) in CMake.
-Each module produces a separate unit test binary (_module_`-test`) under
-`bin/`, which can execute all the tests for that module.
-
-The tests can be executed in a few different ways:
- - Build the `test` target (e.g., `make test`):
- This runs all the tests using CTest. This includes also the regression
- tests if CMake has been told where to find them (regression tests are not
- discussed further on this page).
- If some of the tests fail, this only prints basic summary information (only
- a pass/fail status for each test binary or regression test class).
- You can execute the failing test binaries individually to get more
- information on the failure.
- Note that `make test` does not rebuild the test binaries if you have changed
- the source code, so you need to separately run `make` or `make tests`.
- The latter only builds the test binaries and their dependencies.
- - Build the `check` target (e.g., `make check`):
- This behaves the same as the `test` target, with a few extensions:
- 1. Test binaries are rebuilt if they are outdated before the tests are run.
- 2. If a test fails, the output of the test binary is shown.
- 3. If unit tests and/or regression tests are not available, a message is
- printed.
- - Directly executing a test binary. This provides the most useful output for
- diagnosing failures, and allows debugging test failures. The output
- identifies the individual test(s) that fail, and shows the results of all
- failing assertions. Some tests also add extra information to failing
- assertions to make it easier to identify the reason. It is possible to
- control which tests are run using command line options. Execute the binary
- with `-h` to get additional information.
-
-When executed using CTest, the tests produce XML output in
-`Testing/Temporary/`, containing the result of each test as well as failure
-messages. This XML is used by Jenkins for reporting the test status for
-individual tests. Note that if a test crashes or fails because of an assert or
-a gmx_fatal() call, no XML is produced for the binary, and Jenkins does not
-report anything for the test binary. The actual error is only visible in the
-console output.
-
-Unit testing framework
-======================
-
-The tests are written using [Google Test][], which provides a framework for
-writing unit tests and compiling them into a test binary. Most of the command
-line options provided by the test binaries are implemented by Google Test. See
-the [Google Test Primer][] for an introduction.
-Some tests also use [Google Mock][], which provides a framework for creating
-mock implementations of C++ classes. Both components are included in the
-source tree under `src/external/gmock-1.7.0/`, and are compiled as part of the
-unit test build.
-
-`src/testutils/` contains \Gromacs-specific shared test code. This includes
-a few parts:
- - CMake macros for declaring test binaries. These take care of providing the
- %main() method for the test executables and initializing the other parts of
- the framework, so that the test code in modules can focus on the actual
- tests. This is the only part of the framework that you need to know to be
- able to write simple tests: you can use `gmx_add_unit_test()` in CMake to
- create your test binary and start writing the actual tests right away.
- See `src/testutils/TestMacros.cmake` and existing CMake code for examples
- how to use them.
- - Generic test fixtures and helper classes. Functionality here includes
- locating test input files from the source directory and constructing
- temporary files (gmx::test::TestFileManager), adding custom command line
- options to the test binary (#GMX_TEST_OPTIONS), some custom test assertions
- for better exception and floating-point handling (testasserts.h), utilities
- for constructing command line argument arrays (gmx::test::CommandLine) and
- test fixtures for tests that need to test long strings for correctness
- (gmx::test::StringTestBase) and for tests that execute legacy code where
- `stdin` reading etc. cannot be easily mocked
- (gmx::test::IntegrationTestFixture).
- - Some classes and functions to support the above. This code is for internal
- use of the CMake machinery to build and set up the test binaries, and to
- customize Google Test to suit our environment.
- - Simple framework for building tests that check the results against reference
- data that is generated by the same test code. This can be used if it is not
- easy to verify the results of the code with C/C++ code alone, but manual
- inspection of the results is manageable.
-
- When the test using the framework is first executed, `-ref-data create` can
- be passed on command line to create the reference data (also options
- starting with double dashes are accepted).
- On later executions, the tests read the reference data and fail if the
- results are not the same. It is possible to update existing reference data
- with `-ref-data update`.
-
- The reference data is stored in XML files under
- `src/gromacs/`<em>module</em>`/tests/refdata/`. This part of the framework
- depends on `libxml2`. For inspecting the reference data in a browser, there
- are XSLT stylesheets that transform the XML files into HTML. Such custom
- transformations need to be written for each type of test if the output is
- not easy to check otherwise. Because of security features in browsers, the
- transformations may not work for all browsers. For the same reason, the
- XSLT files must be in the same folder as the XML files. For cases where the
- XSLT files are shared between multiple modules, `src/testutils/copy_xsl.sh`
- takes care to synchronize the files after a master copy is edited.
-
- The current reference data functionality is quite basic, but it can be extended
- if/when more control over, e.g., comparison tolerances is needed.
- See gmx::test::TestReferenceData for documentation and existing tests
- (e.g., the selection unit tests) for examples of how to use it.
-
-In addition to `src/testutils/`, some of the module test directories may
-provide reusable test code that is used in higher-level tests. For example,
-the \ref module_analysisdata module provides test fixtures, a mock
-implementation for gmx::AnalysisDataModuleInterface, and some helper classes
-that are also used in \ref module_trajectoryanalysis module tests.
-These cases are handled using CMake object libraries that are linked to all the
-test binaries that need them.
-
-Getting started with new tests
-==============================
-
-To start working with new tests, you should first read the [Google Test][]
-documentation to get a basic understanding of the testing framework, and read
-the above description to understand how the tests are organized in \Gromacs.
-It is not necessary to understand all the details, but an overall understanding
-helps to get started.
-
-Writing a basic test is straightforward, and you can look at existing tests for
-examples. The existing tests have a varying level of complexity, so here are
-some pointers to find tests that use certain functionality:
- - `src/gromacs/utility/tests/stringutil.cpp` contains very simple tests for
- functions (e.g., for gmx::formatString() and gmx::replaceAll()). These do
- not use any fancy functionality, only plain Google Test assertions.
- The only thing required for these tests is the `TEST()` macro and the block
- following it, plus headers required to make them compile.
- - The same file contains also simple tests using the reference framework to
- check line wrapping (the tests for gmx::TextLineWrapper). The test fixture
- for these tests is in `src/testutils/stringtest.h`/`.cpp`. The string test
- fixture also demonstrates how to add a custom command line option to the
- test binary to influence the test execution.
- - The \ref module_selection module tests contain more complex use of the
- reference framework. This is the code the reference framework was
- originally written for.
- `src/gromacs/selection/tests/selectioncollection.cpp` is the main file to
- look at.
- - For more complex tests that do not use the reference framework, but instead
- do more complex verification in code, you can look at
- `src/gromacs/selection/tests/nbsearch.cpp`.
- - For complex tests with mock-up classes and the reference framework, you can
- look at \ref module_analysisdata tests.
-
-Here are some things to keep in mind when working with the unit tests:
- - Try to keep the execution time for the tests as short as possible, while
- covering the most important paths in the code under test. Generally, tests
- should take seconds instead of minutes to run, so that no one needs to
- hesitate before running the tests after they have done some changes.
- Long-running tests should go somewhere else than in the unit test set.
- Note that Jenkins runs many of the tests under Valgrind, so heavy tests are
- going to slow down also that part of the verification.
- - Try to produce useful messages when a test assertion fails. The assertion
- message should tell what went wrong, with no need to run the _test itself_
- under a debugger (e.g., if the assertion is within a loop, and the loop
- index is relevant for understanding why the assertion fails, it should be
- included in the message). Even better if even a user can understand what
- goes wrong, but the main audience for the messages is the developer who
- caused the test to fail.
-
-[Google Test]: http://code.google.com/p/googletest/
-[Google Test Primer]: http://code.google.com/p/googletest/wiki/V1_7_Primer
-[Google Mock]: http://code.google.com/p/googlemock/
+++ /dev/null
-General organization of the code and documentation {#page_codelayout}
-==================================================
-
-Source code organization
-========================
-
-The source code for \Gromacs is under the `src/` subdirectory
-(except for an analysis tool template, which is under `share/template/`).
-The subfolders under this directory are:
-<dl>
-<dt>`src/gromacs/`</dt>
-<dd>
-The code under this directory is built into a single library,
-`libgromacs`. Installed headers are also located in this hierarchy.
-This is the main part of the code, and is organized into further subdirectories
-as _modules_ (see below)
-</dd>
-<dt>`src/programs/`</dt>
-<dd>
-\Gromacs executables are built from code under this directory.
-Although some build options can change this, there is typically only a single
-binary, `gmx`, built.
-</dd>
-\if libapi
-<dt>`src/testutils/`</dt>
-<dd>
-Shared utility code for writing unit tests is found under this directory.
-</dd>
-<dt>`src/external/`</dt>
-<dd>
-This directory contains bundled source code for various libraries and
-components that \Gromacs uses internally.
-</dd>
-<dt>`src/contrib/`</dt>
-<dd>
-This directory contains collection of less well maintained code that may or may
-not compile. It is not included in the build.
-</dd>
-\endif
-</dl>
-\if libapi
-\subpage page_modulegraph
-\endif
-
-Organization under `src/gromacs/`
----------------------------------
-
-There is no code directly under `src/gromacs/`, except for some public API
-convenience headers. The code is organized into subdirectories, denoted
-_modules_. Each module consists of a set of routines that do some well-defined
-task or a collection of tasks. Installed headers are a subset of the headers
-in `src/gromacs/` and in the module subdirectories. They are installed into a
-corresponding hierarchy under `include/gromacs/` in the installation directory.
-Comments at the top of the header files contain a note about their visibility:
-public (installed), intra-library (can be used from inside the library), or
-intra-module/intra-file.
-
-Each module directory contains one or more `<file>.c/.cpp` files, each of which
-has a corresponding `<file>.h` file that declares the external API in that file
-(there are some exceptions, but this gives a general picture).
-Typically, a C++ file declares a class of the same or similar name, but may
-also declare some related classes.
-There can also be a `<file>-impl.h` file that declares classes or functions that
-are not accessible outside the module. In most cases, declarations that
-are not used outside a single source file are in the source file.
-
-Unit tests, and data required for them, are in a `tests/` subdirectory under
-the module directory.
-\if libapi
-See \ref page_unittesting for more details.
-\endif
-
-When compiling, the include search path is set to `src/`. This means that
-files include headers as
-
- #include "gromacs/<module>/<file>.h"
-
-The following is also possible for intra-module headers:
-
- #include "<file>.h"
-
-For historical reasons, there are directories `src/gromacs/gmxana/`,
-`src/gromacs/gmxlib/`, `src/gromacs/mdlib/`, and `src/gromacs/gmxpreprocess/`
-that do not follow the above rules. The installed headers for these are in
-`src/gromacs/legacyheaders/`. The aim is to gradually get rid of these
-directories and move code into proper modules.
-
-Documentation organization
-==========================
-
-This Doxygen documentation is made of a few different parts. Use the list
-below as a guideline on where to look for a particular kind of content.
-Since the documentation has been written over a long period of time and the
-approach has evolved, not all the documentation yet follows these guidelines,
-but this is where we are aiming at.
-
-<dl>
-<dt>documentation pages</dt>
-<dd>
-These contain mainly overview content, from general-level introduction down
-into explanation of some particular areas of individual modules.
-These are generally the place to start familiarizing with the code or a new
-area of the code.
-They can be reached by links from the main page, and also through cross-links
-from places in the documentation where that information is relevant to
-understand the context.
-</dd>
-<dt>module documentation</dt>
-<dd>
-These contain mainly techical content, explaining the general implementation of
-a particular module and listing the classes, functions etc. in the module.
-They complement pages that describe the concepts.
-They can be reached from the Modules tab, and also from all individual classes,
-functions etc. that make up the module.
-</dd>
-<dt>class documentation</dt>
-<dd>
-These document the usage of an individual class, and in some cases that of
-closely related classes. Where necessary (and time allowing), a broader
-overview is given on a separate page and/or in the module documentation.
-</dd>
-<dt>method documentation</dt>
-<dd>
-These document the individual method. Typically, the class documentation or
-other overview content is the place to look for how different methods interact.
-</dd>
-<dt>file and namespace documentation</dt>
-<dd>
-These are generally only placeholders for links, and do not contain much else.
-The main content is the list of classes and other entities declared in that
-file.
-</dd>
-</dl>
Currently, only parts of the code are documented here. The following pages
give an overview of some of the topics that are documented:
- - \subpage page_codelayout <br/>
- This is a good place to start to understand how to
- navigate the code and the documentation.
- \subpage page_analysisframework <br/>
Provides an overview of the framework that the \Gromacs library provides for
writing (trajectory) analysis tools.
- \subpage page_simd <br/>
Documentation about the new SIMD module that makes it possible to write
highly accelerated CPU code that is still portable.
+
+ - \subpage page_modulegraph <br/>
+ Automatically generated module dependency graph.
\endif
This list will hopefully expand over time.
The headers for the public \Gromacs API are installed in `include/gromacs/`
under the installation directory. The layout reflects the source code layout
-under the `src/gromacs/` directory (see \ref page_codelayout). The headers
+under the `src/gromacs/` directory (see \linktodevmanual{codelayout,Source
+code layout}). The headers
directly under `include/gromacs/` do not contain any declarations, but instead
include a collection of headers from subdirectories.
You should prefer to include these convenience headers instead of individual
Documentation for developers
----------------------------
-Resources for developers, e.g., related to guidelines and tools used during
-development.
+The developer documentation currently consists of two parts:
+
+* A developer guide that provides an overview of the |Gromacs| codebase, and
+ includes more detailed resouces such as guidelines and information on tools
+ used during development.
+* Doxygen documentation extracted from comments in C/C++ code, documenting the
+ actual C/C++ code.
+
+Some overview documentation that is closely related to the actual C/C++ code
+appears in the Doxygen documentation, while some other overview content is in
+the developer guide. The reasons are partially technical, but crosslinks
+between the developer guide and the Doxygen documentation are provided whenever
+related content appears split between the two sources.
+
+The documentation does not yet cover all areas, but more content is being
+(slowly) added.
+
+Contents:
.. toctree::
:maxdepth: 3
dev-manual/index
-* `Doxygen public API documentation <doxygen/html-user/index.xhtml>`_
+* Doxygen documentation
+
+ * `Public API documentation <doxygen/html-user/index.xhtml>`_
+ This contains documentation for code that appears in installed headers,
+ as well as some overview documentation to understand those parts of the
+ code.
+ Please note that the definition of the public API is very preliminary
+ and subject to change, in particular for parts that have not been
+ documented.
+ * `Code documentation <doxygen/html-lib/index.xhtml>`_
+ This contains the public API documentation as a subset, but also has more
+ details on the internal implementation of |Gromacs|. This is a good
+ place to start to understand some specific area of the code in general
+ to, e.g., contribute.
+ * `Full documentation <doxygen/html-full/index.xhtml>`_
+ This contains every single documented function from the codebase,
+ including internal There can be an overwhelming amount of detail, but
+ this can be useful if trying to find some specific function within the
+ codebase.
-* `Doxygen code documentation <doxygen/html-lib/index.xhtml>`_
- This contains the public API documentation as a subset, but also has more
- details on the internal implementation of |Gromacs|.
Indices and tables
==================
* \inlibraryapi
* \ingroup module_testutils
*/
-/*! \libinternal \defgroup module_testutils Unit Testing Utilities (testutils)
- * \brief
- * Common helper classes and functions for writing unit tests.
- *
- * To build unit tests using these utilities, libxml2 is required.
- *
- * \ingroup group_utilitymodules
- */
#ifndef GMX_TESTUTILS_TESTFILEMANAGER_H
#define GMX_TESTUTILS_TESTFILEMANAGER_H
--- /dev/null
+/*
+ * This file is part of the GROMACS molecular simulation package.
+ *
+ * Copyright (c) 2015, by the GROMACS development team, led by
+ * Mark Abraham, David van der Spoel, Berk Hess, and Erik Lindahl,
+ * and including many others, as listed in the AUTHORS file in the
+ * top-level source directory and at http://www.gromacs.org.
+ *
+ * GROMACS is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public License
+ * as published by the Free Software Foundation; either version 2.1
+ * of the License, or (at your option) any later version.
+ *
+ * GROMACS is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with GROMACS; if not, see
+ * http://www.gnu.org/licenses, or write to the Free Software Foundation,
+ * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * If you want to redistribute modifications to GROMACS, please
+ * consider that scientific software is very special. Version
+ * control is crucial - bugs must be traceable. We will be happy to
+ * consider code for inclusion in the official distribution, but
+ * derived work must not be called official GROMACS. Details are found
+ * in the README & COPYING files - if they are missing, get the
+ * official version at http://www.gromacs.org.
+ *
+ * To help us fund GROMACS development, we humbly ask that you cite
+ * the research papers on the package. Check out http://www.gromacs.org.
+ */
+/*! \internal \file
+ * \brief
+ * Dummy header for \ref module_testutils documentation.
+ *
+ * \author Teemu Murtola <teemu.murtola@gmail.com>
+ * \ingroup module_testutils
+ */
+/*! \libinternal \defgroup module_testutils Testing Utilities (testutils)
+ * \brief
+ * Common helper classes and functions for writing tests using Google Test.
+ *
+ * General documentation for the testing in \Gromacs can be found in the
+ * \linktodevmanual{index,developer guide}. This page provides an overview of
+ * the actual API provided by the `testutils` module.
+ *
+ * There are several distinct functionalities provided:
+ * - gmx::test::TestFileManager (in testfilemanager.h) provides functionality
+ * for locating test input files from the source directory and managing
+ * temporary files that need to be created during the test.
+ * - #GMX_TEST_OPTIONS macro provides facilities for adding custom command
+ * line options for the test binary.
+ * - testasserts.h provides several custom test assertions for better
+ * exception and floating-point handling than built-in Google Test
+ * assertions.
+ * - gmx::test::TestReferenceData and related classes (in refdata.h) provide
+ * utilities to write regression-style tests that check that the test
+ * produces the same results as an earlier run of the same test. The
+ * reference data is stored as XML files. For certain types of tests, the
+ * XML can also be easier to inspect manually for correctness than writing
+ * the checks in C++, providing an alternative method to write assertions.
+ * - gmx::test::CommandLine and related classes (in cmdlinetest.h) provide
+ * utilities for constructing command line argument arrays for use in tests
+ * that invoke actual commands.
+ * - gmx::test::StringTestBase provides a test fixture for tests that need to
+ * test long strings for correctness.
+ * - gmx::test::IntegrationTestFixture provides a test fixture for tests that
+ * execute legacy code where `stdin` reading etc. cannot be easily mocked.
+ *
+ * Additionally, testinit.h and mpi-printer.h, and their corresponding source
+ * files, provide functionality that is not visible on the API level: they
+ * provide initialization routines for the above functionality, which are
+ * automatically called by the %main() function provided in unittest_main.cpp.
+ *
+ * mpi-printer.h provides a Google Test listener that is installed when the
+ * tests are compiled with MPI. This listener allows the test binary to be run
+ * on multiple MPI ranks, and synchronizes the execution and output from the
+ * test cases, as well as makes the test fail on even if an assertion fails
+ * only on one rank.
+ *
+ * \ingroup group_utilitymodules
+ */
biod.pnpi.spb.ru / alexxy / gromacs.git / commitdiff