GNU Astronomy Utilities


Previous: , Up: BuildProgram   [Contents][Index]


10.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', 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 --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.

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

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

-b
--onlybuild

Only build the program, don’t run it. By default, the built program is immediately run afterwards.


Previous: , Up: BuildProgram   [Contents][Index]