Context Navigation

source: trunk/README.developer @ 2500

Visit:

Last change on this file since 2500 was 2500, checked in by Peter, 12 years ago
document that developers should have doxygen available. refs #392
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision` Property svn:mime-type set to `text/x-trac-wiki`
File size: 8.6 KB

$Id: README.developer 2500 2011-06-26 21:47:14Z peter $

Coding Style

We follow the coding style described in C++ coding guidelines pdf postscript with the additions described here.

Subversion usage

Commits should be minimalistic and the project should always compile (make and make check) when someone makes a clean checkout. There is a short introduction to subversion and its usage available as Subversion guidelines. We follow these guidelines.

Testing

The test suite is run with make check at the project root directory level.

The test suite should at minimum include creation of all classes (to catch linking errors) and calls to template functions (as template functions are not compiled until they are needed). There is a test that checks that minimum amount of documentation is written. This test is skipped if doxygen is not available and for that reason it is recommended to have doxygen available if you modify header files.

For more details on writing and running tests, see file test/README .

Interfacing Gnu Scientific Library, GSL

The GSL documentation describes how GSL error handling works. The GSL library follows the thread-safe error reporting conventions of the posix Threads library. That is, functions return a non-zero error code to indicate an error. In most cases yat just returns whatever the underlying GSL library calls returns. If GSL errors occur in constructors yat handles them accordingly. If GSL reports errors that cannot be resolved by yat a GSL_error exception will be thrown. However, the default behaviour of GSL library is to call abort() when unrecoverable errors occur and puts the yat (and any other) GSL error treatment out of play. For production environments, yat and GSL users should turn off the default GSL error treatment by calling gsl_set_error_handler_off(), but also when yat's GSL error treatment is preferred.

When new GSL functionality is introduced to yat, it is the responsibility of the programmer to make sure that GSL errors are treated properly. Proper GSL error treatment is very important in cases when yat users turn off the default GSL error handler since:

yat aims at treating GSL errors appropriately in an exception safe and neutral way but there is still some work to do before we do exceptions in a neutral way.

Doxygen

We generate our documentation using Doxygen (version 1.5 or later). Doxygen allows several different styles. We try to use the following style as we have found this minimizes parsing problems:

/**
   \brief My class
   Some text documenting the class MyClass
*/
class MyClass

or similarly

/**
   \brief magic function
   Some text documenting my_function
*/
void my_function(void);

We use doxygen keywords preceded by \ such as \brief, \return. All classes and functions have a brief description, which increases clarity on summary pages.

Try to keep comment line lengths within the terminal character limit, in other words, less than 80 characters per line. This makes the comments more readable.

Internal Interface

Helper functions and classes that are not part of yat API should either be labeled with doxygen flag \internal or placed in sub-namespace detail.

Build

Requirements

To build from a subversion checkout, you will need GNU Autotools. More specifically

Automake 1.11 (or later), http://www.gnu.org/software/automake/
Autoconf 2.63 (or later), http://www.gnu.org/software/automake/
Libtool 1.5 (or later), http://www.gnu.org/software/libtool/

Disable shared library

yat uses GNU Libtool in order to build shared libraries on a variety of systems. While this is very nice for making usable binaries, it can be a pain when trying to debug a program. For that reason, compilation of shared libraries can be turned off by specifying the --disable-shared option to configure.

Debugging using GDB

If shared library is enabled (default), Libtool creates wrapper scripts in directory test/ that call the test programs located in directory test/.libs/. While this allows us to dynamically link against the temporary library in yat/, it makes straightforward usage of GDB impossible. For that reason libtool provides a wrapper:

#> libtool --mode=execute gdb foo_test

that sets the necessary environment variables. For more detailed discussion, please refer to the libtool manual:

http://www.gnu.org/software/libtool/manual/libtool.html#Debugging-executables

Versioning

We use a softened version of APR guidelines which in short implies

"The basic intent is that MAJOR versions are incompatible, large-scale upgrades of the API. MINOR versions retain compatibility with older minor versions, and changes in the PATCH level are perfectly compatible, forwards and backwards."

`MAJOR` Releases

No compatibility is guaranteed between MAJOR versions.

`MINOR` Releases

MINOR versions should be compatible with earlier minor versions. However, in the 0.x line we may allow exceptions to this rule, if developers agree the gain of change is sufficient. Binary compatibility is typically not guaranteed between MINOR versions. The YAT_LT_VERSION in version.m4 should reflect which versions are binary compatible.

`PATCH` Releases

Versions with same MAJOR.MINOR are perfectly compatible, forwards and backwards. This implies that only implementations can be modified in a PATCH release. You cannot change the API, not even add functions or classes because it will break forward compatibility for the previous PATCH version. A PATCH release is a pure bug fix release

Backward Source Compatibility

Backward Source Compatibility means that an application that could build against version x.y shall also build without error against x.y+1. An application that compiled against header files from previous MINOR version shall also compile without errors against the header files of the new version.

Specifically this implies:

Do not remove any public, protected, or free functions.
If you modify a function, its signature must be compatible with previous signature, e.g., new parameters with default values may be added to signature.
Do not remove any class or inheritance for a class.

Backward Binary Compatibility

Backward Binary Compatibility means that an application that has been compiled against version x.y can be linked against version x.y+1.