BuildProgram will compile and link a C source program with Gnuastro’s library and all its dependencies, greatly facilitating the compilation and running of small programs that use Gnuastro’s library. The executable name is astbuildprog with the following general template:
$ astbuildprog [OPTION...] C_SOURCE_FILE
One line examples:
## Compile, link and run `myprogram.c': $ astbuildprog myprogram.c ## Similar to previous, but with optimization and compiler warnings: $ astbuildprog -Wall -O2 myprogram.c ## Compile and link `myprogram.c', then run it with `image.fits' ## as its argument: $ astbuildprog myprogram.c image.fits ## Also look in other directories for headers and linking: $ astbuildprog -Lother -Iother/dir myprogram.c ## Just build (compile and link) `myprogram.c', don't run it: $ astbuildprog --onlybuild myprogram.c
If BuildProgram is to run, it needs a C programming language source file as input. By default it will compile and link the program to build the a final executable file and run it. The built executable name can be set with the optional --output option. When no output name is set, BuildProgram will use Gnuastro’s Automatic output, and remove the suffix of the input and use that as the output name. For the full list of options that BuildProgram shares with other Gnuastro programs, see Common options. You may also use Gnuastro’s Configuration files to specify other libraries/headers to use for special directories and not have to type them in every time.
The first argument is considered to be the C source file that must be
compiled and linked. Any other arguments (non-option tokens on the
command-line) will be passed onto the program when BuildProgram wants to
run it. Recall that by default BuildProgram will run the program after
building it. This behavior can be disabled with the
When the --quiet option (see Operating mode options) is not
called, BuildPrograms will print the compilation and running commands. Once
your program grows and you break it up into multiple files (which are much
more easily managed with Make), you can use the linking flags of the
non-quiet output in your
Directory to search for files that you
#include in your C program.
Note that headers relating to Gnuastro and its dependencies don’t need this
option. This is only necessary if you want to use other headers. It may be
called multiple times and order matters. This directory will be searched
before those of Gnuastro’s build and also the system search
directories. See Headers for a thorough introduction.
From the GNU C Pre-Processor manual: “Add the directory
STR to the
list of directories to be searched for header files. Directories named by
-I are searched before the standard system include directories.
If the directory
STR is a standard system include directory, the
option is ignored to ensure that the default search order for system
directories and the special treatment of system headers are not defeated”.
Directory to search for compiled libraries to link the program with. Note that all the directories that Gnuastro was built with will already be used by BuildProgram (GNU Libtool). This option is only necessary if your libraries are in other directories. Multiple calls to this option are possible and order matters. This directory will be searched before those of Gnuastro’s build and also the system search directories. See Linking for a thorough introduction.
Library to link with your program. Note that all the libraries that Gnuastro was built with will already be linked by BuildProgram (GNU Libtool). This option is only necessary if you want to link with other directories. Multiple calls to this option are possible and order matters. This library will be linked before Gnuastro’s library or its dependencies. See Linking for a thorough introduction.
Compiler optimization level: 0 (for no optimization, good debugging), 1, 2, 3 (for the highest level of optimizations). From the GNU Compiler Collection (GCC) manual: “Without any optimization option, the compiler’s goal is to reduce the cost of compilation and to make debugging produce the expected results. Statements are independent: if you stop the program with a break point between statements, you can then assign a new value to any variable or change the program counter to any other statement in the function and get exactly the results you expect from the source code. Turning on optimization flags makes the compiler attempt to improve the performance and/or code size at the expense of compilation time and possibly the ability to debug the program.” Please see your compiler’s manual for the full list of acceptable values to this option.
Emit extra information in the compiled binary for use by a debugger. When calling this option, it is best to explicitly disable optimization with -O0. To combine both options you can run -gO0 (see Options for how short options can be merged into one).
Print compiler warnings on command-line during compilation. “Warnings are diagnostic messages that report constructions that are not inherently erroneous but that are risky or suggest there may have been an error.” (from the GCC manual). It is always recommended to compile your programs with warnings enabled.
All compiler warning options that start with W are usable by this option in BuildProgram also, see your compiler’s manual for the full list. Some of the most common values to this option are: pedantic (Warnings related to standard C) and all (all issues the compiler confronts).
The language configuration information. Libtool can build objects and
libraries in many languages. In many cases, it can identify the language
automatically, but when it doesn’t you can use this option to explicitly
notify Libtool of the language. The acceptable values are:
CC for C,
CXX for C++,
GCJ for Java,
F77 for Fortran 77,
FC for Fortran,
GO for Go and
RC for Windows
Resource. Note that the Gnuastro library is not yet fully compatible with
all these languages.
Only build the program, don’t run it. By default, the built program is immediately run afterwards.
Delete the compiled binary file after running it. This option is only relevant when the compiled program is run after being built. In other words, it is only relevant when --onlybuild is not called. It can be useful when you are busy testing a program or just want a fast result and the actual binary/compiled file is not of later use.
Use the given .la file (Libtool control file) instead of the one that was produced from Gnuastro’s configuration results. The Libtool control file keeps all the necessary information for building and linking a program with a library built by Libtool. The default prefix/lib/libgnuastro.la keeps all the information necessary to build a program using the Gnuastro library gathered during configure time (see Installation directory for prefix). This option is useful when you prefer to use another Libtool control file.