[gnuastro-commits] master e3e5f9f 3/3: Automatic linking script section added, array test

[Mohammad Akhlaghi]

branch: master
commit e3e5f9f902a74ec02b98c2809ae30a03114b43d5
Author: Mohammad Akhlaghi <address@hidden>
Commit: Mohammad Akhlaghi <address@hidden>

    Automatic linking script section added, array test
    
    The introductory text for libraries was further edited and a new "Automatic
    linking script" was added. This is a very convenient shell function that
    can be used for compiling and linking any program using Gnuastro
    functions. Maybe in the future, we can make it more general and install
    it. It will make it really easy to write C programs using Gnuastro and not
    having to worry about linking.
    
    As part of the explanations, the old `versionc.c' test was replaced with
    another one to be alittle more complicated: actually use some of the
    library functions. Since the version reporting is done with a macro, the
    `versionc' test wouldn't need any linking, which made it hard to use as a
    reference for explaining in the text.
---
 doc/gnuastro.texi      |  127 +++++++++++++++++++++++++++++++++++-------------
 tests/Makefile.am      |    4 +-
 tests/lib/arraymanip.c |   75 ++++++++++++++++++++++++++++
 tests/lib/versionc.c   |   36 --------------
 4 files changed, 169 insertions(+), 73 deletions(-)

diff --git a/doc/gnuastro.texi b/doc/gnuastro.texi
index 7ad1c9b..94462f0 100644
--- a/doc/gnuastro.texi
+++ b/doc/gnuastro.texi
@@ -503,6 +503,7 @@ Review of library fundamentals
 * Headers::                     Header files included in source.
 * Linking::                     Linking the compiled source files into one.
 * Summary and example on libraries::  A summary and example on using libraries.
+* Automatic linking script::    Shell function for automatic linking.
 
 Gnuastro library
 
@@ -14115,6 +14116,7 @@ problems.
 * Headers::                     Header files included in source.
 * Linking::                     Linking the compiled source files into one.
 * Summary and example on libraries::  A summary and example on using libraries.
+* Automatic linking script::    Shell function for automatic linking.
 @end menu
 
 @node Headers, Linking, Review of library fundamentals, Review of library 
fundamentals
@@ -14525,7 +14527,7 @@ the linker will complain and abort.
 
 
 
address@hidden Summary and example on libraries,  , Linking, Review of library 
fundamentals
address@hidden Summary and example on libraries, Automatic linking script, 
Linking, Review of library fundamentals
 @subsection Summary and example on libraries
 
 After the mostly abstract discussions of @ref{Headers} and @ref{Linking},
@@ -14559,49 +14561,105 @@ be linked to other executables (it has many entry 
points).
 @cindex GCC
 @cindex GNU Compiler Collection
 The GNU Compiler Collection (or GCC for short) will do all three steps. So
-as a first example, from Gnuastro's source, copy the
address@hidden/lib/versionc.c} in a test directory. This small program will
-use the @code{GAL_GNUASTRO_VERSION} to print the version of Gnuastro (see
address@hidden numbering}). It is good practice for a program to report the
-versions of its dependencies for later reproducibility, so this function
-will (hopefully) be used a lot. To compile this program you can run this
-command from the same directory that contains the C source file. Since this
-function just uses a macro (defined in the header), it doesn't need to link
-to gnuastro to work.
+as a first example, from Gnuastro's source, go to @file{tests/lib/}. This
+directory contains the library tests, you can use these as some simple
+tutorials. For this demonstration, we will compile and run the
address@hidden This small program will call Gnuastro library for some
+simple operations on an array (open it and have a look). To compile this
+program, run this command inside the directory containing it.
 
 @example
-$ gcc versionc.c -o gnuastro-version
+$ gcc arraymanip.c -lgnuastro -lm -o arraymanip
 @end example
 
