<?xml version="1.0"?>
<!DOCTYPE manual PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" >

<!-- "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [ 
  <!ENTITY date "March 2004">
  <!ENTITY app "anjuta"> -->
<!-- =============Document Header ============================= -->
<book id="index">
 <bookinfo>
  <title>Anjuta advanced tutorial</title>
  <edition>v0.1</edition>

  <copyright>
   <year>2004</year>
   <holder>Olivier Pinçon</holder>
  </copyright>

<!-- translators: uncomment this:
  <copyright>
   <year>2001</year>
   <holder>ME-THE-TRANSLATOR </holder>
  </copyright>
-->
  
  <legalnotice>
   <para>
     Permission is granted to copy, distribute and/or modify this
     document under the terms of the <citetitle>GNU Free Documentation
     License</citetitle>, Version 1.1 or any later version published
     by the Free Software Foundation with no Invariant Sections, no
     Front-Cover Texts, and no Back-Cover Texts. You may obtain a copy
     of the <citetitle>GNU Free Documentation License</citetitle> from
     the Free Software Foundation by visiting <ulink type="http"
     url="http://www.fsf.org">their Web site</ulink> or by writing to:
     Free Software Foundation, Inc., 59 Temple Place - Suite 330,
     Boston, MA 02111-1307, USA.
   </para>
   <para>
     Many of the names used by companies to distinguish their products and
     services are claimed as trademarks. Where those names appear in any
     GNOME documentation, and those trademarks are made aware to the members
     of the GNOME Documentation Project, the names have been printed in caps
     or initial caps.
   </para>
  </legalnotice>

  <!-- this is the version of manual, not application --> 
  <releaseinfo>
   This is version 0.1 of Anjuta advanced tutorial
  </releaseinfo>
 </bookinfo>
 <!-- Document Body -->
 <!-- Introduction -->
<chapter id="intro">
	<title>Introduction</title>
	<para>
		When I first launched Anjuta, I told myself : "Hey, that looks like MS Visual C++, as I 
		know it pretty well, understanding Anjuta will be a piece of cake.". As you might have guessed, 
		I come from the Windows world and I was looking for something familiar.
		Actually, Anjuta differs quite a bit from MSVC or Borland's C++ Builder, essentially 
		in its build system, which is in fact the standard linux build system using 
		<application>autoconf</application>, <application>automake</application> and
		<application>libtool</application>; these three programs are usually referred to
		as the <application>autotools</application>.
	</para>
	<para>
		Here I will try to explain everything that I wanted to know but could'nt directly find 
		when I started using Anjuta.
		Therefore, this tutorial should be especially suitable to you if you are starting 
		GNU/Linux programming.
	</para>
	<para> 
		I will use Anjuta v1.2.1 here; so things can slightly differ if you have another 
		version.
		I assume that you have a basic understanding of C or C++ and makefiles.
	</para>
</chapter>

