source: trunk/README.developer @ 1706

Last change on this file since 1706 was 1686, checked in by Peter, 13 years ago

bumping AC_PREREQ to 2.61 - some macros used have AC_PREREQ([2.61])

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