source: trunk/README.developer @ 2071

Last change on this file since 2071 was 2071, checked in by Peter, 14 years ago

wrapping some long lines

  • 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
RevLine 
[2]1$Id: README.developer 2071 2009-09-24 15:19:44Z peter $
2
[1674]3= Coding Style =
[1605]4
[1674]5We follow the coding style described in
6[http://cbbp.thep.lu.se/~jari/documents/c++_coding_guidelines/index.html C++ coding guidelines]
7[http://cbbp.thep.lu.se/~jari/documents/c++_coding_guidelines/c++_coding_guidelines.pdf pdf] 
8[http://cbbp.thep.lu.se/~jari/documents/c++_coding_guidelines/c++_coding_guidelines.ps postscript]
9with the additions described here.
10
[1721]11=== Subversion usage ===
12
13Commits should be minimalistic and the project should always compile
14(`make` and `make check`) when someone makes a clean checkout. There
15is a short introduction to subversion and its usage available as
16[http://cbbp.thep.lu.se/~jari/documents/subversion_guidelines/index.html
17Subversion guidelines]. We follow these guidelines.
18
[1674]19=== Testing ===
20
[1721]21The test suite is run with `make check` at the project root directory
22level.
[1674]23
[1721]24The test suite should at minimum include creation of all classes (to
25catch linking errors) and calls to template functions (as template
26functions are not compiled until they are needed). There is a test
27that checks that minimum amount of documentation is written.
28
29For more details on writing and running tests, see file
30[source:trunk/test/README test/README].
31
[1674]32=== Interfacing [http://www.gnu.org/software/gsl/ Gnu Scientific Library, GSL] ===
33
34The GSL documentation describes how
35[http://www.gnu.org/software/gsl/manual/html_node/Error-Handling.html#Error-Handling GSL error handling]
36works. The GSL library follows the thread-safe
37error reporting conventions of the posix Threads library. That is,
38functions return a non-zero error code to indicate an error. In most
39cases yat just returns whatever the underlying GSL library calls
40returns. If GSL errors occur in constructors yat handles them
41accordingly. If GSL reports errors that cannot be resolved by yat a
42[http://cbbp.thep.lu.se/~jari/documents/yat/classtheplu_1_1yat_1_1utility_1_1GSL__error.html GSL_error]
43exception will be thrown. However, the default behaviour of
44GSL library is to call abort() when unrecoverable errors occur and
45puts the yat (and any other) GSL error treatment out of play. For
[2067]46production environments, yat and GSL users should turn off the default
[1674]47GSL error treatment by calling gsl_set_error_handler_off(), but also
48when yat's GSL error treatment is preferred.
49
50When new GSL functionality is introduced to yat, it is the
[1721]51responsibility of the programmer to make sure that GSL errors are
[1674]52treated properly. Proper GSL error treatment is very important in
53cases when yat users turn off the default GSL error handler since:
54
55yat aims at treating GSL errors appropriately in an
56[http://www.gotw.ca/gotw/008.htm exception safe and neutral]
57way but there is still some work to do before we do exceptions in a neutral way.
58
59=== Doxygen ===
[2071]60We generate our documentation using [http://www.doxygen.org Doxygen]
61(version 1.5 or later). Doxygen allows several different styles. We
62try to use the following style as we have found this minimizes parsing
63problems:
[1674]64
65{{{
66/**
67   \brief My class
68
69   Some text documenting the class MyClass
70*/
71class MyClass
72}}}
73
74or similarly
75
76{{{
77/**
78   \brief magic function
79
80   Some text documenting my_function
81*/
82void my_function(void);
83}}}
84
[2071]85We use doxygen keywords preceded by `\` such as `\brief`,
86`\return`. All classes and functions have a brief description, which
87increases clarity on summary pages.
[1674]88
[2071]89Try to keep comment line lengths within the terminal character limit,
90in other words, less than 80 characters per line. This makes the
91comments more readable.
[1674]92
93'''Internal Interface'''
94
95Helper functions and classes that are not part of yat API should either be
96labeled with doxygen flag `\internal` or placed in sub-namespace `detail`.
97
98= Build =
99
100== Requirements ==
101
[1605]102To build from a subversion checkout, you will need Autotools. More
[1674]103specifically
104 * Automake 1.10 (or later)
[1686]105 * Autoconf 2.61 (or later)
[1674]106 * Libtool.
[1605]107
[1674]108== Disable shared library ==
[573]109
[1368]110yat uses gnu Libtool in order to build shared libraries on a variety
111of systems.  While this is very nice for making usable binaries, it
112can be a pain when trying to debug a program. For that reason,
113compilation of shared libraries can be turned off by specifying the
114`--disable-shared` option to configure.
115
[1674]116== Debugging using GDB ==
[1372]117
118If shared library is enabled (default), libtool creates wrapper
[1638]119scripts in directory test/ that call the test programs located in
120directory test/.libs/. While this allows us to dynamically link against
121the temporary library in yat/, it makes straightforward usage of GDB
[1372]122impossible. For that reason libtool provides a wrapper:
123
124`#> libtool --mode=execute gdb foo_test`
125
126that sets the necessary environment variables. For more detailed
127discussion, please refer to the libtool manual:
128
129http://www.gnu.org/software/libtool/manual/libtool.html#Debugging-executables
130
[1674]131== Enable svn-support ==
[1372]132
[1673]133If you are building from an svn wc, you may run '`configure`' with
134option '`--enable-svn-support`' to turn on some extra make
135targets. Most of the targets are useful at release time, i.e.,
136probably not very useful for other developers than the release
[1674]137manager. See [source:trunk/build_support/svn_support.am build_support/svn_support.am] for more details.
[1558]138
[1674]139= Versioning =
140
141We use a softened version of [http://apr.apache.org/versioning.html APR guidelines] which
142in short implies
143
144''"The basic intent is that '''`MAJOR`''' versions are incompatible,
145large-scale upgrades of the API. '''`MINOR`''' versions retain compatibility with older minor versions, and changes in the
146'''`PATCH`''' level are perfectly compatible, forwards and backwards."''
147
148== '''`MAJOR`''' Releases ==
149
150No compatibility is guaranteed between '''`MAJOR`''' versions.
151
152== '''`MINOR`''' Releases ==
153
154'''`MINOR`''' versions should be compatible with earlier minor
155versions. However, in the `0.x` line we may allow exceptions to this
156rule, if developers agree the gain of change is sufficient. Binary compatibility is typically not guaranteed between '''`MINOR`''' versions. The `YAT_LT_VERSION` in [source:trunk/build_support/version.m4 version.m4] should reflect which versions are binary compatible.
157 
158== '''`PATCH`''' Releases ==
159
160Versions with same '''`MAJOR.MINOR`''' are perfectly compatible,
161forwards and backwards.
162 
163This implies that only implementations can be modified in a `PATCH`
164release. You cannot change the API, not even add functions or
165classes because it will break forward compatibility for the previous
166`PATCH` version. A `PATCH` release is a pure bug fix release
167
168=== Backward Source Compatibility ===
169
170Backward Source Compatibility means that an application that could build
171against version `x.y` shall also build without error against
172`x.y+1`. An application that compiled against header files from
173previous `MINOR` version shall also compile without errors against the
174header files of the new version.
175
176Specifically this implies:
177  - Do not remove any public, protected, or free functions.
178  - If you modify a function, its signature must be compatible with
179    previous signature, e.g., new parameters with default values may
[1721]180    be added to signature.
[1674]181  - Do not remove any class or inheritance for a class.
182
183=== Backward Binary Compatibility ===
184
185Backward Binary Compatibility means that an application that has been
186compiled against version `x.y` can be linked against version
187`x.y+1`.
188
189Specifically this implies:
190
191  - Do not remove or modify any function (except private), not even
192    add a parameter with default value because it will make the
193    function incompatible with earlier header files.
194
195  - Do not add, remove, or modify member variables, because that will
196    change the allocated size of the class. Therefore, to allow
197    modifications of the internal representation, it is preferable to
198    hold member variable is a ''pimpl'' that is allocated privately.
199    http://developer.gnome.org/doc/guides/programming-guidelines/binary.html
200
201  - Do not add or change order among virtual functions because it will
202    change the layout of the virtual table.
203
204
205
206
[1262]207----------------------------------------------------------------------
208{{{
[1797]209Copyright (C) 2003 Jari Häkkinen, Peter Johansson
210Copyright (C) 2004 Jari Häkkinen
[2071]211Copyright (C) 2006, 2007, 2008, 2009 Jari Häkkinen, Peter Johansson
[1262]212
[1469]213This file is part of yat library, http://dev.thep.lu.se/yat
[1262]214
215The yat library is free software; you can redistribute it and/or
216modify it under the terms of the GNU General Public License as
[1486]217published by the Free Software Foundation; either version 3 of the
[1262]218License, or (at your option) any later version.
219
220The yat library is distributed in the hope that it will be useful, but
221WITHOUT ANY WARRANTY; without even the implied warranty of
222MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
223General Public License for more details.
224
225You should have received a copy of the GNU General Public License
[1487]226along with yat. If not, see <http://www.gnu.org/licenses/>.
[1262]227}}}
Note: See TracBrowser for help on using the repository browser.