<chapter id="reminders">
	<title>Some reminders</title>
	<para>
		Let's quickly review the basics before we get a higher-level view.
	</para>
	<sect1 id="compilation"> 
			<title>Compilation</title>
			<para> A typical compilation command:
			<screen>
			<prompt>$</prompt><userinput>gcc -g -Wall -I/usr/include/libxml2/libxml -lxml2 main.c aux.c -o tut_prog </userinput>
			</screen>
			 This command tells GCC to compile the source files main.c and aux.c, and
			 produce a binary called 'tut_prog' (this stands for 'tutorial program').
			 The various switches have the following meaning :
			</para>
			<informaltable frame="all">        			
        			<tgroup cols="2">
          		<thead>
            		<row>
              			<entry>Switch</entry>
              			<entry>Meaning</entry>
            		</row>
          		</thead>
          		<tbody>
	            <row>
		              	<entry>-g</entry>
		              	<entry>tells GCC to include debug info into the binary.</entry>
	            </row>
	            <row>
		              	<entry>-Wall</entry>		              			              	
              			<entry>Warning all : print every warning.</entry>              			
	            </row>
	            <row>
	            		<entry>-Idir</entry>
	            		<entry>Look for included header files (like in #include &lt;myheader.h&gt;) in directory dir.</entry>              			
	            </row>
	            <row>
	            		<entry>-llib</entry>
	            		<entry>Link to library lib; here libxml2.</entry>
	            </row>
          		</tbody>
       	 		</tgroup>
			</informaltable>			
			<para>
			Here, tut_prog can use the libxml2 library to parse some XML.
			</para>
			<para>
			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
			<userinput>CFLAGS=-g -Wall -I/usr/include/libxml2/libxml</userinput> and
			<userinput>LIBS=-Lxml2</userinput> then our compilation command is equivalent to
			<prompt>$</prompt><userinput>gcc $(CFLAGS) $(LIBS) main.c aux.c -o tut_prog</userinput>.
			</para>
			<para>
			Using Anjuta you will never type a compilation command line.
			</para>
	</sect1>
	<sect1 id="makefiles"> 
			<title>Makefiles</title>
			<para>With makefiles you can greatly automate the compilation process 
			(and actually make many more things than just compiling). A <filename>Makefile</filename>
			file for our tutorial program could be :
			</para>
			<example>
				<title>A simple Makefile file</title>
				<programlisting>
				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
				</programlisting>
			</example>
			<para>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).
			</para>
			<para> Once the Makefile is typed, you only have to run 'make' for your program
			to be built and up to date.
			</para>
			<para>With Anjuta, you will never have to read or write a makefile.
			</para>
	</sect1>	
	
</chapter>


