README-developer

This document describes the organization of TEOS-10/GSW-C on github, and
gives instructions for contributors.

Files for users
===============

README                  -- The README file distributed with the
                            teos-10.org distribution.
LICENSE                 -- GSW C software license.
Makefile                -- Simple default makefile for building the library and
                            test runner program, gsw_check.
gswteos-10.h            -- GSW function prototype definitions
gsw_internal_const.h    -- Common parameters used to compile the GSW-C
                            library.
gsw_oceanographic_toolbox.c
                        -- The distribution source code for the GSW-C
                            library less gsw_saar.
gsw_saar.c              -- gsw_saar and gsw_deltasa_atlas (modified).
gsw_saar_data.h         -- static global absolute salinity anomaly data
                            used by gsw_saar.c
gsw_check_data.h        -- static check data used by gsw_check_functions.c
gsw_check_functions.c   -- C implementation of the check functions used
                            to validate the correct building of the GSW-C
                            Oceanographic Toolbox.
TOOLS.ini               -- Variable definitions used by nmake
TOOLS.gcc               -- Variable definitions used by make
meson.build             -- Meson build file (alternative build system to build
                            libgswteos-10 library and gsw_check tests)
meson.options           -- Meson build options file (defines additional options
                            for the Meson build system)

Files for development
=====================

README-developer        -- This file.
make_data_from_mat.py   -- Utility to generate check data and SAAR data from
                            the gsw_data_v3_0.mat targeted by this release,
                            presently v3_06_16.
                            You need to edit the file to supply the correct
                            path to the matfile for your directory structure.
geo_strf_dyn_height.npy -- Geostrophic streamfunction test values used by
                            make_data_from_mat.py to match the pchip-based
                            interpolation used here; for the geostrophic
                            streamfunction we do not try to exactly match the
                            Matlab version.
gsw_check_data.nc       -- Netcdf version of the information in
                            gsw_check_data.h.  The file is written by
                            make_data_from_mat.py.  It is intended for use by
                            GSW-Julia, and possibly others.
gsw_data_ncdump.txt     -- Edited text from the "ncdump -h" of a netcdf file
                            that was originally generated by Paul Barker from
                            an earlier version of gsw_data_v3_0.mat.  It is
                            used by make_data_from_mat.py to find the array
                            dimensions when generating gsw_check_data.nc.
meson.options           -- Meson build options file. Use this to define more
                            options for the Meson build system. (e.g. force-cpp)

Notes for contributors
======================

It is anticipated that the primary use for this C library will be
to provide core functionality in the GSW-Python, GSW-R, and GSW-Julia
libraries.

If additional core GSW functions are added here, they should be consistent
with their GSW-Matlab versions and with the general style of functions
presently in the C library.  Pull Requests for new functions should
include the corresponding tests in gsw_check_functions.c and test data in
gsw_check_data.h.  The latter should be the result of re-running the
make_data_from_mat utility; gsw_check_data.h should not be hand-edited.

Code style for C should be generally consistent with the existing code
with respect to brackets and indentation, with the proviso that new
code should use 4-space indentation.  There should be no trailing
whitespace, and no tab characters.

Originally, gsw_oceanographic_toolbox.c was assembled by a script from
individual files for each exported function, and the files were sorted
alphabetically.  When adding new exported functions, please insert them
alphabetically so as to maintain this (arbitrary) convention.  Support
functions, declared as "static", should be kept together with the
exported functions in which they are used, so they typically will not
be in alphabetic order.