source: trunk/README.developer @ 2067

Last change on this file since 2067 was 2067, checked in by Peter, 10 years ago

fixed typo

  • 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.7 KB

$Id: README.developer 2067 2009-09-16 18:01:29Z 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 [http://cbbp.thep.lu.se/~jari/documents/subversion_guidelines/index.html 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.

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 Autotools. More specifically

  • Automake 1.10 (or later)
  • Autoconf 2.61 (or later)
  • 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

Enable svn-support

If you are building from an svn wc, you may run 'configure' with option '--enable-svn-support' to turn on some extra make targets. Most of the targets are useful at release time, i.e., probably not very useful for other developers than the release manager. See build_support/svn_support.am for more details.

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.

Specifically this implies:

  • Do not remove or modify any function (except private), not even add a parameter with default value because it will make the function incompatible with earlier header files.
  • Do not add or change order among virtual functions because it will change the layout of the virtual table.

Copyright (C) 2003 Jari Häkkinen, Peter Johansson
Copyright (C) 2004 Jari Häkkinen
Copyright (C) 2006, 2007, 2008 Jari Häkkinen, Peter Johansson
Copyright (C) 2009 Jari Häkkinen
This file is part of yat library, http://dev.thep.lu.se/yat
The yat library is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License as
published by the Free Software Foundation; either version 3 of the
License, or (at your option) any later version.
The yat library 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
General Public License for more details.
You should have received a copy of the GNU General Public License
along with yat. If not, see <http://www.gnu.org/licenses/>.
Note: See TracBrowser for help on using the repository browser.