<!-- The build system -->
<chapter id="build-system">
	<title>The build system</title>
	<para>
		Anjuta uses the standard GNU build system, that is to say it uses autoconf, 
		automake and libtool, also know as the autotools. 
		You probably have already installed software from source,
		using the magic combination "./configure; make; make install", and may have noticed
		that many files are involved in this build process; globally all that stuff seems
		very complicated. But you must understand the fundamentals of
		the build system before using it through Anjuta.
	</para>
	<para>
		The GNU build system is a very flexible framework. Its main goal is portability of
		your software to various Unices and Windows as well (in my opinion, this is mainly
		the purpose of autoconf and libtool). It also allows quick generation of very
		complete makefiles.
	</para>
	<para>
		What's happening when you compile GNU software ? The configure shell script (invoked 
		by './configure') checks your system (it searches necessary libraries, amongst other things) and
		adjusts some makefiles (for instance, write the libraries access paths in makefiles).
		When you launch 'make', makefiles are simply executed to build the software; 
		and 'make install' copies the compiled software on your system, using the make target
		called 'install'.
	</para>
	<para> You must keep in mind that the configure script or the makefiles are huge
		files generated by the GNU tools. We will not look inside them here; instead
		we will create the human-readable templates that are input files for the GNU
		tools.
	</para>
	
	
	<sect1 id="simple-example-without-anjuta">
		<title> A simple example without Anjuta </title>
		<para> Let's see a simple example to start grasping the relationships between the various
			files.
		</para>
		<para><emphasis>Create an empty directory called 'tut_prog', and within it a simple 'main.c' 
		C source file </emphasis> :
		</para>
		<programlisting role="C">
			main.c: 
		
			<![CDATA[#include <stdio.h> ]]>
			
			int main()
			{
				printf("Hello world!\n");
				return 0;
			}
		</programlisting>		
		<para>Now <emphasis>let's write configure.in</emphasis>, which is the template for the configure script.
		It is the input file of autoconf	and is also used by automake.
		</para>
		<programlisting>
			configure.in: 

			AC_INIT
			AM_INIT_AUTOMAKE(tut_prog, 1.0)
			AC_PROG_CC
			AC_OUTPUT(Makefile)
		</programlisting>
		<para>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.
		</para>
		<para> AC_INIT expands into the initialization part of the configure script, which, 
		when launched, will perform some basic tests of the system's sanity.
		</para>
		<para> AM_INIT_AUTOMAKE expands into some other initialization code; here we indicate
		the name of the software and its version.</para>
		<para>AC_PROG_CC expands in a code that checks for a decent C compiling environment, 
		that we actually need to build our test program.</para>
		<para>AC_OUTPUT indicates what makefiles will be produced by the configure script.</para>
		<para>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 <ulink type="http" url="http://sources.redhat.com/autobook/autobook/autobook_283.html#SEC283">standard macros list</ulink> if you
		like.</para>
		
		<para>So when we will launch autoconf, it will expand the macros. The macros contents
		were installed on your system when you installed autoconf. 
		<tip>To locate them, search .m4 files on your system.</tip>
		The macros we use must first be copied into the 'tut_prog' directory. That is 
		done by launching 'aclocal' which scans configure.in and create an aclocal.m4 
		file which contains the macros mentionned in configure.in. <emphasis>Launch 'aclocal' now.</emphasis>
		Now we have all the macros, <emphasis>run 'autoconf'</emphasis>. We now have 4 files : main.c, configure.in,
		aclocal.m4 and the configure script.
		<tip>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.</tip>
		</para>
		
		
		<para>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. <emphasis>Create the following Makefile.am</emphasis> :
		</para>
		<programlisting>
			Makefile.am: 
		
		
			bin_PROGRAMS = tut_prog			
			tut_prog_SOURCES = main.c
		</programlisting>
		<para>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 <emphasis>how</emphasis> that will be built: 
		automake will figure it out. We have'nt even mentioned the compiler in this pre-makefile.
		</para>
		<para>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).
		</para>
		<para>It's now time to run 'automake'.
		But first <emphasis>create some empty files</emphasis>:  NEWS, README, AUTHORS and ChangeLog:
		<screen><prompt>$</prompt><userinput>touch NEWS README AUTHORS ChangeLog</userinput></screen>
		because automake complains if they are absent. Now <emphasis>run 'automake -a'</emphasis>
		(-a stands for --add-missing: some files needed internally are not present in the directory.).
		</para>
		<para>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).
		<tip>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.</tip>		
		</para>
		<para>
		Everything is now ready for configure to run. <emphasis>Run './configure'.</emphasis>
		<screen><prompt>$ ./configure</prompt>
			<userinput>
			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
			</userinput>
		</screen>
		As planned, configure checked various things, like the compiler.
		Using the data it acquired from that scanning, it created 'Makefile'
		from Makefile.in. You can compare these two big files : they are really
		similar.
		</para>
		<para>
			You can now <emphasis>Run 'make'.</emphasis>
			<screen><prompt>$ make</prompt>
			<userinput>
			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			
			</userinput>
			</screen>
		Quite complicated, but it works. Launch the binary 'tut_prog' if you like.
		Note the -D switches passed to gcc: they
		correspond to #define in a C program. For instance, thanks to
		<userinput>-DPACKAGE=\"tut_prog\"</userinput> everything is as if main.c contained:
		<programlisting> #define PACKAGE "tut_prog" </programlisting>
		Thus, you can add the following line to main.c:
		<programlisting>printf("This package is %s\n", PACKAGE);</programlisting>
		Then re-run make and re-run tut_prog:
		<screen>
				<prompt>$ make</prompt>
				<userinput> -- make output cut --</userinput>
				<prompt>$ ./tut_prog</prompt>
				<userinput> 
					Hello world!
					This package is tut_prog
				</userinput>
		</screen>
		How did that string 'tut_prog' come from configure.in's AM_INIT_AUTOMAKE ? 
		A 'PACKAGE' variable containing "tut_prog" has been created in 'configure', 
		and put in Makefile while configure processed Makefile.in.
		Many communications between 'configure' and your program work that way.
		</para>
		<para>
		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 :)
		</para>
		
		<para> For things to be even clearer, you can take a look at the 
		<ulink type="http" url="http://sources.redhat.com/autobook/autobook/autobook_276.html#SEC276">
		dependencies</ulink>
		amongst the various files in this chapter of the <emphasis>Autobook</emphasis>.
		</para>
		
	</sect1>
	
	
	<sect1 id="same-thing-with-anjuta">
		<title> The same thing with Anjuta </title>
		<para> Let's see how does Anjuta handle a very simple project containing
		only the main.c file we used in the previous section.
		<emphasis>Launch Anjuta, create a new project of type 'Generic/Terminal project.'
		</emphasis>
		</para>
		<figure>
	   	<screenshot>	     	
				<graphic fileref="figures/aat_project_type.png" format="PNG"></graphic>			
			</screenshot>		
		</figure>
		<para><emphasis>Call it 'tut_prog' and let it be a C-only project.</emphasis>
		Enter no comment, <emphasis> uncheck copyright statement and gettext support</emphasis>
		since we want to keep things as simple as possible.				
		</para>
		<figure>
	   	<screenshot>	     	
				<graphic fileref="figures/aat_additional_options.png" format="PNG"></graphic>			
			</screenshot>		
		</figure>
		
		<para>
		<emphasis>Complete the remaining steps of the application wizard</emphasis>; 
		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:
		</para> 		
		<screen>
		<userinput>
		**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.
		</userinput>
		</screen>
		
		<para>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.
		</para>
		<para> <emphasis>libtoolize</emphasis> is provided by <application>libtool</application>. Its goal is to
		make library using easier, we will look at it later.</para>
		<para> <emphasis>autoheader</emphasis> 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:
		</para>
		<screen>
		<userinput>
			-- various #defines --
			
			/* Define to 1 if you have the &lt;stdlib.h&gt; 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 --
		</userinput>
		</screen>
		<para>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.
		</para>
		<para>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).</para>
		<para>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 <application>autoconf</application> and <application>automake</application>.
		</para>
	</sect1>
	
	
	<sect1 id="references">
		<title>References</title>
		<para> Here are some links to reference documents dealing with the autotools in general, and
		<application>autoconf</application> and <application>automake</application> in particular.
		</para>
				
		<variablelist>
			<varlistentry>
				<term>English</term>

				<listitem><para>The 
					<ulink type="http" url="http://sources.redhat.com/autobook/autobook/autobook_toc.html">
					Autobook</ulink> explains in details how the autotools work.</para>
				</listitem>
				<listitem><para>You can take a look at the
					<ulink type="http" url="http://www.gnu.org/software/autoconf/manual/autoconf-2.57/autoconf.html">
					Autoconf</ulink> or
					<ulink type="http" url="http://www.gnu.org/software/automake/manual/automake.html">
					Automake</ulink> manuals.</para>
				</listitem>

				<listitem><para><ulink type="http" url="http://nis-www.lanl.gov/~rosalia/mydocs/autoconf_tutorial_toc.html">
					Here</ulink> is a tutorial about using autoconf alone.</para>
				</listitem>

				<listitem><para>Amongst the various GNU development
					tools you are told about<ulink type="http" url="http://autotoolset.sourceforge.net/tutorial.html">					
					here</ulink> are autoconf and automake.</para>
				</listitem>							
					
			</varlistentry>
				
			<varlistentry>
				<term>French</term>
				<listitem><para><ulink type="http" url="http://www.infres.enst.fr/~dax/polys/configure/slide1.html">
					Here</ulink> are some slides by a teacher from Ecole Nationale Supérieure des Télecoms
					about the autotools.</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term>Japanese</term>				
				<listitem>
				<ulink type="http" url="http://larse-gtk.hp.infoseek.co.jp/automake.html">
				A tutorial about autoconf and automake</ulink>.</listitem>
			</varlistentry>
		</variablelist>
		
		<para>Please e-mail  <ulink url="mailto://opincon@wanadoo.fr">me</ulink> /* how can that be done ? */ if one of these links
		is broken, or if you know other ones.</para>
	</sect1>
