Anjuta build tutorial

Each C source file goes through the preprocessor, named cpp. In this stage, all include files and macros are expanded to get preprocessed C source code. The resulting file .i is rarely generated but it could be interesting to see how complex macros are expanded. You can do this by calling cpp directly or using the -E switch of GCC. The later option is better as it allows to run the preprocessor with all default options.

In this stage each file is compiled into assembler code. The compiler depends on the language of the source file, C here. It is a complex program because there is not a one to one correspondence between C instructions and assembler instructions. By example, requesting the fastest or the smallest program will generate different sequences of assembler instructions. The assembler is the language of your computer, the most common one is called x86. The output is a, human readable, assembler source file ending with '.s'. Like the preprocessor output, the assembler code is not normally written on the hard disk. You can stop the compilation at this stage to look at it by running GCC with the -S switch.

In this stage each file is assembled: the assembler code is transformed to an object file with .o extension. It is much easier than the compilation as each assembler instruction corresponds to an unique code. The object file contains additional information for debugging or linking the program. The object file is a binary format, called ELF on recent Linux machine, you need to use special program to look in it like objdump. It is possible to write directly assembler code and assemble it using the assembler ,as, or GCC if your source file has a .s extension. These object files are commonly written on your hard disk because it depends only of theirs corresponding C source file (with all files included). If you modify only one source file, you need to regenerate only the corresponding object file. You can stop at this stage, without linking by using -c switch with GCC.

This stage is used to combine all the object files and libraries into one executable file. The result is a binary file in a format close to the object file, on Linux it is even the same format.

Like in any programming language, you can define variables in a make file. All variables contains a string or a list of strings separated by whitespace. A variable is defined using the following syntax: name=value. You can get its value by writing $(name) or ${name}. In the sample above, three variables are defined CC, CFLAGS and LIBS.

Variables can be redefined when calling make in the command line or using values from environment. Moreover make includes some default rules using predefined variables. Here is a list of the most common ones:

The basic syntax for make rules is:

target: prerequisites
	commands
	…

The target and the prerequisites are normally files but they could be actions. The rule is interpreted as in order to make the target or update it if it is older than its prerequisites, you need to make all prerequisites and then run all commands.

make starts with the first target of the makefile or the one given in the command line and looks for a rule. If this rules has no prerequisites, the associated commands are run and that's all. Else before running the commands, for each prerequisite, make looks for a rule having it as target and repeats the same process.

In the sample above, if you run make or make tut_prog. make does the following:

Search a rule with tut_prog as target
Found with prerequisites main.o aux.o
	Search a rule with main.o as target
	Found with prequisite main.c
		Search a rule with main.c as target
		Not found (main.c is a source file)
	If main.o does not exist or is older than main.c
		Compile main.c, do not link (-c switch)
	Search a rule with aux.o as target
	Found with prequisite aux.c
		Search a rule with aux.c as target
		Not found (aux.c is a source file)
	If aux.o does not exist or is older than aux.c
		Compile aux.c, do not link (-c switch)
If tut_prog is older than main.o or aux.o
	Link main.o, aux.o and libxml2

Like for variables, several target names are commonly defined:

An Autotools project comes at least with a configure script, named configure, and a makefile template named Makefile.in. There is normally, one Makefile.in in each directory of the project. There are several other files used by an Autotools project but they are not stricly necessary or are generated automatically.

In fact, you don't need Autotools to build an autotools package, configure is a shell script running on the most basic shell: sh. It probes your system checking each characteristic and writes makefiles from the templates.

Figure 2-2 Configure process

configure creates all files in the directory where it is called. This directory is the build directory. If you run it from the source directory, using ./configure, the build directory will be the same.

configure accepts several options in the command line. They are used to install the files in different directories, to disable some parts of the project in order to get a smaller executable or if you haven't one needed library or force a value for some make variable (see Section 2.2.1 ― Variables). You can get a list of them by running configure --help. Here is a list of the most common ones:

The makefiles generated by configure are quite complex but are standard makefiles. They define all standard targets needed by GNU standard.

As Anjuta is using Autotools, the first step is similar, you need to run configure. Select Build ▸ Configure Project…, to get the following dialog:

Figure 2-3 Configure dialog

The Regenerate project checkbox will not be described now as it is related to project creation (see in Section 3.1.6 ― Generate project).

The Configuration field is an user name used to reference this particular configuration to switch between different ones later. For Anjuta each configuration corresponds to one build directory and a set of configure options. Anjuta already provides some default configurations that you can select here.

The Build Directory field allow to select the directory used to build the project. It must be different for each configuration.

