updating GSW R when GSW C changes

Assess your programming skill

Some familiarity with C will be required to do the work sketched below, and readers without such a background ought to find someone to help, before they try to update GSW-R.

For those still reading, the following notes might be helpful. Little more than a rough diary of notes made during the transition from GSW-R 1.0.5 to 1.0.6, these notes are almost certainly incomplete, and might also be incorrect. In particular, the notes do not address the severing of ties to the testthat R package, because that was relatively straightforward, and ought to be captured reasonably well with a git diff.

Set up repositories

Since GSW-R relies on C code in GSW-C and a netcdf file in GSW-Fortran, the first step is to clone those repositories. It makes sense to put all three repositories in the same directory, so that an R script in GSW-R will "know" where to find the netcdf file that GSW-Fortran provides.

Back up and copy C files

Copy the GSW-R/*.c and GSW-R/*.h files to some location that is outside the repository (so you can compare old and new versions). Then, copy the .c and .h files from GSW-C to GSW-R/src.

Edit src/gsw_saar.c

The steps below worked for the transition from GSW-R 1.0.5 to 1.0.6, and similar steps will likely be required for later changes, although it would be unwise for someone new to C to try these steps.

1. Near the start of GSW-R/src/gsw_saar.c, change

#include "gsw_saar_data.c"

#ifdef __cplusplus
#       define ISNAN(x) std::isnan(x)
#else
#       define ISNAN(x) isnan(x)
#endif

to the following

// {{{
// This block is needed for GSW-R, because CRAN policies
// mediate against storing large datasets in code.
int gsw_nx=0;
int gsw_ny=0;
int gsw_nz=0;
double *longs_ref=NULL;
double *lats_ref=NULL;
double *p_ref=NULL;
double *ndepth_ref=NULL;
double *saar_ref=NULL;
double *delta_sa_ref=NULL;
GSW_SAAR_DATA;
// }}}

2. Change several ISNAN() calls to isnan() calls.

3. In the 1.0-5 to 1.0-6 transition, some functions changed their argument counts, so there will be contradictions between function descriptions in the wrappers.c and gswteos-10.h files. This will be revealed by doing a test build at this stage. So, the next step is to analyse the code, both to rectify these problems and, very importantly, to change the documentation so that users will not be blind-sided by the change. In the 1.0-5 to 1.0-6 transition, the main change seems to be that both gsw_p_from_z() and gsw_z_from_p() gained two new parameters, named geo_strf_dyn_height and sea_surface_geopotential. This required changing R/gsw.R, src/wrappers.c to handle and document the new parameters, and also changing the NEWS file to highlight this change. This is a non-breaking change, in the sense that the defaults for these new parameters are zero, so the old test values still work.

Update data

Do this in developer/create_data. The makefile and readme file should be clear.

Build and test

Fix any errors.

Update docs

The main docs are created in Roxygen, so to alter them, edit R/gsw.R. Usually, no changes will be needed, except for functions that have changed. However, it is important to update man-roxygen/teos10template.R, which will always need to be changed if the GSW-C code is updated.