</chapter>


<!-- Using libraries -->
<chapter id="libraries">
	<title>Using libraries</title>
	<para> When producing real-life software, you will need libraries. If you want to parse
	some XML, you might want to use libxml2; if you're programming a game you could link
	your program to SDL or OpenGL.</para>
	<para>In this chapter you will learn how to use shared libraries with Anjuta.</para>
	
	<sect1 id="libtool">
		<title>Some points about libtool</title>
		<para><application>libtool</application> is a portability layer which makes library
		access easier, since it hides the differences between the various Unix variants
		in this particular domain.</para>
		<para>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 
		<ulink type="http" url="http://www.gnu.org/software/libtool/manual.html">manual</ulink>
		to understand its ins and outs.</para>		
	</sect1>
	
	<sect1 id="first-example">
		<title>First example: using libxml2 with pkg-config</title>
		
		<para> <application>libxml2</application> allows you to parse and produce XML files,
		which can be very useful nowadays (see its <ulink type="http" url="www.xmlsoft.org">
		homepage at www.xmlsoft.org</ulink>). Let's see how to use it with Anjuta.</para>
		
		<para><emphasis>Open our tut_prog project, and replace main.c by this one :</emphasis>
		<programlisting role="C">
			main.c: 
		
			#include &lt;libxml/parser.h&gt;			
			#include &lt;stdio.h&gt;
			
			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;
				}
			}
        	
		</programlisting>
		Our goal is now to compile it and make it work correctly. For that purpose, we must
		tell gcc two things: where to find libxml/parser.h (that is to say, give gcc
		the right include path) and what library (i.e. shared object) it should link
		our project against. There are several ways to do that, I will mention two of them.
		</para>
		<sect2 id="the-lame-way">
			<title>The lame way</title>
			<para>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).
			Let's indicate it to Anjuta.</para>
			
			<para><emphasis>In the 'Settings' menu, select 'Compiler and Linker Settings...'.
			Select the 'Include Paths' tab, and add '/usr/include/libxml2' (or your 
			corresponding include path) in the list.</emphasis></para>
			
			<figure>
	   	<screenshot>	     	
				<graphic fileref="figures/aat_include_paths.png" format="PNG"></graphic>			
			</screenshot>		
			</figure>
			
			<para>Likewise, if the shared object is in an unusual directory, we should add it
			in the 'Library Paths' tab. It is not the case here since gcc always look in
			/usr/lib.</para>
			
			<para>Finally we must indicate the shared object itself in the 'Libraries' tab.
			You can <emphasis>enter 'xml2'</emphasis> by hand or select it in the list if present.			
			<figure>
	   	<screenshot>	     	
				<graphic fileref="figures/aat_libraries.png" format="PNG"></graphic>			
			</screenshot>		
			</figure>			
			</para>
					
			<para>What we have just typed is now reflected in src/Makefile.am.
			Indeed, take a look at it: you will see something like:
			</para>
			<programlisting>
				INCLUDES =\
					-I/usr/include/libxml2
			</programlisting>
			and like:
			<programlisting>
				tut_prog_LDADD = \
					-lxml2
			</programlisting>
			<para>
			For changes to be taken into account, you must re-run automake; in Anjuta
			you can run 'Auto generate' in the Build menu. Then, building should work;
			that's done, you can parse XML files.
			</para> 			
			<para> This approach works, but it has several drawbacks:
				<itemizedlist>
					<listitem><para>It is not portable to various linuxes: perhaps on other
					distros the include path is different.					
					</para></listitem>
					<listitem><para>If the next versions of libxml have different paths,
					or different needed libraries, we will have to keep track of it in Anjuta.
					</para></listitem>
					<listitem><para>We don't test whether the system of the packager/user has
					the library.
					</para></listitem>
					<listitem><para>We cannot check the version if the libxml2 we use.
					</para></listitem>
					<listitem><para>It's ugly !</para></listitem>
				</itemizedlist>
			</para>
			<para>As you might have guessed, using the autotools will be far better.</para>
		</sect2>
		<sect2 id="the-right-way">
			<title>The Right Way(tm)</title>
			<para>We will now use autoconf's capabilities. <emphasis>Undo what you have just done
			</emphasis>(that is to say, remove what you typed in the 'Compiler and Linker Settings'
			dialog box).<emphasis>Open 'Configure Project' in the 'Project' menu.</emphasis> 
			Here we can tweak the interaction between Anjuta and the autotools.
			<emphasis>Select the 'Configuration' tab.</emphasis> In these subtabs you can
			type things to add in configure.in, in different sections delimited by comments
			(take a look at configure.in to see that).
			<emphasis>Type the following in 'Libraries': </emphasis>
	   	<screenshot>	     	
				<graphic fileref="figures/aat_config_libraries_libxml2.png" format="PNG"></graphic>			
			</screenshot>		
			<emphasis>Now validate, re-open the 'Compiler and linker settings' dialog, and
			type the following in the 'Options' tab:</emphasis>
			<screenshot>	     	
				<graphic fileref="figures/aat_options_libxml2.png" format="PNG"></graphic>			
			</screenshot>
			These two fields go straight in src/Makefile.am (give it a glance).
			Now you can regen the project and build it: it should work.
			</para>
			<para>So what happened ? First, libxml2 is handled by <application>pkg-config
			</application> which provides m4 macros for autoconf, like PKG_CHECK_MODULES
			(see pkg-config man page for details on this macro and others). With this macro,
			configure will check for a minimal version of libxml2 and set the shell variables
			xml_CFLAGS and xml_LIBS (since the first parameter of the macro is
			'xml') to the C flags and library switches needed by gcc. Look at the output of 
			'configure':</para>
			<screen>
			<userinput>
			checking for pkg-config... /usr/bin/pkg-config
			checking for libxml-2.0 &gt;= 2.4... yes
			checking xml_CFLAGS... -I/usr/include/libxml2
			checking xml_LIBS... -lxml2 -lpthread -lz -lm
			</userinput>
			</screen>
			<para>AC_SUBST(xml_CFLAGS) tells configure to replace ocurrences of @xml_CFLAGS@
			in the various Makefile.in by the the contents of the shell variable xml_CFLAGS
			(i.e. "-I/usr/include/libxml2").</para>
			<para>Let's recap: in src/Makefile.am we have a $(xml_CFLAGS) (which is from 
			the 'Compiler and linker setting' dialog). When automake is run, it produces src/Makefile.in
			and we get @xml_CFLAGS@. Finally, configure transforms @xml_CFLAGS@ in its true
			value : -I/usr/include/libxml2. Of course, the same reasoning holds for xml_LIBS.
			</para>
			<para>Now we have a flexible and robust way to use libxml2.</para>
		</sect2>
	</sect1>
	<sect1 id="3ds">
		<title>Using lib3ds: a m4 file is provided</title>
		<para><application>lib3ds</application> allows you to handle 3DS files.
		We will try to build and run the following code :</para>
		<programlisting role="C">
			main.c: 
		
			#include &lt;lib3ds/types.h&gt;
			#include &lt;lib3ds/file.h&gt;
			#include &lt;stdio.h&gt;
						
			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;
				}
			}        	
		</programlisting>
		<para>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.<para>
		<para>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 !</para>
		</para>Given this, it seems reasonable to use the macro the following way :</para>
		<screenshot>	     	
				<graphic fileref="figures/aat_config_libraries_lib3ds.png" format="PNG"></graphic>			
		</screenshot>
		<para>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):</para>
		<screenshot>	     	
				<graphic fileref="figures/aat_options_lib3ds.png" format="PNG"></graphic>			
		</screenshot>
		<para>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.</para>		
	</sect1>	
	<sect1 id="other-macros">
			<title>Macros for other libraries</title>
			<para>More generally, to use a library with the help of autoconf, check the
			following:</para>
			<itemizedlist>
					<listitem><para>If the library is handled by pkg-config, just
					use the PKG_CHECK_MODULES macros as we did in the section above.
					</para></listitem>
					<listitem><para>Check if the library author shipped a .m4 macro, and use
					it if present.
					</para></listitem>
					<listitem><para>If your library is a basic one, it might be checked
					by the standard autoconf macros (see the list 
					<ulink type="http" url="http://sources.redhat.com/autobook/autobook/autobook_283.html#SEC283">
					here</ulink>).
					</para></listitem>
					<listitem><para>Perhaps the m4 you need has already be programmed by someone
					else. Look at the contributions <ulink type="http" url="http://www.gnu.org/software/ac-archive/">here</ulink>.
					</para></listitem>
					<listitem><para>If all that fail, go deeper in m4, make your own macro, and
					donate it to the library's author !
					</para></listitem>
			</itemizedlist>		
	</sect1>		
</chapter>

<chapter id="future">
	<title>The future of this tutorial</title>
	<para>Depending on the readers' feedback, I might work again on this tutorial.
		I could for instance explain some gettext and i18n.
	</para>
	<para>Feel free to send comments to opincon hat wanadoo.fr</para>
</chapter>


</book>