The Configure Options field allow passing different options to the configure script.

Clicking on Execute will run the configure script. All the output will appears in the message view of Anjuta. If the script runs without error, it will enable all other entries in the Build menu.

The build operations in Anjuta, rely on make only like Autotools. It is working for non Autotools project too. The compile command is even working with only a C source file because make has some builtin rules to compile them. Here is the correspondence between the Anjuta menu item and make commands.

The last menu entry not described above ,Build ▸ Select Configuration, allows you to switch easily between different configurations and so between different build directories.

A few common build options are available in the preferences page that you can get by selecting Edit ▸ Preferences ▸ Build autotools.

Figure 2-4 Build preferences

AC_INIT([Tutorial Program], 1.0)
AM_INIT_AUTOMAKE
AC_PROG_CC
AC_CONFIG_FILES(Makefile)
AC_OUTPUT

AC_INIT, AM_INIT_AUTOMAKE, etc... are M4 macros. M4 is a macro expanding software used by Autotools; we don't need to know about it. When Autoconf will process this configure.in, the macros will be expanded and we will get a fresh huge configure script.

Autoconf only knows its own macros but read additional ones in a file named aclocal.m4. These macros are used to extend Autoconf, it includes Automake macro (starting with AM_) and other third party macros. For instance, if you develop a library called foo, you might want to write an AC_CHECK_FOR_FOO macro so that developers using your library can check for its presence using Autoconf.

aclocal scans configure.ac and create an aclocal.m4 file which contains the macros mentioned in configure.ac. aclocal is part of the Automake package and search by default in Automake macros and in a system path typically /usr/share/aclocal.

bin_PROGRAMS = tut_prog			
tut_prog_SOURCES = main.c

In Makefile.am are the very essential data needed to build the project: the target program, called tut_prog, will be put in a $prefix/bin/ directory; to build it we need main.c. Note that we don't specify how that will be built: Automake will figure it out. We haven't even mentioned the compiler in this pre-makefile.

Makefile.am will be processed by Automake; the result will be a Makefile.in. This Makefile.in is close to being a real makefile, but it contains variable names which will be replaced when the configure script will run, resulting in a real makefile (called Makefile). For instance, configure will write in the final Makefile what compiler to use (it is the compiler it found using the AC_PROG_CC macro).

Running aclocal, automake and autoconf one by one is fine for a tutorial to understand exactly what's happen. But, for a real work, it's a bit tedious especially because there are other tools those could be needed like autoheader, autopoint or libtoolize. After creating the project, the makefiles generated by configure should take care of regenerating configure and all Makefile.in. Anyway, this lets a room for improvement and there are even two responses to this:

dnl Process this file with autoconf to produce a configure script.
dnl Created by Anjuta application wizard.

AC_INIT(tutprog, 0.1)

AM_INIT_AUTOMAKE(AC_PACKAGE_NAME, AC_PACKAGE_VERSION)
AC_CONFIG_HEADERS([config.h])
AM_MAINTAINER_MODE

AC_PROG_CC

AC_OUTPUT([
Makefile
])

It is still quite simple with a bit more macros. Let's look at all unknown ones:

## Process this file with automake to produce Makefile.in
## Created by Anjuta

AM_CPPFLAGS = \
        -DPACKAGE_DATA_DIR=\""$(datadir)"\"

AM_CFLAGS =\
         -Wall\
         -g

bin_PROGRAMS = tutprog

tutprog_SOURCES = \
        main.c

tutprog_LDFLAGS =

tutprog_LDADD =

Not much things in the Makefile.am neither:

pkg-config is tools for developers providing a unified interface for querying installed libraries with their version and all options needed to compile and link it. It comes with an Autoconf macro named PKG_CHECK_MODULES allowing to check the existence of the library and set all necessary flags.

If the library does not support pkg-config: it does not appear in the list returned by pkg-config --list-all. You need a Autoconf macro:

When, you have this macro, you can copy it in /usr/share/aclocal, so aclocal will find it. Then, you just need to look in the macro file to see how to use it. libxml2 installs a macro named AM_PATH_XML2 which is in /usr/share/aclocal/libxml.m4.

It is the approach one could naturally have: let's give GCC the stuff it needs directly ! On my system, libxml/parser.h is in /usr/include/libxml2, and the shared object is 'libxml.so', located in /usr/lib. (I will assume it's all the same for you).

I have described this here to show that it is possible to do simple thing using Autotools. But this approach has several drawbacks:

Anjuta has no real support for library not using pkg-config. You need to edit the configure.ac directly to add all necessary macros. For passing flags to each target you can select the Advanced button in the target properties dialog.