-If your top installation directory (let's call it @file{$prefix}, see
address@hidden directory}) is not recognized by GCC, you will get
-pre-processor errors for unknown header files. To fix the problem, you
-should run GCC as follows: telling it where to find the header files (see
address@hidden):
address@hidden
+The two @option{-lgnuastro} and @option{-lm} options (in this order) tell
+GCC to first link with the Gnuastro library and then with C's math
+library. The @option{-o} option is used to specify the name of the output
+executable, without it the output file name will be @file{a.out} (on most
+OSs), independent of your input file name(s).
+
+If your top Gnuastro installation directory (let's call it @file{$prefix},
+see @ref{Installation directory}) is not recognized by GCC, you will get
+pre-processor errors for unknown header files. Once you fix it, you will
+get linker errors for undefined functions. To fix both, you should run GCC
+as follows: additionally telling it which directories it can find
+Gnuastro's headers and compiled library (see @ref{Headers} and
address@hidden):
+
address@hidden
+$ gcc -I$prefix/include -L$prefix/lib arraymanip.c -lgnuastro -lm     \
+      -o arraymanip
address@hidden example
+
address@hidden
+This single command has done all the preprocessor, compilation and linker
+operations. Therefore no intermediate files (object files in particular)
+were created, only a single output executable was created. You are now
+ready to run the program with:
+
address@hidden
+$ ./arraymanip
address@hidden example
+
+The Gnuastro functions called by this program only needed to be linked with
+the C math library. But if your program needs WCS coordinate
+transformations, needs to read a FITS file, needs special math operations
+(which include its linear algebra operations), or you want it to run on
+multiple CPU threads, you also need to add these libraries in the call to
+GCC: @option{-lgnuastro -lwcs -lcfitsio -lgsl -lgslcblas -pthread -lm}. In
address@hidden library}, where each function is documented, it is mentioned
+which libraries (if any) must also be linked when you call a function. If
+you feel all these linkings can be confusing, please have a look at
address@hidden linking script}.
+
+
address@hidden Automatic linking script,  , Summary and example on libraries, 
Review of library fundamentals
address@hidden Automatic linking script
+The number and order of libraries that are necessary for linking a program
+with Gnuastro library might be too confusing when you need to compile a
+small program for one particular job (with one source file). To solve this
+problem, please add these lines to your @file{~/.bashrc} with a text editor
+and replace @code{PREFIX} with Gnuastro's installation directory (see
address@hidden directory}).
+
address@hidden
+# Compile and correctly link Gnuastro related programs
+function gnuastro-gcc @{
+  libtool --mode=link gcc $1.c $2 PREFIX/lib/libgnuastro.la -o $1
address@hidden
address@hidden example
+
address@hidden GNU Libtool
+This tiny shell function uses GNU Libtool to find the necessary libraries
+to link against. Libtool uses the same libraries that were checked when you
+configured Gnuastro to link your program. So in the future, if Gnuastro's
+prerequisite libraries change, you don't have to worry. Afterwards, when
+you want to compile a C program that uses Gnuastro library (for example
address@hidden), just run the following command from the directory which
+contains the source file:
 
 @example
-$ gcc -I$prefix/include versionc.c -o gnuastro-version
+gnuastro-gcc myprog
 @end example
 
 @noindent
-The @option{-o} option is used to specify the name of the output
-executable, without it the output file name will be @file{a.out},
-independent of your input file name(s). This single command has done all
-the preprocessor, compilation and linker operations. You are now ready to
-run the program with
+If your program needs to link with libraries other than those needed by
+Gnuastro, you can specify them as a second argument (within double quotes):
 
 @example
-$ ./gnuastro-version
+gnuastro-gcc myprog "-lfirst -lsecond"
 @end example
 
-This simple Gnuastro function didn't need linking. But if your program
-needs WCS coordinate transformations, needs to read a FITS file, or needs
-mathematical operations (which include its linear algebra operations), you
-also need to add these libraries in the call to GCC: @option{-lgnuastro
--lwcs -lcfitsio -lgsl -lgslcblas -lm}. In @ref{Gnuastro library} where we
-document each function, it is mentioned which libraries (if any) must also
-be linked when you call a function.
address@hidden
+If you also want to execute the compiled program without typing a second
+command, add @command{&& ./myprog} to either of the lines above, like the
+example below. If your program can take arguments, then you can also
+include them afterwards.
 
address@hidden
+gnuastro-gcc myprog && ./myprog
address@hidden example
 
 
 @node Gnuastro library, The TEMPLATE utility, Review of library fundamentals, 
Libraries
@@ -14636,12 +14694,11 @@ lower level libraries for some operations (see
 your program use functions from the dependencies, you will also need to
 link those dependencies after linking with Gnuastro. The outside libraries
 that need to be linked for such functions are mentioned following the
-function name. In the rare case that all dependencies are necessary, you
-should link the following libraries:
+function name. See @ref{Automatic linking script} for a small shell
+function to worry about the libraries to link against and let you focus on
+your exciting science.
+
 
address@hidden
--lgnuastro -ljpeg -lwcs -lcfitsio -lgsl -lgslcblas -pthread -lm
address@hidden example
 
 @cartouche
 @noindent
diff --git a/tests/Makefile.am b/tests/Makefile.am
index 34ce751..180256a 100644
--- a/tests/Makefile.am
+++ b/tests/Makefile.am
@@ -56,8 +56,8 @@ export hasghostscript=$(MAYBE_HASGHOSTSCRIPT);
 
 # Compilations that are to be done with `make check'.
 LDADD = -lgnuastro
-check_PROGRAMS = versionc versioncpp
-versionc_SOURCES = lib/versionc.c
+check_PROGRAMS = versioncpp arraymanip
+arraymanip_SOURCES = lib/arraymanip.c
 versioncpp_SOURCES = lib/versioncpp.cpp
 
 
diff --git a/tests/lib/arraymanip.c b/tests/lib/arraymanip.c
new file mode 100644
index 0000000..1b2c945
--- /dev/null
+++ b/tests/lib/arraymanip.c
@@ -0,0 +1,75 @@
+/*********************************************************************
+A test program to test array functions in Gnuastro.
+
+Original author:
+     Mohammad Akhlaghi <address@hidden>
+Contributing author(s):
+Copyright (C) 2016, Free Software Foundation, Inc.
+
+Gnuastro is free software: you can redistribute it and/or modify it
+under the terms of the GNU General Public License as published by the
+Free Software Foundation, either version 3 of the License, or (at your
+option) any later version.
+
+Gnuastro is distributed in the hope that it will be useful, but
+WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with Gnuastro. If not, see <http://www.gnu.org/licenses/>.
+**********************************************************************/
+#include <stdio.h>
+#include <stdlib.h>
+
+#include "gnuastro/array.h"
+#include "gnuastro/gnuastro.h"
+
+int
+main(void)
+{
+  double *array;
+  size_t i, size=6;
+
+  /* Allocate the array, report an error if it wasn't allocated. */
+  array=malloc(size * sizeof *array);
+  if(array==NULL)
+    {
+      fprintf(stderr, "%lu bytes for d.\n", size);
+      exit(EXIT_FAILURE);
+    }
+
+  /* Print the version of Gnuastro being used: */
+  printf("Test of Gnuastro %s\n", GAL_GNUASTRO_VERSION);
+
+  /* Fill in the test array and report its contents at the same time. */
+  printf("Input array: ");
+  for(i=0;i<size;++i)
+    {
+      array[i]=i;
+      printf("%.3f, ", array[i]);
+    }
+
+  /* delete the last two characters, add a . and newline */
+  printf("\b\b.\n");
+
+  /* Now do some simple operations, and report each */
+  printf("Multipyling by 2.0...\n");
+  gal_array_dmultip_const(array, size, 2.0f);
+
+  printf("Dividing by 3.0...\n");
+  gal_array_ddivide_const(array, size, 3.0f);
+
+  printf("Taking natural logarithm...\n");
+  gal_array_dlog_array(array, size);
+
+  /* Report the final array: */
+  printf("Output array: ");
+  for(i=0;i<size;++i)
+    printf("%.3f, ", array[i]);
+  printf("\b\b.\n");
+
+  /* Cleanup and return */
+  free(array);
+  return EXIT_SUCCESS;
+}
diff --git a/tests/lib/versionc.c b/tests/lib/versionc.c
deleted file mode 100644
index e25d051..0000000
--- a/tests/lib/versionc.c
+++ /dev/null
@@ -1,36 +0,0 @@
-/*********************************************************************
-A test program to get and use the version number of Gnuastro within C.
-
-Original author:
-     Mohammad Akhlaghi <address@hidden>
-Contributing author(s):
-Copyright (C) 2015, Free Software Foundation, Inc.
-
-Gnuastro is free software: you can redistribute it and/or modify it
-under the terms of the GNU General Public License as published by the
-Free Software Foundation, either version 3 of the License, or (at your
-option) any later version.
-
-Gnuastro is distributed in the hope that it will be useful, but
-WITHOUT ANY WARRANTY; without even the implied warranty of
-MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
-General Public License for more details.
-
-You should have received a copy of the GNU General Public License
-along with Gnuastro. If not, see <http://www.gnu.org/licenses/>.
-**********************************************************************/
-
-#include <stdio.h>
-#include <stdlib.h>
-
-#include "gnuastro/gnuastro.h"
-
-int
-main(void)
-{
-  /* Print the version. */
-  printf("Gnuastro version is: %s\n", GAL_GNUASTRO_VERSION);
-
-  /* Cleanup and return */
-  return EXIT_SUCCESS;
-}