.. _contributing:
.. index:: Contributing
Contributing to :program:`libvdwxc`
**********************************************
:program:`libvdwxc` follows the GNU Coding Standards as much as
permitted by the experience of its developers. If you are planning to
contribute, we thus recommend you to consult the official `GNU Coding
Standards homepage `_ before
doing so.
.. index:: Contributing; Programming language
Programming language
====================================
The core of :program:`libvdwxc` is written in C. All other languages
must be supported through bindings.
Since we use the Autotools to build, install, and distribute the code,
all C, C++, or Fortran files, must be stored in language-specific
subdirectories. Mixes should not happen in the same directory, and
even less in the same library.
.. index:: Contributing; Optional features
Optional features
====================================
Optional features are triggered either through `HAVE_FEATURE` or
`VDW_FEATURE` preprocessing options, where `FEATURE` is the name of
the feature. All these preprocessing options are handled through
`config.h`, with the exception of the Autotools-reserved
`HAVE_CONFIG_H` option.
Within the source code, access to the optional features is granted in
a boolean way, i.e.::
#if defined HAVE_FEATURE
... do something optional ...
#endif
This allows keeping the build system as simple and maintainable as
possible.
.. index:: Contributing; C header files
C header files
====================================
In order to keep the build process smooth and simple, we have adopted
the following conventions for the inclusion of C headers:
* system headers should come first, then external dependency headers,
then internal exported headers, then internal non-exported headers,
then `config.h`, and finally non-exported headers depending on
`config.h` and/or conditional inclusions;
* all headers coming from outside :program:`libvdwxc` must be included
using "less than" and "greater than" as delimiters;
* internal headers must be included using double quotes as delimiters;
* the inclusion of `config.h` must be controlled by the
`HAVE_CONFIG_H` preprocessing option;
* exported headers must not depend on `config.h` nor on non-exported
headers;
* all exported header names (apart from `vdwxc.h`) must be prefixed
with `vdwxc_`;
* headers depending on `config.h` should be minimised;
* `config.h` must be readable from Fortran.
Here is an example where the source code depends on the FFT library
available::
#include
#include
#include
#include
#include "vdwxc.h"
#include "vdw_splines.h"
#if defined HAVE_CONFIG_H
#include "config.h"
#endif
#ifdef HAVE_PFFT
#include
#else
#ifdef HAVE_MPI
#include
#else
#include
#endif
#endif
Keeping the build system updated
====================================
When changing the contents of a file, the build system does not need
to be updated. However, when adding, removing, or renaming files, you
have to inform the build system of what happened. The corresponding
procedures are described in [Hacking the build
system](hacking-the-build-system.html).
.. index:: Contributing; Testing
Testing
====================================
When adding new functions, it is extremely important to provide simple
test programs, aka "unit tests", to check whether these functions are
performing as they should. If you do not feel comfortable with
integrating these tests with the build system, please notify the other
developers.
Systematically writing unit tests is not only essential to maintain
the overall quality of the code. It will greatly help efficiently
design and structure your contributions, since you will always have a
concrete use example at hand to feed your thoughts.