=========================
SUNDIALS Developer README
=========================

This document is broken into three primary sections:

1. New development checklist, covering a minimal set of tasks that
   should be performed when adding new functionality to SUNDIALS.

2. Description of the SUNDIALS shared library version numbering
   scheme, including instructions on how to enforce this numbering
   system using either Libtool or CMake.

3. Table containing the SUNDIALS library version history, which maps
   between the release numbers of each individual library, the main
   SUNDIALS library release number, and the associated shared library
   number (see item 2).




1. New development checklist
============================

When adding new functionality to SUNDIALS, in the form of bugfixes,
new solvers, new solver options, new test problems, or modifications
to the SUNDIALS build system, developers should adhere to the
following checklist.

a. When adding new source code files, ensure that the corresponding 
   CMakeLists.txt file(s) is/are updated to include your file(s).  If 
   your files depend on external libraries, emulate the
   Latex/KLU/SuperLU_MT CMake options to ensure that these files are
   only included when SUNDIALS is configured to use that library.

b. Configure SUNDIALS using the C flags "-Wall -ansi -pedantic", to
   aid in catching compatibility issues on other platforms (Windows). 
   When building, modify your file to remove any error/warning
   messages output during compilation of your code.

c. Configure your build with a maximal set of configuration options
   enabled (shared libraries, OpenMP, Pthreads, MPI, Lapack, KLU or
   SuperLU_MT, FCMIX).  Run "make", "make test" and "make install" to 
   ensure that everything functions smoothly.

d. Configure your build with a minimal set of configuration options
   enabled (serial, C).  Run "make", "make test" and "make install" to 
   ensure that everything functions smoothly, even when no external
   libraries are supplied.

e. When implementing a bug-fix to an existing solver:
   * If this change affects the user interface, update the solver
     documentation to describe the updated interface.
   * For any problems that now fail when running "make test", verify
     that the bugfix either made only cosmetic changes or improved the 
     results, and copy the updated test output into the examples/ and
     test/answers/ directories (see item g. below).

f. When adding new solvers or new solver options:
   * Update the documentation to include descriptions of your work.
     Ensure that the documentation also compiles ("make ug_pdf" in the
     relevant directory).
   * Add a new example problem (or multiple problems) to the examples/
     directory to demonstrate how to use your solver/option, and to
     include in SUNDIALS' automated nightly tests.
   * Update the solver-specific README file, in src/<solver>/, to
     describe the new feature.
   * For any problems that now fail when running "make test", verify
     that your updates either made only cosmetic changes or improved
     the results, and copy the updated test output into the examples/
     and test/answers/ directories (see item g. below).

g. When adding new test or example problems to the examples/ directory:
   * Ensure that your new file has a unique name,
   * After running "make install", change to the installed examples/
     directory and ensure that "make" succeeds, since the
     CMake-generated Makefile system differs from how the examples are
     built within SUNDIALS.
   * Ensure that the reference output is included, e.g. if a file foo.c
     is added, also add foo.out. 
   * Copy this same output file, without the ".out" extension, to the
     test/answers/ directory. 
   * Update the example problem documentation for that solver to
     include a description of the new problem.

h. When adding any new files, update the corresponding solver script in
   the scripts/ directory to include your file(s) within the
   distribution. 




2. Conventions on shared library versioning
===========================================

A complete name is libfoo.so.x.y.z where the VERSION x.y.z represents 
x = major
y = minor
z = revision

The build system is responsible for creating the following symlinks:
libfoo.so   -> libfoo.so.x.y.z
libfoo.so.x -> libfoo.so.x.y.z

LIBTOOL versioning system
-------------------------

