Re: Framework for filtering?

[Brian Gough <bjg at network-theory dot co dot uk>]

Brian Gough writes:
 > I've been thinking about the general problem of additions/extensions
 > to GSL as it is not feasible for me to review them to the standard I
 > would like.  For future extensions I think we have to adopt a package
 > approach, similar to Perl CPAN, etc. I'm writing a new section for the
 > design document about it, with an example package that can be used as
 > a template.

This is what I am adding to gsl-design.texi:

-- 
Brian Gough


Contributing
************

This design document was originally written in 1996.  As of 2004, GSL
itself is essentially feature complete, the developers are not actively
working on any major new functionality.

   The main emphasis is now on ensuring the stability of the existing
functions, improving consistency, tidying up a few problem areas and
fixing any bugs that are reported.  Adding large amounts of new code is
difficult because it leads to differences in the maturity of different
parts of the library.

   To maintain stability, any new functionality is encouraged as
"packages", built on top of GSL and maintained independently by the
author, as in other free software projects (such as the Perl CPAN
archive and TeX CTAN archive, etc).

Packages
========

The design of GSL permits extensions to be used alongside the existing
library easily by simple linking.  For example, additional random number
generators can be provided in a separate library:

     $ tar xvfz rngextra-0.1.tar.gz
     $ cd rngextra-0.1
     $ ./configure; make; make check; make install
     $ ...
     $ gcc -Wall main.c -lrngextra -lgsl -lgslcblas -lm

   The points below summarise the package design guidelines.  These are
intended to ensure that packages are consistent with GSL itself, to make
life easier for the end-user and make it possible to distribute popular
well-tested packages as part of the core GSL in future.

   * Follow the GSL and GNU coding standards described in this document

     This means using the standard GNU packaging tools, such as
     Automake, providing documentation in Texinfo format, and a test
     suite.  The test suite should run using `make check', and use the
     test functions provided in GSL to produce the output with
     `PASS:'/`FAIL:' lines.  It is not essential to use libtool since
     packages are likely to be small, a static library is sufficient
     and simpler to build.

   * Use a new unique prefix for the package (do not use `gsl_' - this
     is reserved for internal use).

     For example, a package of additional random number generators
     might use the prefix `rngextra'.

          #include <rngextra.h>
          
          gsl_rng * r = gsl_rng_alloc (rngextra_lsfr32);

   * Use a meaningful version number which reflects the state of
     development

     Generally, `0.x' are alpha versions, which provide no guarantees.
     Following that, `0.9.x' are beta versions, which should be
     essentially complete, subject only to minor changes and bug fixes.
     The first major release is `1.0'.  Any version number of `1.0' or
     higher should be suitable for production use with a well-defined
     API.

     The API must not change in a major release and should be
     backwards-compatible in its behavior (excluding actual bug-fixes),
     so that existing code do not have to be modified.  Note that the
     API includes all exported definitions, including data-structures
     defined with `struct'.  If you need to change the API in a
     package, it requires a new major release (e.g. `2.0').

   * Use the GNU General Public License (GPL)

     Follow the normal procedures of obtaining a copyright disclaimer
     if you would like to have the package considered for inclusion in
     GSL itself in the future (*note Legal issues::).

   Post announcements of your package releases to
<gsl-discuss@sources.redhat.com> so that information about them can be
added to the GSL webpages.

   An example package `rngextra' containing two additional random
number generators can be found at
<http://www.network-theory.co.uk/network-theory.co.uk/download/rngextra/>.