[gnuastro-commits] master acd4ca52 2/2: Make (version-is): new function to help in reproducibility

[Mohammad Akhlaghi]

branch: master
commit acd4ca5247daa4751ec13e0e0e45309bc3d41588
Author: Mohammad Akhlaghi <mohammad@akhlaghi.org>
Commit: Mohammad Akhlaghi <mohammad@akhlaghi.org>

    Make (version-is): new function to help in reproducibility
    
    Until now, to check the version of the running Gnuastro in a Makefile (to
    ensure reproducibility), it was necessary to run a program with the
    '--version' function and extract the version string from that using Make's
    '$(shell ...)' function. This was dirty and slow.
    
    With this commit, a new Gnuastro Make extension function has been added for
    this purpose: '$(ast-version-is STRING)'. This enables easy checking of the
    version string in a Makefile, as demonstrated in the minimal working
    example of the manual.
---
 NEWS              |  4 ++++
 doc/gnuastro.texi | 25 +++++++++++++++++++++++++
 lib/makeplugin.c  | 50 ++++++++++++++++++++++++++++++++++++++++++++++++--
 3 files changed, 77 insertions(+), 2 deletions(-)

diff --git a/NEWS b/NEWS
index f08eaac7..8d687764 100644
--- a/NEWS
+++ b/NEWS
@@ -99,6 +99,10 @@ See the end of the file for license conditions.
     analysis becomes even more easier and faster. In the following, you can
     see the first set of such functions (they all begin with 'ast-'). For
     more, see the newly added chapter in the Gnuastro manual.
+    - ast-version-is: will return '1' if the running Gnuastro has the given
+      version (argument of this function). This can be used to ensure
+      reproducibility in combination with Make's conditional features, see
+      the minimal working example in the manual.
     - ast-text-contains: will return space-separated words within a larger
       list that contain a certain string. The to-contain string can be
       anywhere within the words of the larger list.
diff --git a/doc/gnuastro.texi b/doc/gnuastro.texi
index e9aa2475..d2aabef0 100644
--- a/doc/gnuastro.texi
+++ b/doc/gnuastro.texi
@@ -28008,6 +28008,31 @@ For more, see the 
@url{https://www.gnu.org/software/make/manual/html_node/Flavor
 @end cartouche
 
 @table @code
+@item $(ast-version-is STRING)
+@cindex Reproducibility
+Returns @code{1} if the version of the used Gnuastro is equal to 
@code{STRING}, and @code{0} otherwise.
+This is useful/critical for obtaining reproducible results on different 
systems.
+It can be used in combination with 
@url{https://www.gnu.org/software/make/manual/html_node/Conditionals.html, 
Conditionals in Make} to ensure the required version of Gnuastro is going to be 
used in your workflow.
+
+For example, in the minimal working Makefile below, we are using it to specify 
if the default (first) target (@code{all}) should have any prerequisites (and 
let the workflow start), or if it should simply print a message (that the 
required version of Gnuastro isn't installed) and abort (without any 
prerequisites).
+
+@example
+load /usr/local/lib/libgnuastro_make.so
+
+gnuastro-version = 0.19
+ifeq ($(ast-version-is $(gnuastro-version)),1)
+all: paper.pdf
+else
+all:; @@echo "Please use Gnuastro $(gnuastro-version)"
+endif
+
+result.fits: input.fits
+        astnoisechisel $< --output=$@
+
+paper.pdf: result.fits
+        pdflatex --halt-on-error paper.tex
+@end example
+
 @item $(ast-text-contains STRING, TEXT)
 Returns all whitespace-separated words in @code{TEXT} that contain the 
@code{STRING}, removing any words that @emph{do not} match.
 For example, the following minimal Makefile will only print the @code{bAaz 
Aah} word of the list.
diff --git a/lib/makeplugin.c b/lib/makeplugin.c
index 3a3e7763..6d90f9a9 100644
--- a/lib/makeplugin.c
+++ b/lib/makeplugin.c
@@ -48,6 +48,7 @@ int plugin_is_GPL_compatible=1;
 
 /* Names of the separate functions */
 #define MAKEPLUGIN_FUNC_PREFIX "ast"
+static char *version_is_name=MAKEPLUGIN_FUNC_PREFIX"-version-is";
 static char *text_contains_name=MAKEPLUGIN_FUNC_PREFIX"-text-contains";
 static char *text_not_contains_name=MAKEPLUGIN_FUNC_PREFIX"-text-not-contains";
 static char 
*fits_with_keyvalue_name=MAKEPLUGIN_FUNC_PREFIX"-fits-with-keyvalue";
@@ -63,7 +64,48 @@ static char 
*fits_unique_keyvalues_name=MAKEPLUGIN_FUNC_PREFIX"-fits-unique-keyv
 
 
 /**********************************************************************/
-/***************             Text utilities             ***************/
+/***************          Configuration function        ***************/
+/**********************************************************************/
+static char *
+makeplugin_version_is(const char *caller, unsigned int argc, char **argv)
+{
+  int check=0;
+  char *out=NULL;
+  char *version=gal_txt_trim_space(argv[0]);
+
+  /* If the version matches, set the value of 'check'. */
+  if( version && !strcmp(PACKAGE_VERSION, version) ) check=1;
+
+  /* Write the value into the 'out' pointer.*/
+  if( asprintf(&out, "%d", check)<0 )
+    error(EXIT_FAILURE, 0, "%s: couldn't allocate output string",
+          __func__);
+
+  /* Return the output string. */
+  return out;
+}
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+/**********************************************************************/
+/***************             Text functions             ***************/
 /**********************************************************************/
 
 /* Base function that is used for both the contains and not-contains
@@ -142,7 +184,7 @@ makeplugin_text_not_contains(const char *caller, unsigned 
int argc,
 
 
 /**********************************************************************/
-/***************             FITS utilities             ***************/
+/***************             FITS functions             ***************/
 /**********************************************************************/
 
 /* Select the input files that have the requested value(s) in the requested
@@ -253,6 +295,10 @@ makeplugin_fits_unique_keyvalues(const char *caller, 
unsigned int argc,
 int
 libgnuastro_make_gmk_setup()
 {
+  /* Return 1 if Gnuastro has the requested version. */
+  gmk_add_function(version_is_name, makeplugin_version_is,
+                   1, 1, GMK_FUNC_DEFAULT);
+
   /* Return the input strings that contain the given string. */
   gmk_add_function(text_contains_name, makeplugin_text_contains,
                    2, 2, GMK_FUNC_DEFAULT);