2.1. Compilation

A typical compilation command:

			$gcc -g -Wall -I/usr/include/libxml2/libxml -lxml2 main.c aux.c -o tut_prog 
			

Here, tut_prog can use the libxml2 library to parse some XML.

The -g, -Wall and -I switches are know as CFLAGS (because they are passed to the compiler); -l is a LDFLAG (because it is passed to the linker) or a LIBS flag. Thus, if we suppose CFLAGS=-g -Wall -I/usr/include/libxml2/libxml and LIBS=-Lxml2 then our compilation command is equivalent to $gcc $(CFLAGS) $(LIBS) main.c aux.c -o tut_prog.

Using Anjuta you will never type a compilation command line.

2.2. Makefiles

With makefiles you can greatly automate the compilation process (and actually make many more things than just compiling). A Makefile file for our tutorial program could be :

				Makefile:
				
				
				CC=gcc 	# the C compiler is gcc
				CFLAGS=-g -Wall -I/usr/include/libxml2
				LIBS=-lxml2					
				
				tut_prog: main.o aux.o   # what we need to have 'tut_prog'...
					$(CC) $(LIBS) main.o aux.o -o tut_prog # ...and how to get it from the ingredients.
					
				main.o: main.c
					$(CC) -c $(CFLAGS) main.c
					
				aux.o: aux.c
					$(CC) -c $(CFLAGS) aux.c
				

Makefiles have a dependency approach: to have the 'tut_prog' binary, we must first ensure that the object files main.o and aux.o are present (first line), and then link them (second line) using CC; similarly to have these object files we need the source files main.c and aux.c to be present (first line) and compiled (second line).

Once the Makefile is typed, you only have to run 'make' for your program to be built and up to date.

With Anjuta, you will never have to read or write a makefile.

3.1. A simple example without Anjuta

Let's see a simple example to start grasping the relationships between the various files.

Create an empty directory called 'tut_prog', and within it a simple 'main.c' C source file :

			main.c: 
		
			#include <stdio.h> 
			
			int main()
			{
				printf("Hello world!\n");
				return 0;
			}
		

Now let's write configure.in, which is the template for the configure script. It is the input file of autoconf and is also used by automake.

			configure.in: 

			AC_INIT
			AM_INIT_AUTOMAKE(tut_prog, 1.0)
			AC_PROG_CC
			AC_OUTPUT(Makefile)
		

AC_INIT, AM_INIT_AUTOMAKE, etc... are m4 macros. m4 is a macro expanding software used by the 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.

AC_INIT expands into the initialization part of the configure script, which, when launched, will perform some basic tests of the system's sanity.

AM_INIT_AUTOMAKE expands into some other initialization code; here we indicate the name of the software and its version.

AC_PROG_CC expands in a code that checks for a decent C compiling environment, that we actually need to build our test program.

AC_OUTPUT indicates what makefiles will be produced by the configure script.

Many other macros are available to check for every kind of program or library. Some of them are standard macros, provided by the autotools, others are software-specific. 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. Look at the standard macros list if you like.

So when we will launch autoconf, it will expand the macros. The macros contents were installed on your system when you installed autoconf.

To locate them, search .m4 files on your system.

On my system, I actually get an extra directory called 'autom4te.cache'. That is for autoconf internal purposes; so I won't care about it anymore.

It's now time to deal with automake and makefiles. automake's input is a file called 'Makefile.am' which describes the software to build in a very global way. Create the following Makefile.am :

			Makefile.am: 
		
		
			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 have'nt 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).

It's now time to run 'automake'. But first create some empty files: NEWS, README, AUTHORS and ChangeLog:

$touch NEWS README AUTHORS ChangeLog

Now look inside your directory. Makefile.in is here, OK, but many other files have appeared. They are not essential. Keep in mind the 4 really important ones : configure.in, configure, Makefile.am, and Makefile.in (and main.c of course).

Note that the two .in files don't have the same "type": configure.in is a file written by yourself (and so, small) processed by autoconf; but Makefile.in is a big file generated by automake and that will be processed by 'configure'. I think that extension is quite misleading.

Everything is now ready for configure to run. Run './configure'.

