source: trunk/README.developer @ 3114

Last change on this file since 3114 was 3114, checked in by Peter, 8 years ago

update copyright years

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