source: trunk/README.developer @ 3481

Last change on this file since 3481 was 3481, checked in by Peter, 6 years ago

fix PP conditionals so code compiles against libbam

  • 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: 16.0 KB
RevLine 
[2]1$Id: README.developer 3481 2016-03-13 23:50:52Z 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
[3481]65`YAT_HAVE_LIBBAM` conditionals (or alternatively put code inside
66`#ifdef YAT_HAVE_SAMTOOL` preprocessor conditionals). To
67differatniuate between code that compiles against libhts and libbam,
68use `#ifdef YAT_HAVE_HTSLIB` (or `#ifndef`. In order to support
69multiple inclusion styles we do not include <bam.h> directly, but
70`#include <config_bam.h>` and `#include YAT_BAM_HEADER`. Similarly,
71for `<sam.h>` include `YAT_SAM_HEADER`. For more details on this,
72refer to `yat/omic/config_bam.h`.
[2943]73
[1674]74=== Doxygen ===
[2071]75We generate our documentation using [http://www.doxygen.org Doxygen]
76(version 1.5 or later). Doxygen allows several different styles. We
77try to use the following style as we have found this minimizes parsing
78problems:
[1674]79
80{{{
81/**
82   \brief My class
83
84   Some text documenting the class MyClass
85*/
86class MyClass
87}}}
88
[2711]89or similarly
[1674]90
91{{{
92/**
93   \brief magic function
94
95   Some text documenting my_function
96*/
97void my_function(void);
98}}}
99
[2071]100We use doxygen keywords preceded by `\` such as `\brief`,
101`\return`. All classes and functions have a brief description, which
102increases clarity on summary pages.
[1674]103
[2071]104Try to keep comment line lengths within the terminal character limit,
105in other words, less than 80 characters per line. This makes the
106comments more readable.
[1674]107
108'''Internal Interface'''
109
[3188]110Helper functions and classes that are not part of yat API should
111either be labeled with doxygen flag `\internal` or placed in
112sub-namespace `detail`. Functionality placed in namespace `detail`
113should be excluded from doxygen input using a pattern like this:
[1674]114
[3188]115/// \cond IGNORE_DOXYGEN
116namespace detail {
117
118<Some very detailed code here>
119
120}
121/// \endcode
122
[1674]123= Build =
124
125== Requirements ==
126
[2404]127To build from a subversion checkout, you will need GNU Autotools. More
[2711]128specifically
[2404]129 * Automake 1.11 (or later), http://www.gnu.org/software/automake/
[3367]130 * Autoconf 2.64 (or later), http://www.gnu.org/software/autoconf/
[2404]131 * Libtool 1.5 (or later), http://www.gnu.org/software/libtool/
[1605]132
[1674]133== Disable shared library ==
[573]134
[2404]135yat uses GNU Libtool in order to build shared libraries on a variety
[1368]136of systems.  While this is very nice for making usable binaries, it
137can be a pain when trying to debug a program. For that reason,
138compilation of shared libraries can be turned off by specifying the
139`--disable-shared` option to configure.
140
[1674]141== Debugging using GDB ==
[1372]142
[2404]143If shared library is enabled (default), Libtool creates wrapper
144scripts in directory `test/` that call the test programs located in
145directory `test/.libs/`. While this allows us to dynamically link against
146the temporary library in `yat/`, it makes straightforward usage of GDB
[1372]147impossible. For that reason libtool provides a wrapper:
148
149`#> libtool --mode=execute gdb foo_test`
150
151that sets the necessary environment variables. For more detailed
152discussion, please refer to the libtool manual:
153
154http://www.gnu.org/software/libtool/manual/libtool.html#Debugging-executables
155
[3144]156
[3423]157== Avoid compiler warnings from hts.h ==
158
159When compiling with GCC in C++98 mode with -pedantic (as is
160recommended under development) the file 'htslib/hts.h' will cause
161warnings if it's not installed as system header. You can avoid this
162warning by replacing CPPFLAGS=-I/path/to/htslib with
163CPPFLAGS="-isystem /path/to/htslib".
164
[3144]165= Release Procedure =
166
167These instructions cover how to release minor and patch releases in a
168project that uses trac/subversion for revision control and project
169management. How to release major releases is not covered yet since we
170have not done that (with the exception of the first release). Release
171numbering follows the normal convention of major.minor.patch and the
172APR (see http://apr.apache.org/versioning.html) guidelines for
173releases are used.
174
175The main development is performed in the trunk branch of the
176repository. A new release branch is created for each minor release
177from the trunk and patch releases are snapshots of the minor release
178branch. This implies that patch work is performed in the minor release
179branch, and changes made release branch is transferred to the trunk
180every time a new patch release is made. Remember, patch work should be
181limited to bug fixes and important fixes only leaving development of
182new features and designs to the trunk branch.
183
184Releases should only be performed by an appointed member of the team,
185the Release Manager.
186
187
188=== Creating a release branch ===
189
190Once people agree that a new release branch should be made, the
191Release Manager creates it with the following procedure
192(substitute A.B with the version you are preparing, e.g. 0.3)
193
194 1. Check that 'YAT_LT_VERSION_INFO' is set correcly
195    otherwise update following line in 'm4/version.m4'
196
1978<----
198    m4_define([YAT_LT_VERSION_INFO], [c:r:a])
1998<----
200
201 2. Add a line in NEWS
2028<----
203     See the end for copyrights and conditions.
204
205    +yat A.B.x series from http://dev.thep.lu.se/yat/svn/branches/A.B-stable
206    +
207     Version A.B (released NOT YET)
2088<----
209
210 3. Commit the changes with
211
212    #> svn ci -m "Prepare A.B-stable branch"
213
214 4. For this step svncopyright is needed, http://dev.thep.lu.se/svndigest.
215    Update copyright statements with command:
216
217    #> make copyright
218
219    Examine the updates and commit changes with
220
221    #> svn ci -m "updating copyright statements"`.
222
223 5. Create a new stable branch with
224
225    #> make svn-stable-branch
226
227 6. Prepare the trunk for the next minor release
228
229   a) Update version number in 'm4/version.m4'. Locate and change the
230      below lines
231
2328<----
233      MY_VERSION_early([A], [B+1], [0], [true])
234      m4_define([YAT_LT_VERSION_INFO], [c+1:0:0])
2358<----
236
237   b) Add an entry in `NEWS`
238
2398<----
240      version A.[B+1] (released NOT YET)
2418<----
242
243      The date is set when version A.[B+1] is released. [[br]][[br]]
244
245   c) Commit changes to the repository:
246
247    #> svn ci -m "Bumping VERSION to A.[B+1]pre"
248
249 7. When someone with access to documentation site has time available,
250    they will upgrade to the new branch. This person is usually not the
251    release manager, so please send a reminder.
252
253=== Rolling a minor release ===
254
255    These instructions describe how to make a release. Replace A.B.C
256    with current VERSION (A.B if this is not a patch release).
257
258 1. Update version number in 'm4/version.m4'. Locate and change the
259    below line
260
2618<----
262      MY_VERSION_early([A], [B], [C], [false])
2638<----
264
265
266 2. Update the interface version number in 'm4/version.m4'. Locate and
267    set the version in the below line
268
2698<----
270      m4_define([YAT_LT_VERSION_INFO], [c:r:a])
2718<----
272
273    appropriately. Refer to file 'm4/version.m4' for details on how to
274    decide triplet 'c:r:a'.
275
276
277 3. Set the date for the new release in 'NEWS'.
278
2798<----
280      version A.B.C (released 26 June 2007)
2818<----
282
283
284 4. Make sure that the items in 'NEWS' cover the new features of the
285    release.
286
287
288 5. Commit changes to the repository:
289
290    #> svn ci -m "Preparing release A.B.C"
291
292
293 6. For this step svncopyright is needed, http://dev.thep.lu.se/svndigest.
294    Update copyright statements with command:
295
296    #> make copyright
297
298    Examine the updates and commit changes with
299
300    #> svn ci -m "updating copyright statements"
301
302
303 7. Now it's time to create a tarball, an svn tag, and upload the
304    tarball to sourceforge. For this to work you need to hold write
305    permissions at libyat project page at sourceforge. If your sf user
306    id is different from the one defined in 'Makefile.am', you can
307    override the default with 'sf_user=<your id>'. Issue the
308    convenience target:
309
[3248]310    #> make release-tag-upload sf_user=<sourceforge user id>
[3144]311
312    This will run some sanity checks, run maintainer-check and
313    distcheck, create an svn tag, and upload the newly created tarball
314    to sourceforge. The last step requires that you provide your SF password.
315
316
317 8. On WikiStart update links
318    '[source:tags/A.B.C/NEWS NEWS]' and
319    '[source:branches/A.B-stable/README README]'
320
321 9. Update SubversionCheckout
322
323   a) In section 'yat latest release' update command to
324      'svn checkout http://dev.thep.lu.se/yat/svn/tags/A.B.C yat-A.B.C
325      and link to
326      '[source:tags/A.B.C/NEWS NEWS]'
327      If this is a patch release jump to point 10).
328
329   b) In section 'yat stable' update command to
330      'svn checkout http://dev.thep.lu.se/yat/svn/branches/A.B-stable yat-A.B.x
331      and link to
332      '[source:branches/A.B-stable/NEWS NEWS]'
333
334
335 10. Close the milestone associated with this release.
336
337
338 11. Update the version list in Trac using the trac-admin tool.
339
340
341 12. Use file 'announcement.txt' as template and send email to
342    libyat-users@lists.sourceforge.net
343
344
345 13. Merge the release into the trunk.
346
347    a) Go to a pristine trunk WC:
348
349       #> cd /path/to/yat-trunk/
350       #> make check-svn-diff
351
352    b) Merge changes into trunk:
353
354       #> svn merge ^/branches/A.B-stable
355
356    c) Resolve potential conflicts. Run tests and perform all other
357       appropriate tests to make sure that the merge does not create
358       havoc. Typically changes in `m4/version.m4` are problematic so
359       check this file extra carefully.
360
361    d) Commit changes to the trunk branch.
362
363       #> svn commit -m "Merged release A.B.C into trunk."
364
365
366 14. Prepare the stable branch for the next patch release.
367
368    a) Update version number in 'm4/version.m4'. Locate and change the
369       below line
370
3718<---
372       MY_VERSION_early([A], [B], [C+1], [true])
3738<---
374
375       Run 'make all' and while waiting finalize item b) below
376
377    b) Add an entry in 'NEWS'
378
3798<----
380       version A.B.[C+1] (released NOT YET)
3818<----
382
383       The date is set when version A.B.[C+1] is released.
384
385
386 15. Commit changes to the repository:
387
388    #> svn ci -m "Bumping VERSION to A.B.[C+1]pre"
389
390
[1674]391= Versioning =
392
[2711]393We use a softened version of
[2404]394[http://apr.apache.org/versioning.html APR guidelines] which in short implies
[1674]395
396''"The basic intent is that '''`MAJOR`''' versions are incompatible,
[2404]397large-scale upgrades of the API. '''`MINOR`''' versions retain
398compatibility with older minor versions, and changes in the
399'''`PATCH`''' level are perfectly compatible, forwards and
400backwards."''
[1674]401
[2711]402== '''`MAJOR`''' Releases ==
[1674]403
404No compatibility is guaranteed between '''`MAJOR`''' versions.
405
406== '''`MINOR`''' Releases ==
407
408'''`MINOR`''' versions should be compatible with earlier minor
409versions. However, in the `0.x` line we may allow exceptions to this
[2711]410rule, 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.
411
[1674]412== '''`PATCH`''' Releases ==
413
414Versions with same '''`MAJOR.MINOR`''' are perfectly compatible,
415forwards and backwards.
[2711]416
[1674]417This implies that only implementations can be modified in a `PATCH`
418release. You cannot change the API, not even add functions or
419classes because it will break forward compatibility for the previous
420`PATCH` version. A `PATCH` release is a pure bug fix release
421
422=== Backward Source Compatibility ===
423
424Backward Source Compatibility means that an application that could build
425against version `x.y` shall also build without error against
426`x.y+1`. An application that compiled against header files from
427previous `MINOR` version shall also compile without errors against the
428header files of the new version.
429
430Specifically this implies:
431  - Do not remove any public, protected, or free functions.
432  - If you modify a function, its signature must be compatible with
433    previous signature, e.g., new parameters with default values may
[1721]434    be added to signature.
[1674]435  - Do not remove any class or inheritance for a class.
436
437=== Backward Binary Compatibility ===
438
439Backward Binary Compatibility means that an application that has been
440compiled against version `x.y` can be linked against version
[2711]441`x.y+1`.
[1674]442
443Specifically this implies:
444
445  - Do not remove or modify any function (except private), not even
446    add a parameter with default value because it will make the
447    function incompatible with earlier header files.
448
449  - Do not add, remove, or modify member variables, because that will
450    change the allocated size of the class. Therefore, to allow
451    modifications of the internal representation, it is preferable to
452    hold member variable is a ''pimpl'' that is allocated privately.
453    http://developer.gnome.org/doc/guides/programming-guidelines/binary.html
454
455  - Do not add or change order among virtual functions because it will
456    change the layout of the virtual table.
457
458
459
460
[1262]461----------------------------------------------------------------------
462{{{
[2119]463Copyright (C) 2003 Jari Häkkinen, Peter Johansson
464Copyright (C) 2004 Jari Häkkinen
465Copyright (C) 2006, 2007, 2008, 2009 Jari Häkkinen, Peter Johansson
[3417]466Copyright (C) 2010, 2011, 2012, 2013, 2014, 2015 Peter Johansson
[1262]467
[1469]468This file is part of yat library, http://dev.thep.lu.se/yat
[1262]469
470The yat library is free software; you can redistribute it and/or
471modify it under the terms of the GNU General Public License as
[1486]472published by the Free Software Foundation; either version 3 of the
[1262]473License, or (at your option) any later version.
474
475The yat library is distributed in the hope that it will be useful, but
476WITHOUT ANY WARRANTY; without even the implied warranty of
477MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
478General Public License for more details.
479
480You should have received a copy of the GNU General Public License
[1487]481along with yat. If not, see <http://www.gnu.org/licenses/>.
[1262]482}}}
Note: See TracBrowser for help on using the repository browser.