$ ./configure
			
			checking for a BSD-compatible install... /usr//bin/install -c
			checking whether build environment is sane... yes
			checking for gawk... gawk
			checking whether make sets $(MAKE)... yes
			checking for gcc... gcc
			checking for C compiler default output... a.out
			checking whether the C compiler works... yes
			checking whether we are cross compiling... no
			checking for suffix of executables... 
			checking for suffix of object files... o
			checking whether we are using the GNU C compiler... yes
			checking whether gcc accepts -g... yes
			checking for gcc option to accept ANSI C... none needed
			checking for style of include used by make... GNU
			checking dependency style of gcc... gcc3
			configure: creating ./config.status
			config.status: creating Makefile
			config.status: executing depfiles commands
			
		

You can now Run 'make'.

$ make
			
			if gcc -DPACKAGE_NAME=\"\" -DPACKAGE_TARNAME=\"\" -DPACKAGE_VERSION=\"\" -DPACKAGE_STRING=\"\" \
				-DPACKAGE_BUGREPORT=\"\" -DPACKAGE=\"tut_prog\" -DVERSION=\"1.0\"  -I. -I.     -g -O2 -MT main.o \
				-MD -MP -MF ".deps/main.Tpo" \
			  -c -o main.o `test -f 'main.c' || echo './'`main.c; \
			then mv -f ".deps/main.Tpo" ".deps/main.Po"; \
			else rm -f ".deps/main.Tpo"; exit 1; \
			fi
			gcc  -g -O2   -o tut_prog  main.o			
			
			

 #define PACKAGE "tut_prog" 

printf("This package is %s\n", PACKAGE);

				$ make
				 -- make output cut --
				$ ./tut_prog
				 
					Hello world!
					This package is tut_prog
				
		

Take a look at your directory again. It's a real mess (and there's even a hidden directory inside on my system). But now you are not afraid of it anymore :)

For things to be even clearer, you can take a look at the dependencies amongst the various files in this chapter of the Autobook.

3.2. The same thing with Anjuta

Let's see how does Anjuta handle a very simple project containing only the main.c file we used in the previous section. Launch Anjuta, create a new project of type 'Generic/Terminal project.'

Call it 'tut_prog' and let it be a C-only project. Enter no comment, uncheck copyright statement and gettext support since we want to keep things as simple as possible.