Specify the version information to libtool using the `-version-info' flag during link mode.
This flag accepts an argument of the form `current[:revision[:age]]'.
So, passing `-version-info 3:12:1' sets current to 3, revision to 12, and age to 1.
If either revision or age are omitted, they default to 0. 
Also note that age must be less than or equal to the current interface number.

Therefore, the rules for updating libtool's 'c:r:a' versioning are:

 1.Start with version information of `0:0:0' for each libtool library.
 2.Update the version information only immediately before a public release of your software. 
   More frequent updates are unnecessary, and only guarantee that the current interface 
   number gets larger faster.
 3.If the library source code has changed at all since the last update, then increment revision
   (`c:r:a' becomes `c:r+1:a').
 4.If any interfaces have been added, removed, or changed since the last update, 
   increment current, and set revision to 0.
 5.If any interfaces have been added since the last public release, then increment age.
 6.If any interfaces have been removed since the last public release, then set age to 0. 

The SONAME of the resulting library will satisfy:

x = c-a
y = a
z = r

Examples of version updates:

- a bug was fixed:          c:r:a -> c:r+1:a    and therefore x.y.z -> x.y.z+1
- an interface was added:   c:r:a -> c+1:0:a+1  and therefore x.y.z -> x.y+1.0
- an interface was removed: c:r:a -> c+1:0:0    and therefore x.y.z -> x+y+1.0.0

Sample version history (on linux):

        Files                           SONAME       POSSIBLE CHANGE

0:0:0   lib.so lib.so.0 lib.so.0.0.0    lib.so.0     initial 
0:1:0   lib.so lib.so.0 lib.so.0.0.1    lib.so.0     bug fix
1:0:1   lib.so lib.so.0 lib.so.0.1.0    lib.so.0     add interface
1:1:1   lib.so lib.so.0 lib.so.0.1.1    lib.so.0     bug fix
2:0:0   lib.so lib.so.2 lib.so.2.0.0    lib.so.2     remove interface

CMAKE versioning system
-----------------------

The version information is specified by setting the VERSION and SOVERSION properties
to the library target:

ADD_LIBRARY(foo file1.c file2.c)
SET_TARGET_PROPERTIES(foo PROPERTIES VERSION x.y.z SOVERSION x)

Note that we force SOVERSION to be the same as the major number for compatibility with
the libtool versioning scheme (at least under Linux)




3. SUNDIALS version history
===========================

Note: there was no library versioning before sundials-2.2.0


ARKODE
RELEASE   SUNDIALS RELEASE    LIBTOOL VER.    LIB FILE (Linux)  
1.0.0     2.6.0               2:0:0           2.0.0
2.0.0     3.0.0               3:0:0           3.0.0
2.1.0     3.1.0               3:0:0           3.0.0               
2.1.1     3.1.1               3:0:0           3.0.0
2.1.2     3.1.2               3:0:0           3.0.0
2.2.0     3.2.0               3:0:0           3.0.0
2.2.1     3.2.1               3:0:0           3.0.0
3.0.0     4.0.0               4:0:0           4.0.0
3.0.1     4.0.1               4:0:1           4.0.1
3.0.2     3.0.2               3:0:2           3.0.2
3.1.0     4.1.0               4:1:0           4.1.0

CVODE
RELEASE   SUNDIALS RELEASE    LIBTOOL VER.    LIB FILE (Linux)  
2.4.0     2.2.0               0:0:0           0.0.0
2.5.0     2.3.0               0:1:0           0.0.1
2.6.0     2.4.0               1:0:0           1.0.0
3.0.0     3.0.0               2:0:0           2.0.0
3.1.0     3.1.0               2:0:0           2.0.0
3.1.1     3.1.1               2:0:0           2.0.0
3.1.2     3.1.2               3:0:0           3.0.0
3.2.0     3.2.0               3:0:0           3.0.0
3.2.1     3.2.1               3:0:0           3.0.0
4.0.0     4.0.0               4:0:0           4.0.0
4.0.1     4.0.1               4:0:1           4.0.1
4.0.2     4.0.2               4:0:2           4.0.2
4.1.0     4.1.0               4:1:0           4.1.0

CVODES
RELEASE   SUNDIALS RELEASE    LIBTOOL VER.    LIB FILE (Linux)  
2.4.0     2.2.0               0:0:0           0.0.0
2.5.0     2.3.0               1:0:0           1.0.0
2.6.0     2.4.0               2:0:0           2.0.0
3.0.0     3.0.0               3:0:0           3.0.0
3.1.0     3.1.0               3:0:0           3.0.0
3.1.1     3.1.1               3:0:0           3.0.0
3.1.2     3.1.2               3:0:0           3.0.0
3.2.0     3.2.0               3:0:0           3.0.0
3.2.1     3.2.1               3:0:0           3.0.0
4.0.0     4.0.0               4:0:0           4.0.0
4.0.1     4.0.1               4:0:1           4.0.1
4.0.2     4.0.2               4:0:2           4.0.2
4.1.0     4.1.0               4:1:0           4.1.0

IDA
RELEASE   SUNDIALS RELEASE    LIBTOOL VER.    LIB FILE (Linux)  
2.4.0     2.2.0               0:0:0           0.0.0
2.5.0     2.3.0               1:0:0           1.0.0
2.6.0     2.4.0               2:0:0           2.0.0
3.0.0     3.0.0               3:0:0           3.0.0
3.1.0     3.1.0               3:0:0           3.0.0
3.1.1     3.1.1               3:0:0           3.0.0
3.1.2     3.1.2               3:0:0           3.0.0
3.2.0     3.2.0               3:0:0           3.0.0
3.2.1     3.2.1               3:0:0           3.0.0
4.0.0     4.0.0               4:0:0           4.0.0
4.0.1     4.0.1               4:0:1           4.0.1
4.0.2     4.0.2               4:0:2           4.0.2
4.1.0     4.1.0               4:1:0           4.1.0

IDAS
RELEASE   SUNDIALS RELEASE    LIBTOOL VER.    LIB FILE (Linux)  
1.0.0     2.4.0               0:0:0           0.0.0
2.0.0     3.0.0               2:0:0           2:0:0
2.1.0     3.1.0               3:0:0           3.0.0
2.1.1     3.1.1               3:0:0           3.0.0
2.1.2     3.1.2               3:0:0           3.0.0
2.2.0     3.2.0               3:0:0           3.0.0
2.2.1     3.2.1               3:0:0           3.0.0
3.0.0     4.0.0               4:0:0           4.0.0
3.0.1     4.0.1               4:0:1           4.0.1
3.0.2     4.0.2               4:0:2           4.0.2
3.1.0     4.1.0               4:1:0           4.1.0

KINSOL
RELEASE   SUNDIALS RELEASE    LIBTOOL VER.    LIB FILE (Linux)  
2.4.0     2.2.0               0:0:0           0.0.0
2.5.0     2.3.0               0:1:0           0.0.1
2.6.0     2.4.0               1:0:0           1.0.0
3.0.0     3.0.0               3:0:0           3.0.0
3.1.0     3.1.0               3:0:0           3.0.0
3.1.1     3.1.1               3:0:0           3.0.0
3.1.2     3.1.2               3:0:0           3.0.0
3.2.0     3.2.0               3:0:0           3.0.0
3.2.1     3.2.1               3:0:0           3.0.0
4.0.0     4.0.0               4:0:0           4.0.0
4.0.1     4.0.1               4:0:1           4.0.1
4.0.2     4.0.2               4:0:2           4.0.2
4.1.0     4.1.0               4:1:0           4.1.0
