12.2.1 Invoking BuildProgram ¶

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', do not 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 given source into a final executable program 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 system to remove the suffix of the input source file (usually .c) and use the resulting name as the built program 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 C compiler can be chosen with the --cc option, or environment variables, please see the description of --cc for more. The two common LDFLAGS and CPPFLAGS environment variables are also checked and used in the build by default. Note that they are placed after the values to the corresponding options --includedir and --linkdir. Therefore BuildProgram’s own options take precedence. Using environment variables can be disabled with the --noenv option. Just note that BuildProgram also keeps the important flags in these environment variables in its configuration file. Therefore, in many cases, even though you may needed them to build Gnuastro, you will not need them in BuildProgram.

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 --onlybuild option.

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 Makefile.

-c STR ¶

--cc=STR

C compiler to use for the compilation, if not given environment variables will be used as described in the next paragraph. If the compiler is in your system’s search path, you can simply give its name, for example, --cc=gcc. If it is not in your system’s search path, you can give its full path, for example, --cc=/path/to/your/custom/cc.

If this option has no value after parsing the command-line and all configuration files (see Configuration file precedence), then BuildProgram will look into the following environment variables in the given order CC and GCC. If they are also not defined, BuildProgram will ultimately default to the gcc command which is present in many systems (sometimes as a link to other compilers).

-I STR ¶

--includedir=STR

Directory to search for files that you #include in your C program. Note that headers relating to Gnuastro and its dependencies do not 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 preprocessor 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”.

-L STR ¶

--linkdir=STR

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.

-l STR

--linklib=STR

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.

-O INT/STR ¶

--optimize=INT/STR

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.

-g ¶

--debug

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).

-W STR

--warning=STR

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).

-t

--tag=STR

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 does not 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.

-b

--onlybuild

Only build the program, do not run it. By default, the built program is immediately run afterwards.

-d

--deletecompiled

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.

-a STR

--la=STR

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.

-e ¶

--noenv

Do not use environment variables in the build, just use the values given to the options. As described above, environment variables like CC, GCC, LDFLAGS, CPPFLAGS will be read by default and used in the build if they have been defined.