source: branches/0.13-stable/README.developer @ 3437

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

mention how to avoid compiler warning from htslib

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