Complete the remaining steps of the application wizard; the project is now created. The default behaviour of Anjuta is to create a directory 'tut_prog' in $HOME/Projects, to add a src/ subdirectory and a sample main.c file in it. The project is configured immediately. Here is some simplified output:

		
		**Warning**: I am going to run `configure' with no arguments.
		If you wish to pass any to it, please specify them on the
		`./autogen.sh' command line.
		
		processing .
		Running libtoolize...
		Running aclocal  ...
		Running autoheader...
		--- some warnings from autoheader ---
		Running automake --gnu  ...
		Running autoconf ...
		Running ./configure ...
		--- various tests run by configure ---
		creating libtool
		configure: creating ./config.status
		config.status: creating Makefile
		config.status: creating src/Makefile
		config.status: creating config.h
		config.status: config.h is unchanged
		config.status: executing depfiles commands
		Now type `make' to compile the package.
		
		

In fact, Anjuta runs a script called 'autogen.sh', provided by Anjuta itself (that is, it is not part of the autotools) which runs : libtoolize, aclocal, autoheader, automake, autoconf and finally ./configure. We already know about aclocal, automake, autoconf and configure, let's look at libtoolize and autoheader.

libtoolize is provided by libtool. Its goal is to make library using easier, we will look at it later.

autoheader creates a 'config.h.in' file which, like Makefile.in, is processed later by configure, resulting in a 'config.h'. This C header file contains various #defines, all set by configure; you could take a look at it now. You can see:

		
			-- various #defines --
			
			/* Define to 1 if you have the <stdlib.h> header file. */
			/* -- this value is a result of a test by configure -- */
			#define HAVE_STDLIB_H 1
			
			-- various other #defines --
			
			/* Name of package */
			/* -- this is from configure.in -- */
			#define PACKAGE "tut_prog"
			
			-- various other #defines --
		
		

Do you remember how configure communicated with C files by using several -Dxxxx flags in the previous section ? In fact, this config.h is another mean of communication : by including 'config.h', a C source file can know everything that configure determined.

Now you can build the project (that is, run 'make') by pressing F11 and run the binary with F3 (both are in the 'Build' menu).

Just like we typed configure.in and Makefile.am in the previous section, Anjuta created these files automatically. They are indeed more complicated, while being very understandable: configure.in specifies more checks and more variables; moreover Makefile.am must manage the recursion in src/ (actually, there is a Makefile.am in src/ too). You can look at these files and thus expand your knowledge about autoconf and automake.

3.3. References

Here are some links to reference documents dealing with the autotools in general, and autoconf and automake in particular.

Please e-mail me /* how can that be done ? */ if one of these links is broken, or if you know other ones.

4.1. Some points about libtool

libtool is a portability layer which makes library access easier, since it hides the differences between the various Unix variants in this particular domain.

Using libtool is transparent for the Anjuta user, that is why I won't tell you much about it. However you can look at libtool's manual to understand its ins and outs.

4.2. First example: using libxml2 with pkg-config

libxml2 allows you to parse and produce XML files, which can be very useful nowadays (see its homepage at www.xmlsoft.org). Let's see how to use it with Anjuta.

Open our tut_prog project, and replace main.c by this one :

			main.c: 
		
			#include <libxml/parser.h>			
			#include <stdio.h>
			
			int main()
			{				
				xmlDocPtr doc;                                                                                                                  
				doc = xmlParseFile ("testfile.xml");                                                                                                          
				if (doc == NULL) {
					printf ("Document not parsed successfully. \n");
					return -1;
				}
				else {
					printf ("Document parsed successfully.\n");
					xmlFreeDoc(doc);
					return 0;
				}
			}
        	
		

				INCLUDES =\
					-I/usr/include/libxml2
			

				tut_prog_LDADD = \
					-lxml2
			

			
			checking for pkg-config... /usr/bin/pkg-config
			checking for libxml-2.0 >= 2.4... yes
			checking xml_CFLAGS... -I/usr/include/libxml2
			checking xml_LIBS... -lxml2 -lpthread -lz -lm
			
			

4.3. Using lib3ds: a m4 file is provided

lib3ds allows you to handle 3DS files. We will try to build and run the following code :

			main.c: 
		
			#include <lib3ds/types.h>
			#include <lib3ds/file.h>
			#include <stdio.h>
						
			int main()
			{				
				Lib3dsFile* file;                                                                                                                  
				file = lib3ds_file_load ("testfile.3ds");                                                                                                          
				if (file == NULL) {
					printf ("3DS file not read successfully. \n");
					return -1;
				}
				else {
					printf ("3DS file parsed successfully.\n");
					lib3ds_file_free(file);
					return 0;
				}
			}        	
		

This library does not use pkg-config. However, when I installed the lib3ds-devel package on my distro, I noticed a lib3ds.m4 file copied in /usr/share/aclocal/. I will now assume you have this package installed.

Take a look at this .m4 file. A comment note at the top explains how to use the macro it defines : AM_PATH_LIB3DS. Look around the end of the file : its seems to use AC_SUBST with variables LIB3DS_CFLAGS and LIB3DS_LIBS. We know that !

And given the AC_SUBST the following should work (I added -lm which stands for the math library; lib3ds' author seems to have forgotten it):

Regenerate the project and rebuild : that should work. In fact, 'aclocal' looked in /usr/share/aclocal/ (or the corresponding directory on your distro) for the .m4 files it needed, and found lib3ds.m4.

4.4. Macros for other libraries

More generally, to use a library with the help of autoconf, check the following:

• If the library is handled by pkg-config, just use the PKG_CHECK_MODULES macros as we did in the section above.

• Check if the library author shipped a .m4 macro, and use it if present.

• If your library is a basic one, it might be checked by the standard autoconf macros (see the list here).

• Perhaps the m4 you need has already be programmed by someone else. Look at the contributions here.

• If all that fail, go deeper in m4, make your own macro, and donate it to the library's author !