Editing Documentation/Maemo 5 Developer Guide/GNU Build System

Warning: You are not logged in. Your IP address will be recorded in this page's edit history.

Warning: This page is 101 kilobytes long; some browsers may have problems editing pages approaching or longer than 32kb. Please consider breaking the page into smaller sections.

The edit can be undone. Please check the comparison below to verify that this is what you want to do, and then save the changes below to finish undoing the edit.

Learn more about Contributing to the wiki.

= GNU Build System =

The following code examples are used in this chapter:

* [https://garage.maemo.org/svn/maemoexamples/trunk/simple-make-files/ simple-make-files]
* [https://garage.maemo.org/svn/maemoexamples/trunk/autoconf-automake/ autoconf-automake]
 
= GNU Make and Makefiles =

The ''make'' program from the GNU project is a powerful tool to aid implementing automation in the software building process. Beside this, it can be used to automate any task that uses files and in which these files are transformed into some other form. Make by itself does not know what the files contain or what they represent, but using a simple syntax it can be taught how to handle them.

When developing software with gcc (and other tools), gcc will often be invoked repeatedly with the same parameters and flags. After changing one source file, it will be noticed that other output files need to be rebuilt, and even the whole application if some interface has changed between the functions. This might happen whenever declarations change, new parameters are added to function prototypes etc.

These tasks could, of course, be always performed manually, but after a while a nicer way is going to be more desirable.

GNU make is a software building automation tool that will execute repetitive tasks. It is controlled via a '''Makefile''' that contains lists of dependencies between different source files and output files. It also contains lists of commands that should be executed to satisfy these dependencies. Make uses the '''timestamps''' of files and the information of the files' existence to automate the rebuilding of applications (targets in make), as well as the rules that are specified in the Makefile.

Make can be used for other purposes as well. A target can easily be created for installing the built software on a destination computer, a target for generating documentation by using some automatic documentation generation tool, etc. Some people use make to keep multiple Linux systems up to date with the newest software and various system configuration changes. In short, make is flexible enough to be generally useful.

The dependencies between different files making up a software project:

<div align="CENTER">[[Image:make.png|Image make]]</div>

The aim of make is to satisfy the target. Each target has its own dependencies. A user will generally select a target for make to satisfy by supplying the target name on the command line. Make will start by checking, whether all of the dependencies exist and have an older timestamp than the target. If so, make will do nothing, as nothing has changed. However, since a header file (that an application is not dependent on directly) might change, make will propagate the changes to the 'root' of the target as shown in the picture above.

Make will rebuild all of the necessary dependencies and targets on the way towards the target. This way, make will only rebuild those dependencies that actually affect something, and thus, will save time and effort. In big projects, the amount of time saved is significant.

To illustrate this, suppose that '''file3.c''' in the above picture is modified. After that, make is run, and it will automatically rebuild the necessary targets ('''file3.o''', '''libutil.a''' and '''app'''):

<div align="CENTER">[[Image:make-mod1.png|Image make-mod1]]</div>

Now suppose that another function is added to '''file1.c'''. Then also '''util.h''' would need to be modified accordingly. The picture shows that quite many objects and targets depend on this header file, so a sizable number of objects need to be rebuilt (but not all):

<div align="CENTER">[[Image:make-mod2.png|Image make-mod2]]</div>

N.B. In the example pictures, there is a project with a custom static library, which will be linked against the test application.

== Simple Real Example ==

Before delving too deeply into the syntax of makefiles, it is instructive to first see make in action. For this, a simple project will be used, written in the C language.

In C, it is customary to write "header" files (conventional suffix for them is '''.h''') and regular source files ('''.c'''). The header files describe calling conventions, APIs and structures that are to be made usable for the outside world. The .c files contain the implementation of these interfaces.

The first rule in this is: if something is changed in the interface file, then the binary file containing the code implementation (and other files that use the same interface) should be regenerated. Regeneration in this case means invoking gcc to create the binary file out of the C-language source file.

Make needs to be told two things at this point:

* If a file's content changes, which other files will be affected? Since a single interface will likely affect multiple other files, make uses a reversed ordering here. For each resulting file, it is necessary to list the files on which this one file depends on.
* What are the commands to regenerate the resulting files when the need arises?

This example deals with that as simply as possible. There is a project that consists of two source files and one header file. The contents of these files are listed below: simple-make-files/hello.c

<tt>''/**''
 '' * The old faithful hello world.''
 '' *''
 '' * This maemo code example is licensed under a MIT-style license,''
 '' * that can be found in the file called "License" in the same''
 '' * directory as this file.''
 '' * Copyright (c) 2007-2008 Nokia Corporation. All rights reserved.''
 '' */''
 '''<nowiki>#include</nowiki>''' &lt;stdlib.h&gt; ''/* EXIT_* */''
 '''<nowiki>#include</nowiki>''' "hello_api.h" ''/* sayhello */''
 int '''main'''(int argc, char <nowiki>**</nowiki>argv) {
 '''sayhello'''();
 '''return''' EXIT_SUCCESS<nowiki>;</nowiki>
 }
 </tt>

simple-make-files/hello_func.c

<tt>''/**''
 '' * Implementation of sayhello.''
 '' *''
 '' * This maemo code example is licensed under a MIT-style license,''
 '' * that can be found in the file called "License" in the same''
 '' * directory as this file.''
 '' * Copyright (c) 2007-2008 Nokia Corporation. All rights reserved.''
 '' */''
 
 '''<nowiki>#include</nowiki>''' &lt;stdio.h&gt; ''/* printf */''
 '''<nowiki>#include</nowiki>''' "hello_api.h" ''/* sayhello declaration */''
 
 void '''sayhello'''(void) {
 '''printf'''("Hello world!\n");
 }
 </tt>

simple-make-files/hello_api.h

<tt>''/**''
 '' * Interface description for the hello_func module.''
 '' *''
 '' * This maemo code example is licensed under a MIT-style license,''
 '' * that can be found in the file called "License" in the same''
 '' * directory as this file.''
 '' * Copyright (c) 2007-2008 Nokia Corporation. All rights reserved.''
 '' */''
 
 '''<nowiki>#ifndef</nowiki>''' INCLUDE_HELLO_API_H
 '''<nowiki>#define</nowiki>''' INCLUDE_HELLO_API_H
 ''/* The above is protection against circular header inclusion. */''
 
 ''/* Function to print out "Hello world!\n". */''
 '''extern''' void '''sayhello'''(void);
 
 '''<nowiki>#endif</nowiki>'''
 ''/* ifndef INCLUDE_HELLO_API_H */''
 </tt>

So, in effect, there is the main application in '''hello.c''', which uses a function that is implemented in '''hello_func.c''' and declared in '''hello_api.h'''. Building an application out of these files could be performed manually like this:

gcc -Wall hello.c hello_func.c -o hello

Or, it could be done in three stages:

gcc -Wall -c hello.c -o hello.o
 gcc -Wall -c hello_func.c -o hello_func.o
 gcc -Wall hello.o hello_func.o -o hello

In both cases, the resulting application ('''hello''') will be the same.

In the first case, gcc is instructed to process all source files in one go, link the resulting object code and store that code (program in this case) into '''hello'''.

In the second case, gcc is instructed to create a binary object file for each of the source files. After that, gcc is instructed to link these output files ('''hello.o''' and '''hello_func.o''') together, and store the linked code into '''hello'''.

N.B. When gcc reads through the C source files, it will also read in the header files, since the C code uses the #include -preprocessor directive. This is because gcc will internally run all files ending with .c through cpp (the preprocessor) first.

The file describing this situation to make is as follows: simple-make-files/Makefile

<tt>''<nowiki># define default target (first target = default)</nowiki>''
 ''<nowiki># it depends on 'hello.o' (which will be created if necessary)</nowiki>''
 ''<nowiki># and hello_func.o (same as hello.o)</nowiki>''
 hello<nowiki>:</nowiki> hello.o hello_func.o
 gcc -Wall hello.o hello_func.o -o hello
 ''<nowiki># define hello.o target</nowiki>''
 ''<nowiki># it depends on hello.c (and is created from it)</nowiki>''
 ''<nowiki># also depends on hello_api.h which would mean that</nowiki>''
 ''<nowiki># changing the hello.h api would force make to rebuild</nowiki>''
 ''<nowiki># this target (hello.o).</nowiki>''
 ''<nowiki># gcc -c: compile only, do not link</nowiki>''
 hello.o<nowiki>:</nowiki> hello.c hello_api.h
 gcc -Wall -c hello.c -o hello.o
 ''<nowiki># define hello_func.o target</nowiki>''
 ''<nowiki># it depends on hello_func.c (and is created from)</nowiki>''
 ''<nowiki># and hello_api.h (since that's its declaration)</nowiki>''
 hello_func.o<nowiki>:</nowiki> hello_func.c hello_api.h
 gcc -Wall -c hello_func.c -o hello_func.o
 ''<nowiki># </nowiki>''</tt>

This file is in the simplest form without using any variables or relying on built-in magic in GNU make. Later it will be shown that the same rules could be written in a much shorter way.

This makefile can be tested by running make in the directory that contains the makefile and the source files:

user@system:~$ make
 gcc -Wall -c hello.c -o hello.o
 gcc -Wall -c hello_func.c -o hello_func.o
 gcc -Wall hello.o hello_func.o -o hello

The resulting files after running make:
 user@system:~$ ls -la
 total 58
 drwxr-xr-x 3  user user 456  Aug 11 15:04 .
 drwxr-xr-x 13 user user 576  Aug 11 14:56 ..
 -rw-r--r-- 1  user user 699  Jun 1  14:48 Makefile
 -rwxr-xr-x 1  user user 4822 Aug 11 15:04 hello
 -rw-r--r-- 1  user user 150  Jun 1  14:48 hello.c
 -rw-r--r-- 1  user user 824  Aug 11 15:04 hello.o
 -rw-r--r-- 1  user user 220  Jun 1  14:48 hello_api.h
 -rw-r--r-- 1  user user 130  Jun 1  14:48 hello_func.c
 -rw-r--r-- 1  user user 912  Aug 11 15:04 hello_func.o

Executing the binary:

user@system:~$ ./hello
 Hello world!

== Anatomy of Makefile ==

From the simple example above, some of syntax of 'make' can be deduced.

Here are the rules that can be learned:

* Comments are lines that start with the #-character. To be more precise, when make reads the makefile, it will ignore the #-character and any characters after it up to the end of the line. This means that comments can also be put at the end of lines, and make will ignore them, but this is considered bad practice as it would lead to subtle problems later on.
* The backslash character (<code>\</code>) can be used to escape the special meaning of the next character. The most important special character in makefiles is the dollar character ($), which is used to access the contents of variables. There are also other special characters. To continue a line that is too long, the newline character can be escaped on that line. When the backslash is put at the end of the line, make will ignore the newline when reading input.
* Empty lines by themselves are ignored.
* A line that starts at column 0 (start of the line) and contains a colon character (:) is considered a rule. The name on the left side of the colon is created by the commands. This name is called a target. Any filenames specified after the colon are the files that the target depends on. They are called prerequisites (i.e. they are required to exist, before make decides to create the target.
* Lines starting with the tabulation character (tab) are commands that make will run to achieve the target.

In the printed material, the tabs are represented with whitespace, so be careful when reading the example makefiles. Note also that in reality, the command lines are considered as part of the rule.

Using these rules, it can now be deduced that:

* make will regenerate '''hello''' when either or both of its prerequisites change. So, if either '''hello.o''' or '''hello_func.o''' change, make will regenerate '''hello''' by using the command: <code>gcc -Wall hello.o hello_func.o -o hello</code>
* If either '''hello.c''' or '''hello_api.h''' change, make will regenerate '''hello.o'''.
* If either '''hello_func.c''' or '''hello_api.h''' change, make will regenerate '''hello_func.o'''.

== Default Goal ==

It should be noted that make was not explicitly told what it should do by default when run without any command line parameters (as was done above). How does it know that creating '''hello''' is the target for the run?

The first target given in a makefile is the default target. A target that achieves some higher-level goal (like linking all the components into the final application) is sometimes called a goal in GNU make documentation.

So, the first target in the makefile is the default goal when make is run without command line parameters.

N.B. In a magic-like way, make will automatically learn the dependencies between the various components and deduce that in order to create '''hello''', it will also need to create '''hello.o''' and '''hello_func.o'''. Make will regenerate the missing prerequisites when necessary. In fact, this is a quality that causes make do its magic.

Since the prerequisites for hello (hello.o and hello_func.o) do not exist, and hello is the default goal, make will first create the files that the hello target needs. This can be evidenced from the screen capture of make running without command line parameters. It shows the execution of each command in the order that make decides is necessary to satisfy the default goal's prerequisites, and finally create the hello.

user@system:~$ make
 gcc -Wall -c hello.c -o hello.o
 gcc -Wall -c hello_func.c -o hello_func.o
 gcc -Wall hello.o hello_func.o -o hello

== Names of Makefiles ==

The recommended name for the makefile is '''Makefile'''. This is not the first filename that GNU make will try to open, but it is the most portable one. In fact, the order of filenames that make attempts to open is: '''GNUMakefile''', '''Makefile''' and finally '''makefile'''.

Unless one is sure that one's makefile will not work on other make systems (not GNU), one should refrain from using GNUMakefile. Makefile will be used here for the most of this material. The idea behind using Makefile instead of makefile is related to how shells and commands sort filenames, when contents of directories are requested. Since in ASCII the uppercase letters come before the lowercase letters, the important files are listed first. Makefiles are considered important, since they are the basis for building the project. (The collation order might be different in your locale and your environment.)

Make can explicitly be told which file to read by using the -f command line option. This option will be used in the next example.

== Questions ==

Based on common sense, what should make do when it is run after:

* Deleting the hello file?
* Deleting the hello.o file?
* Modifying hello_func.c?
* Modifying hello.c?
* Modifying hello_api.h?
* Deleting the Makefile?

What would be done when writing the commands manually?

== Adding Make Goals ==

Sometimes it is useful to add targets, whose execution does not result in a file, but instead causes some commands to be run. This is commonly used in makefiles of software projects to get rid of the binary files, so that building can be attempted from a clean state. These kinds of targets can also be justifiably called goals. GNU documentation uses the name "phony target" for these kinds of targets, since they do not result in creating a file, like normal targets do.

The next step is to create a copy of the original makefile, and add a goal that will remove the binary object files and the application. N.B. Other parts of the makefile do not change. simple-make-files/Makefile.2

<tt>''<nowiki># add a cleaning target (to get rid of the binaries)</nowiki>''
 ''<nowiki># define default target (first target = default)</nowiki>''
 ''<nowiki># it depends on 'hello.o' (which must exist)</nowiki>''
 ''<nowiki># and hello_func.o</nowiki>''
 hello<nowiki>:</nowiki> hello.o hello_func.o
 gcc -Wall hello.o hello_func.o -o hello
 ''<nowiki># define hello.o target</nowiki>''
 ''<nowiki># it depends on hello.c (and is created from)</nowiki>''
 ''<nowiki># also depends on hello_api.h which would mean that</nowiki>''
 ''<nowiki># changing the hello.h api would force make to rebuild</nowiki>''
 ''<nowiki># this target (hello.o).</nowiki>''
 ''<nowiki># gcc -c: compile only, do not link</nowiki>''
 hello.o<nowiki>:</nowiki> hello.c hello_api.h
 gcc -Wall -c hello.c -o hello.o
 ''<nowiki># define hello_func.o target</nowiki>''
 ''<nowiki># it depends on hello_func.c (and is created from)</nowiki>''
 ''<nowiki># and hello_api.h (since that's it's declaration)</nowiki>''
 hello_func.o<nowiki>:</nowiki> hello_func.c hello_api.h
 gcc -Wall -c hello_func.c -o hello_func.o
 ''<nowiki># This is the definition of the target 'clean'</nowiki>''
 ''<nowiki># Here we'll remove all the built binaries and</nowiki>''
 ''<nowiki># all the object files that we might have generated</nowiki>''
 ''<nowiki># Notice the -f flag for rm, it means "force" which</nowiki>''
 ''<nowiki># in turn means that rm will try to remove the given</nowiki>''
 ''<nowiki># files, and if there are none, then that's ok. Also</nowiki>''
 ''<nowiki># it means that we have no writing permission to that</nowiki>''
 ''<nowiki># file and have writing permission to the directory</nowiki>''
 ''<nowiki># holding the file, rm will not then ask for permission</nowiki>''
 ''<nowiki># interactivelly.</nowiki>''
 clean<nowiki>:</nowiki>
 rm -f hello hello.o hello_func.o
 </tt>

In order for make to use this file instead of the default Makefile, the -f command line parameter needs to be used as follows:

user@system:~$ make -f Makefile.2
 gcc -Wall -c hello.c -o hello.o
 gcc -Wall -c hello_func.c -o hello_func.o
 gcc -Wall hello.o hello_func.o -o hello

To control which target make will process (instead of the default goal), target name needs to be given as command line parameter like this:
 user@system:~$ make -f Makefile.2 clean
 rm -f hello hello.o hello_func.o

No binary files remain in the directory:
 user@system:~$ ls -la
 total 42
 drwxr-xr-x 3  user user 376  Aug 11 15:08 .
 drwxr-xr-x 13 user user 576  Aug 11 14:56 ..
 -rw-r--r-- 1  user user 699  Jun 1  14:48 Makefile
 -rw-r--r-- 1  user user 1279 Jun 1  14:48 Makefile.2
 -rw-r--r-- 1  user user 150  Jun 1  14:48 hello.c
 -rw-r--r-- 1  user user 220  Jun 1  14:48 hello_api.h
 -rw-r--r-- 1  user user 130  Jun 1  14:48 hello_func.c

== Making One Target at a Time ==

Sometimes it is useful to ask make to process only one target. Similar to the clean case, it just needs the target name to be given on the command line:

user@system:~$ make -f Makefile.2 hello.o
 gcc -Wall -c hello.c -o hello.o

Multiple target names can also be supplied as individual command line parameters:

user@system:~$ make -f Makefile.2 hello_func.o hello
 gcc -Wall -c hello_func.c -o hello_func.o
 gcc -Wall hello.o hello_func.o -o hello

This can be done with any number of targets, even phony ones. Make will try and complete all of them in the order that they are on the command line. Should any of the commands within the targets fail, make will abort at that point, and will not pursue the rest of the targets.

==PHONY Keyword ==

Suppose that for some reason or another, a file called '''clean''' appears in the directory in which make is run with clean as the target. In this case, make would probably decide that since clean already exists, there is no need to run the commands leading to the target, and in this case, make would not run the rm command at all. Clearly this is something that needs to be avoided.

For these cases, GNU make provides a special target called '''.PHONY''' (note the leading dot). The real phony targets (clean) will be listed as a dependency to .PHONY. This will signal to make that it should never consider a file called clean to be the result of the phony target.

In fact, this is what most open source projects that use make do.

This leads in the following makefile (comments omitted for brevity): simple-make-files/Makefile.3

<tt>hello<nowiki>:</nowiki> hello.o hello_func.o
 gcc -Wall hello.o hello_func.o -o hello
 hello.o<nowiki>:</nowiki> hello.c hello_api.h
 gcc -Wall -c hello.c -o hello.o
 hello_func.o<nowiki>:</nowiki> hello_func.c hello_api.h
 gcc -Wall -c hello_func.c -o hello_func.o
 .PHONY<nowiki>:</nowiki> clean
 clean<nowiki>:</nowiki>
 rm -f hello hello.o hello_func.o
 </tt>

== Specifying Default Goal ==

Make will use the first target in a makefile as its default goal. What if there is a need to explicitly set the default goal instead? Since it is not possible to actually change the "first target is the default goal" setting in make, this needs to be taken into account. So, a new target has to be added, and made sure that it will be processed as the first target in a makefile.

In order to achieve this, a new phony target should be created, and the wanted targets should be listed as the phony target's prerequisites. Any name can be used for the target, but all is a very common name for this use. The only thing that needs to be rememberd is that this target needs to be the first one in the makefile. simple-make-files/Makefile.4

<tt>.PHONY<nowiki>:</nowiki> all
 all<nowiki>:</nowiki> hello
 hello<nowiki>:</nowiki> hello.o hello_func.o
 gcc -Wall hello.o hello_func.o -o hello
 hello.o<nowiki>:</nowiki> hello.c hello_api.h
 gcc -Wall -c hello.c -o hello.o
 hello_func.o<nowiki>:</nowiki> hello_func.c hello_api.h
 gcc -Wall -c hello_func.c -o hello_func.o
 .PHONY<nowiki>:</nowiki> clean
 clean<nowiki>:</nowiki>
 rm -f hello hello.o hello_func.o
 </tt>

Something peculiar can be seen in the listing above. Since the first target is the default goal for make, would that not make .PHONY now to be the default target? Since .PHONY is a special target in GNU make, this is safe. Also, because of compatibility reasons, GNU make will ignore any targets that start with a leading dot (.) when looking for the default goal.

== Other Common Phony Goals ==

Many other phony goals will be encountered in makefiles that projects use.

Some of the more common ones include:

* install: Prerequisites for install is the software application binary (or binaries). The commands (normally ''install'' is used on Linux) will specify which binary file to place under which directory on the system (/usr/bin, /usr/local/bin, etc).
* distclean: Similar to clean; removes object files and such, but removes other files as well (sounds scary). Normally this is used to implement the removal of Makefile in the case that it was created by some automatic tool (''configure'' for example).
* package: Prerequisites are as in install, but instead of installing, creates an archive file (''tar'') with the files in question. This archive can then be used to distribute the software.

Other common phony targets can be found in the [http://www.gnu.org/software/make/manual/make.html GNU make manual].

==  Variables in Makefiles ==

So far these files have been listing filenames explicitly. Writing makefiles this way can get rather tedious, if not error prone.

This is why all make programs (not just the GNU variant) provide variables. Some other make programs call them macros.

Variables work almost as they do inside regular UNIX command shells. They are a simple mechanism, by which a piece of text can be associated with a name that can be referenced later on in multiple places in the makefiles. Make variables are based on text replacement, just like shell variables are.

== Variable Flavors ==

The variables that can be used in makefiles come in two basic styles or flavors.

The default flavor is where referencing a variable will cause make to expand the variable contents at the point of reference. This means that if the value of the variable is some text in which other variables are referenced, their contents will also be replaced automatically. This flavor is called recursive.

The other flavor is simple, meaning that the content of a variable is evaluated only once, when the variable is defined.

Deciding on which flavor to use might be important, when the evaluation of variable contents needs to be repeatable and fast. In these cases, simple variables are often the correct solution.

== Recursive Variables ==

Here are the rules for creating recursive variables:

* Names must contain only ASCII alphanumerics and underscores (to preserve portability).
* Only lowercase letters should be used in the names of the variables. Make is case sensitive, and variable names written in capital letters are used when it is necessary to communicate the variables outside make, or their origin is from outside (environment variables). This is, however, only a convention, and there will also be variables that are local to the makefile, but still written in uppercase.
* Values may contain any text. The text will be evaluated by make when the variable is used, not when it is defined.
* Long lines may be broken up with a backslash character (<code>\</code>) and newline combination. This same mechanism can be used to continue other long lines as well (not just variables). Do not put any whitespace after the backslash.
* A variable that is being defined should not be referenced in its text portion. This would result in an endless loop whenever this variable is used. If this happens GNU make will stop to an error.

Now the previously used makefile will be reused, but some variables will be introduced. This also shows the syntax of defining the variables, and how to use them (reference them): simple-make-files/Makefile.5

<tt>''<nowiki># define the command that we use for compilation</nowiki>''
 CC <nowiki>=</nowiki> gcc -Wall
 ''<nowiki># which targets do we want to build by default?</nowiki>''
 ''<nowiki># note that 'targets' is just a variable, its name</nowiki>''
 ''<nowiki># does not have any special meaning to make</nowiki>''
 targets <nowiki>=</nowiki> hello
 ''<nowiki># first target defined will be the default target</nowiki>''
 ''<nowiki># we use the variable to hold the dependencies</nowiki>''
 .PHONY<nowiki>:</nowiki> all
 all<nowiki>:</nowiki> $(targets)
 hello<nowiki>:</nowiki> hello.o hello_func.o
 $(CC) hello.o hello_func.o -o hello
 hello.o<nowiki>:</nowiki> hello.c hello_api.h
 $(CC) -c hello.c -o hello.o
 hello_func.o<nowiki>:</nowiki> hello_func.c hello_api.h
 $(CC) -c hello_func.c -o hello_func.o
 ''<nowiki># we'll make our cleaning target more powerful</nowiki>''
 ''<nowiki># we remove the targets that we build by default and also</nowiki>''
 ''<nowiki># remove all object files</nowiki>''
 .PHONY<nowiki>:</nowiki> clean
 clean<nowiki>:</nowiki>
 rm -f $(targets) <nowiki>*.</nowiki>o
 </tt>

The CC variable is the standard variable to hold the name of the C compiler executable. GNU make comes preloaded with a list of tools that can be accessed in similar way (as will be shown with $(RM) shortly, but there are others). Most UNIX tools related to building software already have similar pre-defined variables in GNU make. Here one of them will be overridden for no other reason than to demonstrate how it is done. Overriding variables like this is not recommended, since the user running make later might want to use some other compiler, and would have to edit the makefile to do so.

== Simple Variables ==

Suppose you have a makefile like this: simple-make-files/Makefile.6

<tt>CC <nowiki>=</nowiki> gcc -Wall
 ''<nowiki># we want to add something to the end of the variable</nowiki>''
 CC <nowiki>=</nowiki> $(CC) -g
 hello.o<nowiki>:</nowiki> hello.c hello_api.h
 $(CC) -c hello.c -o hello.o
 </tt>

What might seem quite logical to a human reader, will not seem very logical to make.

Since the contents of recursive variables are evaluated when they are referenced, it can be seen that the above fragment will lead to an infinite loop.

How can this be corrected? Make actually provides two mechanisms for this. This is the solution with simple variables: simple-make-files/Makefile.7

<tt>CC <nowiki>:=</nowiki> gcc -Wall
 ''<nowiki># we want to add something to the end of the variable</nowiki>''
 CC <nowiki>:=</nowiki> $(CC) -g
 hello.o<nowiki>:</nowiki> hello.c hello_api.h
 $(CC) -c hello.c -o hello.o
 </tt>

Notice that the equals character (=) has been changed into := .

This is how simple variables are created. Whenever a simple variable is referenced, make will just replace the text that is contained in the variable without evaluating it. It will do the evaluation only when the variable is defined. In the above example, CC is created with the content of gcc -Wall (which is evaluated, but is just plain text), and when the CC variable is defined next time, make will evaluate $(CC) -g which will be replaced with gcc -Wall -g, as one might expect.

So, the only two differences between the variable flavors are:

* When defining simple variables, := is used.
* make evaluates the contents, when the simple variable is defined, not when it is referenced later.

Most of the time it is advisable to use the recursive variable flavor, since it does what is wanted.

There was a mention about two ways of appending text to an existing variable. The other mechanism is the += operation as follows: simple-make-files/Makefile.8

<tt>CC <nowiki>=</nowiki> gcc -Wall
 ''<nowiki># we want to add something to the end of the variable</nowiki>''
 CC += -g
 hello.o<nowiki>:</nowiki> hello.c hello_api.h
 $(CC) -c hello.c -o hello.o
 </tt>

The prepending operation can also be used with simple variables. Make will not change the type of variable on the left side of the += operator.

== Automatic Variables ==

There is a pre-defined set of variables inside make that can be used to avoid repetitive typing, when writing out the commands in a rule.

This is a list of the most useful ones:

* <code>$&lt;</code> : replaced by the first prerequisite of the rule.
* <code>$^</code> : replaced by the list of all prerequisites of the rule.
* <code>$@</code> : replaced by the target name.
* <code>$?</code> : list of prerequisites that are newer than the target is (if target does not exist, they are all considered newer).

By rewriting the makefile using automatic variables, the result is: simple-make-files/Makefile.9

<tt>''<nowiki># add the warning flag to CFLAGS-variable</nowiki>''
 CFLAGS += -Wall
 targets <nowiki>=</nowiki> hello
 .PHONY<nowiki>:</nowiki> all
 all<nowiki>:</nowiki> $(targets)
 hello<nowiki>:</nowiki> hello.o hello_func.o
 $(CC) $^ -o $@
 hello.o<nowiki>:</nowiki> hello.c hello_api.h
 $(CC) $(CFLAGS) -c $&lt; -o $@
 hello_func.o<nowiki>:</nowiki> hello_func.c hello_api.h
 $(CC) $(CFLAGS) -c $&lt; -o $@
 .PHONY<nowiki>:</nowiki> clean
 clean<nowiki>:</nowiki>
 $(RM) $(targets) <nowiki>*.</nowiki>o
 </tt>

Notice the cases when <code>$^</code> is used instead of <code>$&lt;</code> in the above snippet. It is not desired to pass the header files for compilation to the compiler, since the source file already includes the header files. For this reason, <code>$&lt;</code> is used. On the other hand, when linking programs and there are multiple files to put into the executable, <code>$^</code> would normally be used.

This relies on a couple of things:

* $(RM) and $(CC) will be replaced with paths to the system compiler and removal commands. * $(CFLAGS) is a variable that contains a list of options to pass whenever make will invoke the C compiler.

It can also be noticed that all these variable names are in uppercase. This signifies that they have been communicated from the system environment to make. In fact, if creating an environment variable called CFLAGS, make will create it internally for any makefile that it will process. This is the mechanism to communicate variables into makefiles from outside.

Writing variables in uppercase is a convention signaling external variables, or environmental variables, so this is the reason why lowercase should be used in own private variables within a Makefile.

== Integrating with Pkg-Config ==

The above has provided the knowledge to write a simple Makefile for the Hello World example. In order to get the the result of pkg-config, the GNU make $(shell command params) function will be used here. Its function is similar to the backtick operation of the shell. simple-make-files/Makefile.10

<tt>''<nowiki># define a list of pkg-config packages we want to use</nowiki>''
 pkg_packages <nowiki>:=</nowiki> gtk+-2.0 hildon-1
 ''<nowiki># get the necessary flags for compiling</nowiki>''
 PKG_CFLAGS <nowiki>:=</nowiki> $(shell pkg-config -cflags $(pkg_packages))
 ''<nowiki># get the necessary flags for linking</nowiki>''
 PKG_LDFLAGS <nowiki>:=</nowiki> $(shell pkg-config -libs $(pkg_packages))
 ''<nowiki># additional flags</nowiki>''
 ''<nowiki># -Wall: warnings</nowiki>''
 ''<nowiki># -g: debugging</nowiki>''
 ADD_CFLAGS <nowiki>:=</nowiki> -Wall -g
 ''<nowiki># combine the flags (so that CFLAGS/LDFLAGS from the command line</nowiki>''
 ''<nowiki># still work).</nowiki>''
 CFLAGS <nowiki>:=</nowiki> $(PKG_CFLAGS) $(ADD_CFLAGS) $(CFLAGS)
 LDFLAGS <nowiki>:=</nowiki> $(PKG_LDFLAGS) $(LDFLAGS)
 targets <nowiki>=</nowiki> hildon_helloworld-1
 .PHONY<nowiki>:</nowiki> all
 all<nowiki>:</nowiki> $(targets)
 hildon_helloworld-1<nowiki>:</nowiki> hildon_helloworld-1.o
 $(CC) $^ -o $@ $(LDFLAGS)
 hildon_helloworld-1.o<nowiki>:</nowiki> hildon_helloworld-1.c
 $(CC) $(CFLAGS) -c $&lt; -o $@
 .PHONY<nowiki>:</nowiki> clean
 clean<nowiki>:</nowiki>
 $(RM) $(targets) <nowiki>*.</nowiki>o
 </tt>

One might wonder, where the CC and RM variables come from. They certainly were not declared anywhere in the Makefile. GNU make comes with a list of pre-defined variables for many programs and their arguments. GNU make also contains a preset list of pattern rules (which will not be dealt here), but basically these are pre-defined rules that are used when (for example) one needs an .o file from an .c file. The rules that were manually specified above are actually the same rules that GNU make already contains, so the Makefile can be made even more compact by only specifying the dependencies between files.

This leads to the following, slightly simpler version: simple-make-files/Makefile.11

<tt>''<nowiki># define a list of pkg-config packages we want to use</nowiki>''
 pkg_packages <nowiki>:=</nowiki> gtk+-2.0 hildon-1
 PKG_CFLAGS <nowiki>:=</nowiki> $(shell pkg-config -cflags $(pkg_packages))
 PKG_LDFLAGS <nowiki>:=</nowiki> $(shell pkg-config -libs $(pkg_packages))
 ADD_CFLAGS <nowiki>:=</nowiki> -Wall -g
 ''<nowiki># combine the flags</nowiki>''
 CFLAGS <nowiki>:=</nowiki> $(PKG_CFLAGS) $(ADD_CFLAGS) $(CFLAGS)
 LDFLAGS <nowiki>:=</nowiki> $(PKG_LDFLAGS) $(LDFLAGS)
 targets <nowiki>=</nowiki> hildon_helloworld-1
 .PHONY<nowiki>:</nowiki> all
 all<nowiki>:</nowiki> $(targets)
 ''<nowiki># we can omit the rules and just specify the dependencies</nowiki>''
 ''<nowiki># for our simple project this doesn't seem like a big win</nowiki>''
 ''<nowiki># but for larger projects where you have multiple object</nowiki>''
 ''<nowiki># files, this will save considerable time.</nowiki>''
 hildon_helloworld-1<nowiki>:</nowiki> hildon_helloworld-1.o
 hildon_helloworld-1.o<nowiki>:</nowiki> hildon_helloworld-1.c
 .PHONY<nowiki>:</nowiki> clean
 clean<nowiki>:</nowiki>
 $(RM) $(targets) <nowiki>*.</nowiki>o
 </tt>

= GNU Autotools =

Creating portable software written in the C language has historically been challenging. The portability issues are not restricted just to the differences between binary architectures, but also encompass differences in system libraries and different implementations of UNIX APIs in different systems. This section introduces GNU autotools as one solution for managing this complexity. There are also other tools available, but the most likely to be encountered are autotoolized projects and also Debian packaging supports autotools.

== Brief History of Managing Portability ==

When discussing portability challenges with C code, various issues crop up:

* Same library function has differing prototypes in different UNIX-style systems.
* Same library function has differing implementations between systems (this is a difficult problem).
* Same function can be found in different libraries in different UNIX systems, and because of this, the linker parameters need to be modified when making the final linking of the project.
* Besides these not so obvious problems, there is also of course the problem of potentially different architecture, and hence different sizes for the standard C data types. This problem is best fixed by using GLib (as in this case), so it is not covered here.
* GLib also provides the necessary macros to do endianess detection and conversion.

The historical solutions to solve these problems can be roughly grouped as follows:

* The whole software is built with one big shell script, which tries to pass the right options to different compilers and tools. However, such scripts are very hard to maintain and their use is strongly discouraged.
* Makefiles (GNU or other kind) allow some automation in building, but do not directly solve any of the portability issues. The classical solution is to ship various makefiles already tailored for different UNIX systems, and make it the user's responsibility to select the appropriate Makefile to use for their system. However, quite often this method required the Makefile to be edited, so the user had to be knowledgeable in UNIX programming tools. A good example of this style is found in some of the older versions of the game nethack.
* Some parts of the Makefile selection above can be automated by a suitable script that tries to guess the system on which it is running and select a suitably prepared Makefile. However, maintaining such scripts is quite hard, because there have been so many different kinds of systems, such as different library versions and different compilers.
* Even the creation of Makefiles can be automated from a script that guesses the system. Such scripts are normally called '''configure''' or '''Configure''' and are marked as executable for the sake of convenience. The name of the script does not automatically mean that the script is related to GNU autotools.
* Two major branches of these master configure scripts evolved, each operating slightly differently and catering for differing needs.
* These two scripts and a third guessing script were then combined into GNU autoconf. Because this happened many years ago, most of the historical code has already been purged from GNU autoconf.

Besides autoconf, it became evident that a more general Makefile generation tool can be useful as part of the whole process. This is how GNU automake was born. GNU automake can also be used outside autoconf. A simple autoconf configuration file is presented next.

== GNU Autoconf ==

Autoconf is a tool that uses the GNU m4 macro preprocessor to process the configuration file and output a shell script based on the macros used in the file. Anything that m4 does not recognize as a macro is passed verbatim to the output script. This means that almost any wanted shell script fragments can be included into the '''configure.ac''' (the modern name for the default configuration file for autoconf).

The first subject here is a simple example to see how the basic configuration file works. Then some limitations of m4 syntax are covered, and hints on how to avoid problems with the syntax are given. autoconf-automake/example1/configure.ac

<tt>''<nowiki># Specify the "application name" and application version</nowiki>''
 AC_INIT(hello, version-0.1)
 
 ''<nowiki># Because autoconf passes trough anything that it does not recognize</nowiki>''
 ''<nowiki># into the final script ('configure'), we can use any valid shell</nowiki>''
 ''<nowiki># statements here. Note that you should restrict your shell to</nowiki>''
 ''<nowiki># standard features that are available in all UNIX shells, but in our</nowiki>''
 ''<nowiki># case, we are content with the most used shell on Linux systems</nowiki>''
 ''<nowiki># (bash).</nowiki>''
 echo -e "\n\nHello from configure (using echo)!\n\n"
 
 ''<nowiki># We can use a macro for this messages. This is much preferred as it</nowiki>''
 ''<nowiki># is more portable.</nowiki>''
 AC_MSG_NOTICE([Hello from configure using msg-notice<nowiki>!])</nowiki>
 
 ''<nowiki># Check that the C Compiler works.</nowiki>''
 AC_PROG_CC
 ''<nowiki># Check what is the AWK-program on our system (and that one exists).</nowiki>''
 AC_PROG_AWK
 ''<nowiki># Check whether the 'cos' function can be found in library 'm'</nowiki>''
 ''<nowiki># (standard C math library).</nowiki>''
 AC_CHECK_LIB(m, cos)
 ''<nowiki># Check for presence of system header 'unistd.h'.</nowiki>''
 ''<nowiki># This also tests a lot of other system include files (it is</nowiki>''
 ''<nowiki># semi-intelligent in determining which ones are required).</nowiki>''
 AC_CHECK_HEADER(unistd.h)
 ''<nowiki># You can also check for multiple system headers at the same time,</nowiki>''
 ''<nowiki># but notice the different name of the test macro for this (plural).</nowiki>''
 AC_CHECK_HEADERS([math.h stdio.h])
 ''<nowiki># A way to implement conditional logic based on header file presence</nowiki>''
 ''<nowiki># (we do not have a b0rk.h in our system).</nowiki>''
 AC_CHECK_HEADER(b0rk.h, [echo "b0rk.h present in system"], \
 [echo "b0rk.h not present in system"])
 
 echo "But that does not stop us from continuing!"
 
 echo "Directory to install binaries in is '$bindir'"
 echo "Directory under which data files go is '$datadir'"
 echo "For more variables, check 'config.log' after running configure"
 echo "CFLAGS is '$CFLAGS'"
 echo "LDFLAGS is '$LDFLAGS'"
 echo "LIBS is '$LIBS'"
 echo "CC is '$CC'"
 echo "AWK is '$AWK'"
 </tt>

The listing is verbosely commented, so it should be pretty self-evident what the different macros do. The macros that test for a feature or an include file normally causes the generated configure script to generate small C code test programs that are run as part of the configuration process. If these programs run successfully, the relevant test succeeds and the configuration process continues to the next test.

The following convention holds true in respect to the names of macros that are commonly used and available:

* '''AC_*'''<nowiki>: A macro that is included in autoconf or is meant for it. </nowiki>
* '''AM_*'''<nowiki>: A macro that is meant for automake. </nowiki>
* Others: The autoconf system can be expanded by writing custom macros which can be stored in a custom directory. Some development packages also install new macros to be used.

The next step is to run ''autoconf''. Without any parameters, it reads '''configure.ac''' by default. If configure.ac does not exist, it tries to read '''configure.in''' instead.

Note that using the name configure.in is considered obsolete.

<nowiki>
 [sbox-FREMANTLE_X86: ~/example1] &gt; autoconf
 [sbox-FREMANTLE_X86: ~/example1] &gt; ls -l
 total 112
 drwxr-xr-x 2 user user 4096 Sep 16 05:14 autom4te.cache
 -rwxrwxr-x 1 user user 98683 Sep 16 05:14 configure
 -rw-r--r-- 1 user user 1825 Sep 15 17:23 configure.ac
 [sbox-FREMANTLE_X86: ~/example1] &gt; ./configure
 Hello from configure (using echo)!
 
 configure: Hello from configure using msg-notice!
 checking for gcc... gcc
 checking for C compiler default output file name... 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 gawk... gawk
 checking for cos in -lm... yes
 checking how to run the C preprocessor... gcc -E
 checking for egrep... grep -E
 checking for ANSI C header files... yes
 checking for sys/types.h... yes
 checking for sys/stat.h... yes
 checking for stdlib.h... yes
 checking for string.h... yes
 checking for memory.h... yes
 checking for strings.h... yes
 checking for inttypes.h... yes
 checking for stdint.h... yes
 checking for unistd.h... yes
 checking for unistd.h... (cached) yes
 checking math.h usability... yes
 checking math.h presence... yes
 checking for math.h... yes
 checking stdio.h usability... yes
 checking stdio.h presence... yes
 checking for stdio.h... yes
 checking b0rk.h usability... no
 checking b0rk.h presence... no
 checking for b0rk.h... no
 b0rk.h not present in system
 But that doesn't stop us from continuing!
 Directory to install binaries in is '${exec_prefix}/bin'
 Directory under which data files go is '${prefix}/share'
 For more variables, check 'config.log' after running configure
 CFLAGS is '-g -O2'
 LDFLAGS is ''
 LIBS is '-lm '
 CC is 'gcc'
 AWK is 'gawk'
 </nowiki>

Autoconf does not output information about its progress. Normally, only errors are output on stdout. Instead, it creates a new script called '''configure''' in the same directory, and sets it as executable.

The configure script is the result of all of the macro processing. If taking a look at the generated file with an editor or by using less, it can be seen that it contains a lot of shell code.

Unless you are experienced in reading convoluted shell code, you do not need to try to understand what is attempted at the various stages. Normally the generated file is not fixed or modified manually because it is overwritten anyway the next time that someone runs autoconf.

When the generated script is executed, the output of various parts can be seen in the order that they were used in the configuration file.

Note that autoconf (because of m4) is an imperative language, which means that it executes the commands one by one when it detects them. This is in contrast to declarative languages, like Makefiles.

'''M4-syntax notes:'''

* Public autoconf M4 macros all start with A[CST]_* .
* Private macros start with an underscore, but they must not be used because they change from one autoconf version to the other (using undocumented features is bad style anyway).
* m4 uses [ and ] to quote arguments to functions, but in most cases quoting is not needed. Avoid using brackets, unless the macro does not seem to work properly otherwise. When writing new macros, using brackets become more important, but this material does not cover creating custom macros.
* If brackets absolutely must be passed to the generated script, there are three choices:
*; ${}$
*: <code>@&lt;:@</code> is same as [, and <code>@&gt;:@</code> is same as ]
*; []
*: expands into [] (most of time)
*; ${}$
*: avoid [ and ] (most command line tools and shell do not really require them)
* Because m4 uses brackets for its own needs, the [ command cannot be used to test things in scripts, but instead test has to be used (which is more clear anyway). This is why the brackets are escaped with the rules given above if they really must be output into the generated shell script.

If bad shell syntax is introduced into the configuration file, the bad syntax causes errors only when the generated script file is run (not when autoconf generates the script). In general, autoconf almost always succeeds but the generated script does not necessarily succeed. Knowing which error in the shell script corresponds to which line in the original configure.ac is not always easy but can be learned through experience.

There is a line that reports the result of testing for '''unistd.h'''. It appears twice: the first time because it is the default test to run whenever testing for headers, and the second time because it was explicitly tested for. The second test output contains text (cached), which means that the test has been already run, and the result has been saved into a cache (the mysterious '''autom4te.cache''' directory). This means that for large projects, which cannot necessarily perform the same tests over and over, the tests are only run once, which makes running the script faster.

The last line's output above contains the values of variables. When the configure script runs, it automatically creates shell variables that can be used in shell code fragments. The macros for checking what programs are available for compiling must illustrate that point. Here awk was used as an example.

The configure script takes the initial values for variables from the environment, but also contains a lot of options that can be given to the script. Using these options introduces new variables that can also be used. Options such as prefix are commonly used in compiling modern open source projects. Both of these cases are illustrated below:

<nowiki>
 [sbox-FREMANTLE_X86: ~/example1] &gt; CFLAGS='-O2 -Wall' ./configure --prefix=/usr
 ...
 Directory to install binaries in is '${exec_prefix}/bin'
 Directory under which data files go is '${prefix}/share'
 For more variables, check 'config.log' after running configure
 CFLAGS is '-O2 -Wall'
 LDFLAGS is ''
 LIBS is '-lm '
 CC is 'gcc'
 AWK is 'gawk'
 </nowiki>

It can seem that giving the prefix does not change anything, but this is because the shell does not expand the value in this particular case. However, if the variable was used in the script for doing something, the shell would expand later on. In order to see some effect, try passing the datadir-option (because that is printed out explicitly).

If you need to see which variables are available for configuration, read the generated '''config.log''' file. The variables are listed at the end of that file.

== Substitutions ==

Besides creating the configure script, autoconf can do other useful things as well. Some people say that autoconf is at least as powerful as emacs, if not more so. Unfortunately, with all this power comes also lot of complexity. Sometimes finding out why things do not quite work can be rather difficult.

It can be useful to use the variables inside text files that are not directly related to the '''configure.ac'''. These might be configuration files or files that are used in some part of the building process later on. For this, autoconf provides a mechanism called ''substitution''. A special macro reads in an external file, replaces all instances of variable names in it, and then stores the resulting file as a new file. The convention in naming the input files is to add a suffix .in to the names. The name of generated output file are the same but without the suffix.

Note that the substitution is done when the generated configure script is run, not when autoconf is run.

The generated configure script replaces all occurrences of the variable name surrounded with 'at' (@) characters with the variable value when it reads through each of the input files.

This is best illustrated with a small example. The input file contents are listed after the autoconf configuration file. In this example, the substitution is only made for one file, but it is also possible to process multiple files using the substitution mechanism. autoconf-automake/example2/configure.ac

<tt>''<nowiki># An example showing how to use a variable-based substitution.</nowiki>''
 
 AC_INIT(hello, version-0.1)
 
 AC_PROG_CC
 AC_PROG_AWK
 AC_CHECK_HEADER(unistd.h)
 AC_CHECK_HEADERS([math.h stdio.h])
 AC_CHECK_HEADER(b0rk.h, [echo "b0rk.h present in system"], \
 [echo "b0rk.h not present in system"])
 
 echo "But that doesn't stop us from continuing!"
 
 ''<nowiki># Run the test-output.txt(.in) through autoconf substitution logic.</nowiki>''
 AC_OUTPUT(test-output.txt)
 </tt>

autoconf-automake/example2/test-output.txt.in

<code>This file will go through autoconf variable substitution.
 The output file will be named as 'test-output.txt' (the '.in'-suffix
 is stripped).
 All the names surrounded by '@'-characters will be replaced by the values
 of the variables (if present) by the configure script, when it is run
 by the end user.
 Prefix: @prefix@
 C compiler: @CC@
 This is a name for which there is no variable.
 Stuff: @stuff@</code>

We then run autoconf and configure:

[sbox-FREMANTLE_X86: ~/example2] &gt; autoconf
 [sbox-FREMANTLE_X86: ~/example2] &gt; ./configure
 checking for gcc... gcc
 checking for C compiler default output file name... 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 gawk... gawk
 checking how to run the C preprocessor... gcc -E
 checking for egrep... grep -E
 checking for ANSI C header files... yes
 checking for sys/types.h... yes
 checking for sys/stat.h... yes
 checking for stdlib.h... yes
 checking for string.h... yes
 checking for memory.h... yes
 checking for strings.h... yes
 checking for inttypes.h... yes
 checking for stdint.h... yes
 checking for unistd.h... yes
 checking for unistd.h... (cached) yes
 checking math.h usability... yes
 checking math.h presence... yes
 checking for math.h... yes
 checking stdio.h usability... yes
 checking stdio.h presence... yes
 checking for stdio.h... yes
 checking b0rk.h usability... no
 checking b0rk.h presence... no
 checking for b0rk.h... no
 b0rk.h not present in system
 But that doesn't stop us from continuing!
 configure: creating ./config.status
 config.status: creating test-output.txt
 [sbox-FREMANTLE_X86: ~/example2] &gt; cat test-output.txt
 This file will go through autoconf variable substitution.
 
 The output file will be named as 'test-output.txt' (the '.in'-suffix
 is stripped).
 
 All names surrounded by '@'-characters will be replaced by the values
 of the variables (if present) by the configure script when it is run
 by end user.
 
 Prefix: /usr/local
 C compiler: gcc
 
 This is a name for which there is no variable.
 Stuff: @stuff@

This feature is used later on. When you run your own version of the file, notice the creation of file called '''config.status'''. It is the file that actually does the substitution for external files, so if the configuration is otherwise complex, and you only want to re-run the substitution of the output files, you can run the config.status script.

== Introducing Automake ==

The next step is to create a small project that consists of yet another hello world. This time, there is a file implementing the application (main), a header file describing the API (printHello()) and the implementation of the function.

As it happens, GNU automake is designed so that it can be easily integrated into autoconf. This is utilized in the next example, so that the Makefile does not have to be written by hand anymore. Instead, the Makefile is generated by the configure script, and it contains the necessary settings for the system on which configure is run.

In order for this to work, two things are necessary:

* A configuration file for automake (conventionally Makefile.am).
* Telling the autoconf that it should create Makefile.in based on Makefile.am by using automake.

The example starts with the autoconf configuration file: autoconf-automake/example3/configure.ac

<tt>''<nowiki># Any source file name related to our project is ok here.</nowiki>''
 AC_INIT(helloapp, 0.1)
 ''<nowiki># We are using automake, so we init it next. The name of the macro</nowiki>''
 ''<nowiki># starts with 'AM' which means that it is related to automake ('AC'</nowiki>''
 ''<nowiki># is related to autoconf).</nowiki>''
 ''<nowiki># Initing automake means more or less generating the .in file from</nowiki>''
 ''<nowiki># the .am file although it can also be generated at other steps.</nowiki>''
 AM_INIT_AUTOMAKE
 ''<nowiki># Compiler check.</nowiki>''
 AC_PROG_CC
 ''<nowiki># Check for 'install' program.</nowiki>''
 AC_PROG_INSTALL
 ''<nowiki># Generate the Makefile from Makefile.in (using substitution logic).</nowiki>''
 AC_OUTPUT(Makefile)
 </tt>

Then the configuration file is presented for automake: autoconf-automake/example3/Makefile.am

<tt>''<nowiki># Automake rule primer:</nowiki>''
 ''<nowiki># 1) Left side_ tells what kind of target this is.</nowiki>''
 ''<nowiki># 2) _right side tells what kind of dependencies are listed.</nowiki>''
 ''<nowiki>#</nowiki>''
 ''<nowiki># As an example, below:</nowiki>''
 ''<nowiki># 1) bin = binaries</nowiki>''
 ''<nowiki># 2) PROGRAMS lists the programs to generate Makefile.ins for.</nowiki>''
 bin_PROGRAMS <nowiki>=</nowiki> helloapp
 ''<nowiki># Listing source dependencies:</nowiki>''
 ''<nowiki>#</nowiki>''
 ''<nowiki># The left side_ gives the name of the application to which the</nowiki>''
 ''<nowiki># dependencies are related to.</nowiki>''
 ''<nowiki># _right side gives again the type of dependencies.</nowiki>''
 ''<nowiki>#</nowiki>''
 ''<nowiki># Here we then list the source files that are necessary to build the</nowiki>''
 ''<nowiki># helloapp -binary.</nowiki>''
 helloapp_SOURCES <nowiki>=</nowiki> helloapp.c hello.c hello.h
 ''<nowiki># For other files that cannot be automatically deduced by automake,</nowiki>''
 ''<nowiki># you need to use the EXTRA_DIST rule which should list the files</nowiki>''
 ''<nowiki># that should be included. Files can also be in other directories or</nowiki>''
 ''<nowiki># even whole directories can be included this way (not recommended).</nowiki>''
 ''<nowiki>#</nowiki>''
 ''<nowiki># EXTRA_DIST = some.service.file.service some.desktop.file.desktop</nowiki>''
 </tt>

This material tries to introduce just enough of automake for it to be useful for small projects. Because of this, the detailed syntax of Makefile.am is not explained. Based on the above description, automake knows what kind of Makefile.in to create, and autoconf takes it over from there and fills in the missing pieces.

The source files for the project are as simple as possible, but notice the implementation of printHello. autoconf-automake/example3/helloapp.c

<tt>''/**''
 '' * This maemo code example is licensed under a MIT-style license,''
 '' * that can be found in the file called "License" in the same''
 '' * directory as this file.''
 '' * Copyright (c) 2007-2008 Nokia Corporation. All rights reserved.''
 '' */''
 '''<nowiki>#include</nowiki>''' &lt;stdlib.h&gt;
 '''<nowiki>#include</nowiki>''' "hello.h"
 int '''main'''(int argc, char<nowiki>**</nowiki> argv) {
 '''printHello'''();
 '''return''' EXIT_SUCCESS<nowiki>;</nowiki>
 }
 </tt>

autoconf-automake/example3/hello.h

autoconf-automake/example3/hello.c

<tt>''/**''
 '' * This maemo code example is licensed under a MIT-style license,''
 '' * that can be found in the file called "License" in the same''
 '' * directory as this file.''
 '' * Copyright (c) 2007-2008 Nokia Corporation. All rights reserved.''
 '' */''
 
 '''<nowiki>#include</nowiki>''' &lt;stdio.h&gt;
 '''<nowiki>#include</nowiki>''' "hello.h"
 
 void '''printHello'''(void) {
 ''/* Note that these are available as defines now. */''
 '''printf'''("(" PACKAGE " " VERSION ")\n");
 '''printf'''("Hello world!\n");
 }
 </tt>

The PACKAGE and VERSION defines is passed to the build process automatically.

[sbox-FREMANTLE_X86: ~/example3] &gt; autoconf
 configure.ac:10: error: possibly undefined macro: AM_INIT_AUTOMAKE
 If this token and others are legitimate, please use m4_pattern_allow.
 See the Autoconf documentation.

Autoconf is complaining about a macro, for which it cannot find a definition (actually m4 is the program that does the complaining). The problem is that by default, autoconf only knows about built-in macros. When using a macro for integration or a macro that comes with another package, autoconf needs to be told about it. Luckily, this process is quite painless.

A local '''aclocal.m4''' file needs to be created into the same directory with the '''configure.ac'''. When starting, autoconf reads this file, and it is enough to put the necessary macros there.

For this, a utility program called aclocal is used, which scans the configure.ac and copy the relevant macros into the local aclocal.m4. The directory for all the extension macros is usually '''/usr/share/aclocal/''', which should be checked out at some point.

Now it is time to run aclocal, and then try and run autoconf again.

Note that the messages that are introduced into the process from now on are inevitable, because some macros use obsolete features or have incomplete syntax, and thus trigger warnings. There is no easy solution to this, other than to fix the macros themselves.

[sbox-FREMANTLE_X86: ~/example3] &gt; aclocal
 /scratchbox/tools/share/aclocal/pkg.m4:5: warning:
  underquoted definition of PKG_CHECK_MODULES
   run info '(automake)Extending aclocal' or see
   http://sources.redhat.com/automake/automake.html#Extending%20aclocal
 /usr/share/aclocal/pkg.m4:5: warning:
  underquoted definition of PKG_CHECK_MODULES
 /usr/share/aclocal/gconf-2.m4:8: warning:
  underquoted definition of AM_GCONF_SOURCE_2
 /usr/share/aclocal/audiofile.m4:12: warning:
  underquoted definition of AM_PATH_AUDIOFILE
 [sbox-FREMANTLE_X86: ~/example3] &gt; autoconf
 [sbox-FREMANTLE_X86: ~/example3] &gt; ./configure
 configure: error: cannot find install-sh or install.sh in
  ~/example3 ~/ ~/..

Listing the contents of the directory reveals that the '''Makefile.in''' is not among the contents. Automake needs to be run manually, so that the file is created. At the same time, the missing files need to be introduced to the directory (such as the install.sh that configure seems to complain about).

This is done by executing automake -ac, which creates the Makefile.in and also copy the missing files into their proper places. ''This step also copies a file called COPYING into the directory, which by default contains the GPL.'' So, if the software is going to be distributed under some other license, this is the correct moment to replace the license file with the appropriate one.

[sbox-FREMANTLE_X86: ~/example3] &gt; automake -ac
 configure.ac: installing `./install-sh'
 configure.ac: installing `./missing'
 Makefile.am: installing `./depcomp'
 [sbox-FREMANTLE_X86: ~/example3] &gt; ./configure
 checking for a BSD-compatible install... /scratchbox/tools/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 file name... 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
 checking for a BSD-compatible install... /scratchbox/tools/bin/install -c
 configure: creating ./config.status
 config.status: creating Makefile
 config.status: executing depfiles commands

Notice the second to last line of the output, telling that autoconf just created a Makefile (based on the Makefile.in that ''automake'' created).

Performing all these steps manually each time to make sure that all the generated files are really generated can be rather tedious. Most developers create a script called '''autogen.sh''', which implements the necessary bootstrap procedures for them. Below is a file that is suitable for this example. Real-life projects can have more steps because of localization and other requirements. autoconf-automake/example3/autogen.sh

<tt>''<nowiki>#!/bin/sh</nowiki>''
 ''<nowiki>#</nowiki>''
 ''<nowiki># A utility script to setup the autoconf environment for the first</nowiki>''
 ''<nowiki># time. Normally this script is run when checking out a</nowiki>''
 ''<nowiki># development version of the software from SVN/version control.</nowiki>''
 ''<nowiki># Regular users expect to download .tar.gz/tar.bz2 source code</nowiki>''
 ''<nowiki># instead, and those should come with with 'configure' script so that</nowiki>''
 ''<nowiki># users do not require the autoconf/automake tools.</nowiki>''
 ''<nowiki>#</nowiki>''
 ''<nowiki># Scan configure.ac and copy the necessary macros into aclocal.m4.</nowiki>''
 aclocal
 ''<nowiki># Generate Makefile.in from Makefile.am (and copy necessary support</nowiki>''
 ''<nowiki># files, because of -ac).</nowiki>''
 automake -ac
 ''<nowiki># This step is not normally necessary, but documented here for your</nowiki>''
 ''<nowiki># convenience. The files listed below need to be present to stop</nowiki>''
 ''<nowiki># automake from complaining during various phases of operation.</nowiki>''
 ''<nowiki>#</nowiki>''
 ''<nowiki># You also should consider maintaining these files separately once</nowiki>''
 ''<nowiki># you release your project into the wild.</nowiki>''
 ''<nowiki>#</nowiki>''
 ''<nowiki># touch NEWS README AUTHORS ChangeLog</nowiki>''
 ''<nowiki># Run autoconf (creates the 'configure'-script).</nowiki>''
 autoconf
 echo 'Ready to go (run configure)'
 </tt>

In the above code, the line with touch is commented. This can raise a question. There is a target called distcheck that automake creates in the Makefile, and this target checks whether the distribution tarball contains all the necessary files. The files listed on the touch line are necessary (even if empty), so they need to be created at some point. Without these files, the penultimate Makefile complains when running the distcheck-target.

Build the project now and test it out:

[sbox-FREMANTLE_X86: ~/example3] &gt; make
 if gcc -DPACKAGE_NAME=\"helloapp\" -DPACKAGE_TARNAME=\"helloapp\"
  -DPACKAGE_VERSION=\"0.1\" -DPACKAGE_STRING=\"helloapp\ 0.1\"
  -DPACKAGE_BUGREPORT=\"\" -DPACKAGE=\"helloapp\" -DVERSION=\"0.1\"
  -I. -Iexample3 -g -O2 -MT helloapp.o -MD -MP -MF ".deps/helloapp.Tpo"
  -c -o helloapp.o helloapp.c; \ then \
   mv -f ".deps/helloapp.Tpo" ".deps/helloapp.Po"; 
  else rm -f ".deps/helloapp.Tpo"; exit 1;
 fi
 if gcc -DPACKAGE_NAME=\"helloapp\" -DPACKAGE_TARNAME=\"helloapp\"
  -DPACKAGE_VERSION=\"0.1\" -DPACKAGE_STRING=\"helloapp\ 0.1\"
  -DPACKAGE_BUGREPORT=\"\" -DPACKAGE=\"helloapp\" -DVERSION=\"0.1\"
  -I. -Iexample3 -g -O2 -MT hello.o -MD -MP -MF ".deps/hello.Tpo"
  -c -o hello.o hello.c; \ then \
   mv -f ".deps/hello.Tpo" ".deps/hello.Po"; 
  else rm -f ".deps/hello.Tpo"; exit 1;
 fi
 gcc -g -O2 -o helloapp helloapp.o hello.o
 [sbox-FREMANTLE_X86: ~/example3] &gt; ./helloapp
 (helloapp 0.1)
 Hello world!
 [sbox-FREMANTLE_X86: ~/example3] &gt; make clean
 test -z "helloapp" || rm -f helloapp
 rm -f *.o

== Checking for Distribution Sanity ==

The generated Makefile contains various targets that can be used when creating distribution tarballs (tar files containing the source code and the necessary files to build the software). The most important of these is the dist-target, which by default creates a .tar.gz-file out of the source, including the configure script and other necessary files (which are specified in Makefile.am).

To test whether building the software from the distribution tarball is possible, execute the distcheck-target. It first creates a distribution tarball, then extracts it in a new subdirectory, runs configure there and tries and builds the software with the default make target. If it fails, the relevant error is given.

Making the distcheck target each time before making a dist target is recommended, so that you can be sure that the distribution tarball can be used outside the source tree. This step is especially critical later when making Debian packages.

== Cleaning up ==

For the sake of convenience, the example3 directory also includes a script called antigen.sh, which will try its best to get rid of all generated files (it will be necessary to autogen.sh the project afterwards).

Having a clean-up script is not very common in open source projects, but it is especially useful when starting autotools development, as it allows testing the toolchain easily from scratch.

The contents of antigen.sh that is suitable for simple projects: autoconf-automake/example3/antigen.sh

<tt>''<nowiki>#!/bin/sh</nowiki>''
 ''<nowiki>#</nowiki>''
 ''<nowiki># A utility script to remove all generated files.</nowiki>''
 ''<nowiki>#</nowiki>''
 ''<nowiki># Running autogen.sh will be required after running this script since</nowiki>''
 ''<nowiki># the 'configure' script will also be removed.</nowiki>''
 ''<nowiki>#</nowiki>''
 ''<nowiki># This script is mainly useful when testing autoconf/automake changes</nowiki>''
 ''<nowiki># and as a part of their development process.</nowiki>''
 ''<nowiki># If there's a Makefile, then run the 'distclean' target first (which</nowiki>''
 ''<nowiki># will also remove the Makefile).</nowiki>''
 '''if''' '''test''' -f Makefile<nowiki>;</nowiki> '''then'''
 make distclean
 '''fi'''
 ''<nowiki># Remove all tar-files (assuming there are some packages).</nowiki>''
 rm -f <nowiki>*.</nowiki>tar.* <nowiki>*.</nowiki>tgz
 ''<nowiki># Also remove the autotools cache directory.</nowiki>''
 rm -Rf autom4te.cache
 ''<nowiki># Remove rest of the generated files.</nowiki>''
 rm -f Makefile.'''in''' aclocal.m4 configure depcomp install-sh missing
 </tt>

== Integration with Pkg-Config ==

The last part that is covered for autoconf is how to integrate pkg-config support into the projects when using configure.ac.

Pkg-config comes with a macro package ('''pkg.m4'''), which contains some useful macros for integration. The best documentation for these can be found in the pkg-config manual pages.

Here only one will be used, PKG_CHECK_MODULES, which should be used like this: Part of configure.ac for pkg-config integration

<tt>''<nowiki># Check whether the necessary pkg-config packages are present. The</nowiki>''
 ''<nowiki># PKG_CHECK_MODULES macro is supplied by pkg-config</nowiki>''
 ''<nowiki># (/usr/share/aclocal/).</nowiki>''
 ''<nowiki>#</nowiki>''
 ''<nowiki># The first parameter will be the variable name prefix that will be</nowiki>''
 ''<nowiki># used to create two variables: one to hold the CFLAGS required by</nowiki>''
 ''<nowiki># the packages, and one to hold the LDFLAGS (LIBS) required by the</nowiki>''
 ''<nowiki># packages. The variable name prefix (HHW) can be chosen freely.</nowiki>''
 PKG_CHECK_MODULES(HHW, gtk+-2.0 hildon-1 hildon-fm-2 gnome-vfs-2.0 \
 gconf-2.0 libosso)
 ''<nowiki># At this point HHW_CFLAGS will contain the necessary compiler flags</nowiki>''
 ''<nowiki># and HHW_LIBS will contain the linker options necessary for all the</nowiki>''
 ''<nowiki># packages listed above.</nowiki>''
 ''<nowiki>#</nowiki>''
 ''<nowiki># Add the pkg-config supplied values to the ones that are used by</nowiki>''
 ''<nowiki># Makefile or supplied by the user running ./configure.</nowiki>''
 CFLAGS<nowiki>=</nowiki>"$HHW_CFLAGS $CFLAGS"
 LIBS<nowiki>=</nowiki>"$HHW_LIBS $LIBS"</tt>

The proper placing for this code is after all the AC_PROG_* checks and before the AC_OUTPUT macros (so that the build flags may affect the substituted files).

One should also check the validity of the package names by using:

pkg-config --list-all

to make sure one does not try to get the wrong library information.

Please note that all contributions to maemo.org wiki may be edited, altered, or removed by other contributors. If you do not want your writing to be edited mercilessly, then do not submit it here.
You are also promising us that you wrote this yourself, or copied it from a public domain or similar free resource (see maemo.org wiki:Copyrights for details). Do not submit copyrighted work without permission!

Summary:

Cancel | Editing help (opens in new window)

Templates used on this page:

Template:Ambox (view source) (semi-protected)

Retrieved from "https://wiki.maemo.org/Documentation/Maemo_5_Developer_Guide/GNU_Build_System"

Personal tools

Navigation

Views

Editing Documentation/Maemo 5 Developer Guide/GNU Build System

@@ Line 1: / Line 1: @@
+= GNU Build System =
 The following code examples are used in this chapter:
-* [https://vcs.maemo.org/svn/maemoexamples/tags/maemo_5.0/simple-make-files/ simple-make-files]
+* [https://garage.maemo.org/svn/maemoexamples/trunk/simple-make-files/ simple-make-files]
-* [https://vcs.maemo.org/svn/maemoexamples/tags/maemo_5.0/autoconf-automake/ autoconf-automake]
+* [https://garage.maemo.org/svn/maemoexamples/trunk/autoconf-automake/ autoconf-automake]
+= GNU Make and Makefiles =
-== GNU Make and Makefiles ==
+The ''make'' program from the GNU project is a powerful tool to aid implementing automation in the software building process. Beside this, it can be used to automate any task that uses files and in which these files are transformed into some other form. Make by itself does not know what the files contain or what they represent, but using a simple syntax it can be taught how to handle them.
-The <code>make</code> program from the GNU project is a powerful tool to aid implementing automation in the software building process. Beside this, it can be used to automate any task that uses files and in which these files are transformed into some other form. Make by itself does not know what the files contain or what they represent, but using a simple syntax it can be taught how to handle them.
+When developing software with gcc (and other tools), gcc will often be invoked repeatedly with the same parameters and flags. After changing one source file, it will be noticed that other output files need to be rebuilt, and even the whole application if some interface has changed between the functions. This might happen whenever declarations change, new parameters are added to function prototypes etc.
-When developing software with gcc (and other tools), gcc is often invoked repeatedly with the same parameters and flags. After changing one source file, it is noticed that other output files need to be rebuilt, and even the whole application if some interface has changed between the functions. This might happen whenever declarations change, new parameters are added to function prototypes, and so on.
+These tasks could, of course, be always performed manually, but after a while a nicer way is going to be more desirable.
-These tasks can always be performed manually, but after a while a nicer way is more desirable.
 GNU make is a software building automation tool that will execute repetitive tasks. It is controlled via a '''Makefile''' that contains lists of dependencies between different source files and output files. It also contains lists of commands that should be executed to satisfy these dependencies. Make uses the '''timestamps''' of files and the information of the files' existence to automate the rebuilding of applications (targets in make), as well as the rules that are specified in the Makefile.
-Make can be used for other purposes as well. A target can easily be created for installing the built software on a destination computer, a target for generating documentation by using some automatic documentation generation tool, and so on. Some people use make to keep multiple Linux systems up to date with the newest software and various system configuration changes. In short, make is flexible enough to be generally useful.
+Make can be used for other purposes as well. A target can easily be created for installing the built software on a destination computer, a target for generating documentation by using some automatic documentation generation tool, etc. Some people use make to keep multiple Linux systems up to date with the newest software and various system configuration changes. In short, make is flexible enough to be generally useful.
-[[Image:make.png|center|frame|alt=Diagram of project dependencies|The dependencies between different files making up a software project]]
+The dependencies between different files making up a software project:
-The aim of make is to satisfy the target. Each target has its own dependencies. A user generally selects a target for make to satisfy by supplying the target name on the command line. Make starts by checking whether all of the dependencies exist and have an older timestamp than the target. If so, make  does nothing, because nothing has changed. However, because a header file (that an application is not dependent on directly) can change, make propagates the changes to the 'root' of the target as shown in the picture above.
+<div align="CENTER">[[Image:make.png|Image make]]</div>
-Make rebuilds all of the necessary dependencies and targets on the way towards the target. This way, make only rebuilds those dependencies that actually affect something, and thus, saves time and effort. In big projects, the amount of time saved is significant.
+The aim of make is to satisfy the target. Each target has its own dependencies. A user will generally select a target for make to satisfy by supplying the target name on the command line. Make will start by checking, whether all of the dependencies exist and have an older timestamp than the target. If so, make will do nothing, as nothing has changed. However, since a header file (that an application is not dependent on directly) might change, make will propagate the changes to the 'root' of the target as shown in the picture above.
+Make will rebuild all of the necessary dependencies and targets on the way towards the target. This way, make will only rebuild those dependencies that actually affect something, and thus, will save time and effort. In big projects, the amount of time saved is significant.
 To illustrate this, suppose that '''file3.c''' in the above picture is modified. After that, make is run, and it will automatically rebuild the necessary targets ('''file3.o''', '''libutil.a''' and '''app'''):
-[[Image:make-mod1.png|center|frame|alt=Diagram of project files that need to be rebuilt|Project files that need to be rebuilt after file3.c is modified]]
+<div align="CENTER">[[Image:make-mod1.png|Image make-mod1]]</div>
-Now suppose that another function is added to '''file1.c'''. Then also '''util.h''' needs to be modified accordingly. The picture shows that quite a few objects and targets depend on this header file, so a sizable number of objects need to be rebuilt (but not all):
+Now suppose that another function is added to '''file1.c'''. Then also '''util.h''' would need to be modified accordingly. The picture shows that quite many objects and targets depend on this header file, so a sizable number of objects need to be rebuilt (but not all):
-[[Image:make-mod2.png|center|frame|alt=Diagram of project files that need to be rebuilt|Project files that need to be rebuilt after file1.c and util.h are modified]]
+<div align="CENTER">[[Image:make-mod2.png|Image make-mod2]]</div>
-N.B. In the example pictures, there is a project with a custom static library, which is linked against the test application.
+N.B. In the example pictures, there is a project with a custom static library, which will be linked against the test application.
-=== Simple Real Example ===
+== Simple Real Example ==
 Before delving too deeply into the syntax of makefiles, it is instructive to first see make in action. For this, a simple project will be used, written in the C language.
@@ Line 38: / Line 42: @@
 In C, it is customary to write "header" files (conventional suffix for them is '''.h''') and regular source files ('''.c'''). The header files describe calling conventions, APIs and structures that are to be made usable for the outside world. The .c files contain the implementation of these interfaces.
-The first rule in this is: if something is changed in the interface file, the binary file containing the code implementation (and other files that use the same interface) must be regenerated. Regeneration in this case means invoking gcc to create the binary file out of the C-language source file.
+The first rule in this is: if something is changed in the interface file, then the binary file containing the code implementation (and other files that use the same interface) should be regenerated. Regeneration in this case means invoking gcc to create the binary file out of the C-language source file.
 Make needs to be told two things at this point:
-* If a file's content changes, which other files will be affected? Because a single interface likely affects multiple other files, make uses a reversed ordering here. For each resulting file, it is necessary to list the files on which this one file depends on.
+* If a file's content changes, which other files will be affected? Since a single interface will likely affect multiple other files, make uses a reversed ordering here. For each resulting file, it is necessary to list the files on which this one file depends on.
 * What are the commands to regenerate the resulting files when the need arises?
-This example deals with that as simply as possible. There is a project that consists of two source files and one header file. The contents of these files are listed below: [https://vcs.maemo.org/svn/maemoexamples/tags/maemo_5.0/simple-make-files/hello.c simple-make-files/hello.c]
+This example deals with that as simply as possible. There is a project that consists of two source files and one header file. The contents of these files are listed below: simple-make-files/hello.c
-<source lang="c">
+ <tt><span>''<span><font color="#9A1900">/**</font></span>''</span>
-/**
+  <span>''<span><font color="#9A1900"> * The old faithful hello world.</font></span>''</span>
-  * The old faithful hello world.
+  <span>''<span><font color="#9A1900"> *</font></span>''</span>
-  *
+  <span>''<span><font color="#9A1900"> * This maemo code example is licensed under a MIT-style license,</font></span>''</span>
-  * This maemo code example is licensed under a MIT-style license,
+  <span>''<span><font color="#9A1900"> * that can be found in the file called "License" in the same</font></span>''</span>
-  * that can be found in the file called "License" in the same
+  <span>''<span><font color="#9A1900"> * directory as this file.</font></span>''</span>
-  * directory as this file.
+  <span>''<span><font color="#9A1900"> * Copyright (c) 2007-2008 Nokia Corporation. All rights reserved.</font></span>''</span>
-  * Copyright (c) 2007-2008 Nokia Corporation. All rights reserved.
+  <span>''<span><font color="#9A1900"> */</font></span>''</span>
-  */
+ <span>'''<span><font color="#000080"><nowiki>#include</nowiki></font></span>'''</span> <span><font color="#FF0000">&lt;stdlib.h&gt;</font></span>    <span>''<span><font color="#9A1900">/* EXIT_* */</font></span>''</span>
-#include <stdlib.h>    /* EXIT_* */
+ <span>'''<span><font color="#000080"><nowiki>#include</nowiki></font></span>'''</span> <span><font color="#FF0000">"hello_api.h"</font></span> <span>''<span><font color="#9A1900">/* sayhello */</font></span>''</span>
-#include "hello_api.h" /* sayhello */
+ <span><font color="#009900">int</font></span> <span>'''<span><font color="#000000">main</font></span>'''</span><span><font color="#990000">(</font></span><span><font color="#009900">int</font></span> argc<span><font color="#990000">,</font></span> <span><font color="#009900">char</font></span> <span><font color="#990000"><nowiki>**</nowiki></font></span>argv<span><font color="#990000">)</font></span> <span><font color="#FF0000">{</font></span>
-int main(int argc, char **argv) {
+   <span>'''<span><font color="#000000">sayhello</font></span>'''</span><span><font color="#990000">();</font></span>
-  sayhello();
+   <span>'''<span><font color="#0000FF">return</font></span>'''</span> EXIT_SUCCESS<span><font color="#990000"><nowiki>;</nowiki></font></span>
-  return EXIT_SUCCESS;
+ <span><font color="#FF0000">}</font></span>
-}
+ </tt>
-</source>
-[https://vcs.maemo.org/svn/maemoexamples/tags/maemo_5.0/simple-make-files/hello_func.c simple-make-files/hello_func.c]
+simple-make-files/hello_func.c
-<source lang="c">
+ <tt><span>''<span><font color="#9A1900">/**</font></span>''</span>
-/**
+  <span>''<span><font color="#9A1900"> * Implementation of sayhello.</font></span>''</span>
-  * Implementation of sayhello.
+  <span>''<span><font color="#9A1900"> *</font></span>''</span>
-  *
+  <span>''<span><font color="#9A1900"> * This maemo code example is licensed under a MIT-style license,</font></span>''</span>
-  * This maemo code example is licensed under a MIT-style license,
+  <span>''<span><font color="#9A1900"> * that can be found in the file called "License" in the same</font></span>''</span>
-  * that can be found in the file called "License" in the same
+  <span>''<span><font color="#9A1900"> * directory as this file.</font></span>''</span>
-  * directory as this file.
+  <span>''<span><font color="#9A1900"> * Copyright (c) 2007-2008 Nokia Corporation. All rights reserved.</font></span>''</span>
-  * Copyright (c) 2007-2008 Nokia Corporation. All rights reserved.
+  <span>''<span><font color="#9A1900"> */</font></span>''</span>
-  */
+ <span>'''<span><font color="#000080"><nowiki>#include</nowiki></font></span>'''</span> <span><font color="#FF0000">&lt;stdio.h&gt;</font></span>     <span>''<span><font color="#9A1900">/* printf */</font></span>''</span>
-#include <stdio.h>     /* printf */
+ <span>'''<span><font color="#000080"><nowiki>#include</nowiki></font></span>'''</span> <span><font color="#FF0000">"hello_api.h"</font></span> <span>''<span><font color="#9A1900">/* sayhello declaration */</font></span>''</span>
-#include "hello_api.h" /* sayhello declaration */
+ <span><font color="#009900">void</font></span> <span>'''<span><font color="#000000">sayhello</font></span>'''</span><span><font color="#990000">(</font></span><span><font color="#009900">void</font></span><span><font color="#990000">)</font></span> <span><font color="#FF0000">{</font></span>
+   <span>'''<span><font color="#000000">printf</font></span>'''</span><span><font color="#990000">(</font></span><span><font color="#FF0000">"Hello world!</font></span><span><font color="#CC33CC">\n</font></span><span><font color="#FF0000">"</font></span><span><font color="#990000">);</font></span>
+ <span><font color="#FF0000">}</font></span>
+ </tt>
-void sayhello(void) {
+simple-make-files/hello_api.h
-  printf("Hello world!\n");
-}
-</source>
-[https://vcs.maemo.org/svn/maemoexamples/tags/maemo_5.0/simple-make-files/hello_api.h simple-make-files/hello_api.h]
+ <tt><span>''<span><font color="#9A1900">/**</font></span>''</span>
+ <span>''<span><font color="#9A1900"> * Interface description for the hello_func module.</font></span>''</span>
-<source lang="c">
+  <span>''<span><font color="#9A1900"> *</font></span>''</span>
-/**
+  <span>''<span><font color="#9A1900"> * This maemo code example is licensed under a MIT-style license,</font></span>''</span>
- * Interface description for the hello_func module.
+  <span>''<span><font color="#9A1900"> * that can be found in the file called "License" in the same</font></span>''</span>
-  *
+  <span>''<span><font color="#9A1900"> * directory as this file.</font></span>''</span>
-  * This maemo code example is licensed under a MIT-style license,
+  <span>''<span><font color="#9A1900"> * Copyright (c) 2007-2008 Nokia Corporation. All rights reserved.</font></span>''</span>
-  * that can be found in the file called "License" in the same
+  <span>''<span><font color="#9A1900"> */</font></span>''</span>
-  * directory as this file.
-  * Copyright (c) 2007-2008 Nokia Corporation. All rights reserved.
+ <span>'''<span><font color="#000080"><nowiki>#ifndef</nowiki></font></span>'''</span> INCLUDE_HELLO_API_H
-  */
+ <span>'''<span><font color="#000080"><nowiki>#define</nowiki></font></span>'''</span> INCLUDE_HELLO_API_H
+ <span>''<span><font color="#9A1900">/* The above is protection against circular header inclusion. */</font></span>''</span>
-#ifndef INCLUDE_HELLO_API_H
-#define INCLUDE_HELLO_API_H
+ <span>''<span><font color="#9A1900">/* Function to print out "Hello world!\n". */</font></span>''</span>
-/* The above is protection against circular header inclusion. */
+ <span>'''<span><font color="#0000FF">extern</font></span>'''</span> <span><font color="#009900">void</font></span> <span>'''<span><font color="#000000">sayhello</font></span>'''</span><span><font color="#990000">(</font></span><span><font color="#009900">void</font></span><span><font color="#990000">);</font></span>
-/* Function to print out "Hello world!\n". */
+ <span>'''<span><font color="#000080"><nowiki>#endif</nowiki></font></span>'''</span>
-extern void sayhello(void);
+ <span>''<span><font color="#9A1900">/* ifndef INCLUDE_HELLO_API_H */</font></span>''</span>
+ </tt>
-#endif
-/* ifndef INCLUDE_HELLO_API_H */
-</source>
-So, in effect, there is the main application in '''hello.c''', which uses a function that is implemented in '''hello_func.c''' and declared in '''hello_api.h'''. Building an application out of these files can be performed manually like this:
+So, in effect, there is the main application in '''hello.c''', which uses a function that is implemented in '''hello_func.c''' and declared in '''hello_api.h'''. Building an application out of these files could be performed manually like this:
   gcc -Wall hello.c hello_func.c -o hello
-Or, it can be done in three stages:
+Or, it could be done in three stages:
   gcc -Wall -c hello.c -o hello.o
@@ Line 123: / Line 124: @@
 In the second case, gcc is instructed to create a binary object file for each of the source files. After that, gcc is instructed to link these output files ('''hello.o''' and '''hello_func.o''') together, and store the linked code into '''hello'''.
-{{ambox|text=When gcc reads through the C source files, it also reads in the header files, because the C code uses the <code>#include</code> preprocessor directive. This is because gcc internally runs all files ending with .c through cpp (the preprocessor) first.}}
+N.B. When gcc reads through the C source files, it will also read in the header files, since the C code uses the #include -preprocessor directive. This is because gcc will internally run all files ending with .c through cpp (the preprocessor) first.
-The file describing this situation to make is as follows: [https://vcs.maemo.org/svn/maemoexamples/tags/maemo_5.0/simple-make-files/Makefile simple-make-files/Makefile]
+The file describing this situation to make is as follows: simple-make-files/Makefile
-<source lang="make">
+ <tt><span>''<span><font color="#9A1900"><nowiki># define default target (first target = default)</nowiki></font></span>''</span>
-# define default target (first target = default)
+ <span>''<span><font color="#9A1900"><nowiki># it depends on 'hello.o' (which will be created if necessary)</nowiki></font></span>''</span>
-# it depends on 'hello.o' (which will be created if necessary)
+ <span>''<span><font color="#9A1900"><nowiki># and hello_func.o (same as hello.o)</nowiki></font></span>''</span>
-# and hello_func.o (same as hello.o)
+ hello<span><font color="#990000"><nowiki>:</nowiki></font></span> hello<span><font color="#990000">.</font></span>o hello_func<span><font color="#990000">.</font></span>o
-hello: hello.o hello_func.o
+         gcc -Wall hello<span><font color="#990000">.</font></span>o hello_func<span><font color="#990000">.</font></span>o -o hello
-        gcc -Wall hello.o hello_func.o -o hello
+ <span>''<span><font color="#9A1900"><nowiki># define hello.o target</nowiki></font></span>''</span>
-# define hello.o target
+ <span>''<span><font color="#9A1900"><nowiki># it depends on hello.c (and is created from it)</nowiki></font></span>''</span>
-# it depends on hello.c (and is created from it)
+ <span>''<span><font color="#9A1900"><nowiki># also depends on hello_api.h which would mean that</nowiki></font></span>''</span>
-# also depends on hello_api.h which would mean that
+ <span>''<span><font color="#9A1900"><nowiki># changing the hello.h api would force make to rebuild</nowiki></font></span>''</span>
-# changing the hello.h api would force make to rebuild
+ <span>''<span><font color="#9A1900"><nowiki># this target (hello.o).</nowiki></font></span>''</span>
-# this target (hello.o).
+ <span>''<span><font color="#9A1900"><nowiki># gcc -c: compile only, do not link</nowiki></font></span>''</span>
-# gcc -c: compile only, do not link
+ hello<span><font color="#990000">.</font></span>o<span><font color="#990000"><nowiki>:</nowiki></font></span> hello<span><font color="#990000">.</font></span>c hello_api<span><font color="#990000">.</font></span>h
-hello.o: hello.c hello_api.h
+         gcc -Wall -c hello<span><font color="#990000">.</font></span>c -o hello<span><font color="#990000">.</font></span>o
-        gcc -Wall -c hello.c -o hello.o
+ <span>''<span><font color="#9A1900"><nowiki># define hello_func.o target</nowiki></font></span>''</span>
-# define hello_func.o target
+ <span>''<span><font color="#9A1900"><nowiki># it depends on hello_func.c (and is created from)</nowiki></font></span>''</span>
-# it depends on hello_func.c (and is created from)
+ <span>''<span><font color="#9A1900"><nowiki># and hello_api.h (since that's its declaration)</nowiki></font></span>''</span>
-# and hello_api.h (since that's its declaration)
+ hello_func<span><font color="#990000">.</font></span>o<span><font color="#990000"><nowiki>:</nowiki></font></span> hello_func<span><font color="#990000">.</font></span>c hello_api<span><font color="#990000">.</font></span>h
-hello_func.o: hello_func.c hello_api.h
+         gcc -Wall -c hello_func<span><font color="#990000">.</font></span>c -o hello_func<span><font color="#990000">.</font></span>o
-        gcc -Wall -c hello_func.c -o hello_func.o
+ <span>''<span><font color="#9A1900"><nowiki># </nowiki></font></span>''</span></tt>
-#
-</source>
-This file is in the simplest form without using any variables or relying on built-in magic in GNU make. Later it will be shown that the same rules can be written in a much shorter way.
+This file is in the simplest form without using any variables or relying on built-in magic in GNU make. Later it will be shown that the same rules could be written in a much shorter way.
 This makefile can be tested by running make in the directory that contains the makefile and the source files:
@@ Line 176: / Line 175: @@
   Hello world!
-=== Anatomy of Makefile ===
+== Anatomy of Makefile ==
-From the simple example above, some of the syntax of 'make' can be deduced.
+From the simple example above, some of syntax of 'make' can be deduced.
 Here are the rules that can be learned:
 * Comments are lines that start with the #-character. To be more precise, when make reads the makefile, it will ignore the #-character and any characters after it up to the end of the line. This means that comments can also be put at the end of lines, and make will ignore them, but this is considered bad practice as it would lead to subtle problems later on.
-* The backslash character (<code>\</code>) can be used to escape the special meaning of the next character. The most important special character in makefiles is the dollar character ($), which is used to access the contents of variables. There are also other special characters. To continue a line that is too long, the newline character can be escaped on that line. When the backslash is put at the end of the line, make ignores the newline when reading input.
+* The backslash character (<code>\</code>) can be used to escape the special meaning of the next character. The most important special character in makefiles is the dollar character ($), which is used to access the contents of variables. There are also other special characters. To continue a line that is too long, the newline character can be escaped on that line. When the backslash is put at the end of the line, make will ignore the newline when reading input.
 * Empty lines by themselves are ignored.
 * A line that starts at column 0 (start of the line) and contains a colon character (:) is considered a rule. The name on the left side of the colon is created by the commands. This name is called a target. Any filenames specified after the colon are the files that the target depends on. They are called prerequisites (i.e. they are required to exist, before make decides to create the target.
-* Lines starting with the tabulation character (tab) are commands that make  runs to achieve the target.
+* Lines starting with the tabulation character (tab) are commands that make will run to achieve the target.
-In the printed material, the tabs are represented with whitespace, so be careful when reading the example makefiles. Note also that in reality, the command lines are considered as a part of the rule.
+In the printed material, the tabs are represented with whitespace, so be careful when reading the example makefiles. Note also that in reality, the command lines are considered as part of the rule.
 Using these rules, it can now be deduced that:
-* make regenerates '''hello''' when either or both of its prerequisites change. So, if either '''hello.o''' or '''hello_func.o''' change, make  regenerates '''hello''' by using the command: <code>gcc -Wall hello.o hello_func.o -o hello</code>
+* make will regenerate '''hello''' when either or both of its prerequisites change. So, if either '''hello.o''' or '''hello_func.o''' change, make will regenerate '''hello''' by using the command: <code>gcc -Wall hello.o hello_func.o -o hello</code>
-* If either '''hello.c''' or '''hello_api.h''' change, make  regenerates '''hello.o'''.
+* If either '''hello.c''' or '''hello_api.h''' change, make will regenerate '''hello.o'''.
-* If either '''hello_func.c''' or '''hello_api.h''' change, make regenerates <br />'''hello_func.o'''.
+* If either '''hello_func.c''' or '''hello_api.h''' change, make will regenerate <br />'''hello_func.o'''.
-=== Default Goal ===
+== Default Goal ==
-Note that make was not explicitly told what it should do by default when run without any command line parameters (as was done above). How does it know that creating '''hello''' is the target for the run?
+It should be noted that make was not explicitly told what it should do by default when run without any command line parameters (as was done above). How does it know that creating '''hello''' is the target for the run?
 The first target given in a makefile is the default target. A target that achieves some higher-level goal (like linking all the components into the final application) is sometimes called a goal in GNU make documentation.
@@ Line 204: / Line 203: @@
 So, the first target in the makefile is the default goal when make is run without command line parameters.
-N.B. Make automatically learns the dependencies between the various components and deduces that to create '''hello''', it also needs to create '''hello.o''' and '''hello_func.o'''. Make regenerates the missing prerequisites when necessary. In fact, this is a quality that causes make do its magic.
+N.B. In a magic-like way, make will automatically learn the dependencies between the various components and deduce that in order to create '''hello''', it will also need to create '''hello.o''' and '''hello_func.o'''. Make will regenerate the missing prerequisites when necessary. In fact, this is a quality that causes make do its magic.
-Because the prerequisites for hello (hello.o and hello_func.o) do not exist, and hello is the default goal, make first creates the files that the hello target needs. This can be evidenced from the screen capture of make running without command line parameters. It shows the execution of each command in the order that make decides is necessary to satisfy the default goal's prerequisites, and finally create the hello.
+Since the prerequisites for hello (hello.o and hello_func.o) do not exist, and hello is the default goal, make will first create the files that the hello target needs. This can be evidenced from the screen capture of make running without command line parameters. It shows the execution of each command in the order that make decides is necessary to satisfy the default goal's prerequisites, and finally create the hello.
   user@system:~$ make
@@ Line 213: / Line 212: @@
   gcc -Wall hello.o hello_func.o -o hello
-=== Names of Makefiles ===
-The recommended name for the makefile is '''Makefile'''. This is not the first filename that GNU make tries to open, but it is the most portable one. In fact, the order of filenames that make attempts to open is: '''GNUMakefile''', '''Makefile''' and finally '''makefile'''.
+== Names of Makefiles ==
-Unless you are sure that your makefile does not work on other make systems (not GNU), refrain from using GNUMakefile. Makefile will be used here for the most of this material. The idea behind using Makefile instead of makefile is related to how shells and commands sort filenames, when contents of directories are requested. Because in ASCII the uppercase letters come before the lowercase letters, the important files are listed first. Makefiles are considered important, because they are the basis for building the project. (The collation order might be different in your locale and your environment.)
+The recommended name for the makefile is '''Makefile'''. This is not the first filename that GNU make will try to open, but it is the most portable one. In fact, the order of filenames that make attempts to open is: '''GNUMakefile''', '''Makefile''' and finally '''makefile'''.
-Make can explicitly be told which file to read by using the -f command line option. This option is used in the next example.
+Unless one is sure that one's makefile will not work on other make systems (not GNU), one should refrain from using GNUMakefile. Makefile will be used here for the most of this material. The idea behind using Makefile instead of makefile is related to how shells and commands sort filenames, when contents of directories are requested. Since in ASCII the uppercase letters come before the lowercase letters, the important files are listed first. Makefiles are considered important, since they are the basis for building the project. (The collation order might be different in your locale and your environment.)
-=== Questions ===
+Make can explicitly be told which file to read by using the -f command line option. This option will be used in the next example.
+== Questions ==
 Based on common sense, what should make do when it is run after:
@@ Line 234: / Line 234: @@
 What would be done when writing the commands manually?
-=== Adding Make Goals ===
+== Adding Make Goals ==
-Sometimes it is useful to add targets, whose execution does not result in a file, but instead causes some commands to be run. This is commonly used in makefiles of software projects to get rid of the binary files, so that building can be attempted from a clean state. These kinds of targets can also be justifiably called goals. GNU documentation uses the name "phony target" for these kinds of targets, because they do not result in creating a file, like normal targets do.
+Sometimes it is useful to add targets, whose execution does not result in a file, but instead causes some commands to be run. This is commonly used in makefiles of software projects to get rid of the binary files, so that building can be attempted from a clean state. These kinds of targets can also be justifiably called goals. GNU documentation uses the name "phony target" for these kinds of targets, since they do not result in creating a file, like normal targets do.
-The next step is to create a copy of the original makefile, and add a goal that removes the binary object files and the application.
+The next step is to create a copy of the original makefile, and add a goal that will remove the binary object files and the application. N.B. Other parts of the makefile do not change. simple-make-files/Makefile.2
-N.B. Other parts of the makefile do not change. [https://vcs.maemo.org/svn/maemoexamples/tags/maemo_5.0/simple-make-files/Makefile.2 simple-make-files/Makefile.2]
-<source lang="make">
+ <tt><span>''<span><font color="#9A1900"><nowiki># add a cleaning target (to get rid of the binaries)</nowiki></font></span>''</span>
-# add a cleaning target (to get rid of the binaries)
+ <span>''<span><font color="#9A1900"><nowiki># define default target (first target = default)</nowiki></font></span>''</span>
-# define default target (first target = default)
+ <span>''<span><font color="#9A1900"><nowiki># it depends on 'hello.o' (which must exist)</nowiki></font></span>''</span>
-# it depends on 'hello.o' (which must exist)
+ <span>''<span><font color="#9A1900"><nowiki># and hello_func.o</nowiki></font></span>''</span>
-# and hello_func.o
+ hello<span><font color="#990000"><nowiki>:</nowiki></font></span> hello<span><font color="#990000">.</font></span>o hello_func<span><font color="#990000">.</font></span>o
-hello: hello.o hello_func.o
+         gcc -Wall hello<span><font color="#990000">.</font></span>o hello_func<span><font color="#990000">.</font></span>o -o hello
-        gcc -Wall hello.o hello_func.o -o hello
+ <span>''<span><font color="#9A1900"><nowiki># define hello.o target</nowiki></font></span>''</span>
-# define hello.o target
+ <span>''<span><font color="#9A1900"><nowiki># it depends on hello.c (and is created from)</nowiki></font></span>''</span>
-# it depends on hello.c (and is created from)
+ <span>''<span><font color="#9A1900"><nowiki># also depends on hello_api.h which would mean that</nowiki></font></span>''</span>
-# also depends on hello_api.h which would mean that
+ <span>''<span><font color="#9A1900"><nowiki># changing the hello.h api would force make to rebuild</nowiki></font></span>''</span>
-# changing the hello.h api would force make to rebuild
+ <span>''<span><font color="#9A1900"><nowiki># this target (hello.o).</nowiki></font></span>''</span>
-# this target (hello.o).
+ <span>''<span><font color="#9A1900"><nowiki># gcc -c: compile only, do not link</nowiki></font></span>''</span>
-# gcc -c: compile only, do not link
+ hello<span><font color="#990000">.</font></span>o<span><font color="#990000"><nowiki>:</nowiki></font></span> hello<span><font color="#990000">.</font></span>c hello_api<span><font color="#990000">.</font></span>h
-hello.o: hello.c hello_api.h
+         gcc -Wall -c hello<span><font color="#990000">.</font></span>c -o hello<span><font color="#990000">.</font></span>o
-        gcc -Wall -c hello.c -o hello.o
+ <span>''<span><font color="#9A1900"><nowiki># define hello_func.o target</nowiki></font></span>''</span>
-# define hello_func.o target
+ <span>''<span><font color="#9A1900"><nowiki># it depends on hello_func.c (and is created from)</nowiki></font></span>''</span>
-# it depends on hello_func.c (and is created from)
+ <span>''<span><font color="#9A1900"><nowiki># and hello_api.h (since that's it's declaration)</nowiki></font></span>''</span>
-# and hello_api.h (since that's it's declaration)
+ hello_func<span><font color="#990000">.</font></span>o<span><font color="#990000"><nowiki>:</nowiki></font></span> hello_func<span><font color="#990000">.</font></span>c hello_api<span><font color="#990000">.</font></span>h
-hello_func.o: hello_func.c hello_api.h
+         gcc -Wall -c hello_func<span><font color="#990000">.</font></span>c -o hello_func<span><font color="#990000">.</font></span>o
-        gcc -Wall -c hello_func.c -o hello_func.o
+ <span>''<span><font color="#9A1900"><nowiki># This is the definition of the target 'clean'</nowiki></font></span>''</span>
-# This is the definition of the target 'clean'
+ <span>''<span><font color="#9A1900"><nowiki># Here we'll remove all the built binaries and</nowiki></font></span>''</span>
-# Here we'll remove all the built binaries and
+ <span>''<span><font color="#9A1900"><nowiki># all the object files that we might have generated</nowiki></font></span>''</span>
-# all the object files that we might have generated
+ <span>''<span><font color="#9A1900"><nowiki># Notice the -f flag for rm, it means "force" which</nowiki></font></span>''</span>
-# Notice the -f flag for rm, it means "force" which
+ <span>''<span><font color="#9A1900"><nowiki># in turn means that rm will try to remove the given</nowiki></font></span>''</span>
-# in turn means that rm will try to remove the given
+ <span>''<span><font color="#9A1900"><nowiki># files, and if there are none, then that's ok. Also</nowiki></font></span>''</span>
-# files, and if there are none, then that's ok. Also
+ <span>''<span><font color="#9A1900"><nowiki># it means that we have no writing permission to that</nowiki></font></span>''</span>
-# it means that we have no writing permission to that
+ <span>''<span><font color="#9A1900"><nowiki># file and have writing permission to the directory</nowiki></font></span>''</span>
-# file and have writing permission to the directory
+ <span>''<span><font color="#9A1900"><nowiki># holding the file, rm will not then ask for permission</nowiki></font></span>''</span>
-# holding the file, rm will not then ask for permission
+ <span>''<span><font color="#9A1900"><nowiki># interactivelly.</nowiki></font></span>''</span>
-# interactivelly.
+ clean<span><font color="#990000"><nowiki>:</nowiki></font></span>
-clean:
+         rm -f hello hello<span><font color="#990000">.</font></span>o hello_func<span><font color="#990000">.</font></span>o
-        rm -f hello hello.o hello_func.o
+ </tt>
-</source>
-To get make to use this file instead of the default Makefile, use the -f command line parameter as follows:
+In order for make to use this file instead of the default Makefile, the -f command line parameter needs to be used as follows:
   user@system:~$ make -f Makefile.2
@@ Line 282: / Line 280: @@
   gcc -Wall hello.o hello_func.o -o hello
-To control which target make processes (instead of the default goal), give the target name as a command line parameter like this:
+To control which target make will process (instead of the default goal), target name needs to be given as command line parameter like this:
   user@system:~$ make -f Makefile.2 clean
   rm -f hello hello.o hello_func.o
@@ Line 297: / Line 295: @@
   -rw-r--r-- 1  user user 130  Jun 1  14:48 hello_func.c
-=== Making One Target at a Time ===
+== Making One Target at a Time ==
 Sometimes it is useful to ask make to process only one target. Similar to the clean case, it just needs the target name to be given on the command line:
@@ Line 310: / Line 308: @@
   gcc -Wall hello.o hello_func.o -o hello
-This can be done with any number of targets, even phony ones. Make tries to complete all of them in the order that they are on the command line. If any of the commands within the targets fail, make aborts at that point, and does not pursue the rest of the targets.
+This can be done with any number of targets, even phony ones. Make will try and complete all of them in the order that they are on the command line. Should any of the commands within the targets fail, make will abort at that point, and will not pursue the rest of the targets.
-=== PHONY Keyword ===
+==PHONY Keyword ==
-Suppose that for some reason a file called '''clean''' appears in the directory in which make is run with clean as the target. In this case, make probably decides that because clean already exists, there is no need to run the commands leading to the target, and in this case, make does not run the rm command at all. Clearly this is something that needs to be avoided.
+Suppose that for some reason or another, a file called '''clean''' appears in the directory in which make is run with clean as the target. In this case, make would probably decide that since clean already exists, there is no need to run the commands leading to the target, and in this case, make would not run the rm command at all. Clearly this is something that needs to be avoided.
-For these cases, GNU make provides a special target called <code>.PHONY</code> (note the leading dot). The real phony targets (clean) will be listed as a dependency to <code>.PHONY</code>. This signals to make that it should never consider a file called clean to be the result of the phony target.
+For these cases, GNU make provides a special target called '''.PHONY''' (note the leading dot). The real phony targets (clean) will be listed as a dependency to .PHONY. This will signal to make that it should never consider a file called clean to be the result of the phony target.
 In fact, this is what most open source projects that use make do.
-This leads in the following makefile (comments omitted for brevity): [https://vcs.maemo.org/svn/maemoexamples/tags/maemo_5.0/simple-make-files/Makefile.3 simple-make-files/Makefile.3]
+This leads in the following makefile (comments omitted for brevity): simple-make-files/Makefile.3
-<source lang="make">
+ <tt>hello<span><font color="#990000"><nowiki>:</nowiki></font></span> hello<span><font color="#990000">.</font></span>o hello_func<span><font color="#990000">.</font></span>o
-hello: hello.o hello_func.o
+         gcc -Wall hello<span><font color="#990000">.</font></span>o hello_func<span><font color="#990000">.</font></span>o -o hello
-        gcc -Wall hello.o hello_func.o -o hello
+ hello<span><font color="#990000">.</font></span>o<span><font color="#990000"><nowiki>:</nowiki></font></span> hello<span><font color="#990000">.</font></span>c hello_api<span><font color="#990000">.</font></span>h
-hello.o: hello.c hello_api.h
+         gcc -Wall -c hello<span><font color="#990000">.</font></span>c -o hello<span><font color="#990000">.</font></span>o
-        gcc -Wall -c hello.c -o hello.o
+ hello_func<span><font color="#990000">.</font></span>o<span><font color="#990000"><nowiki>:</nowiki></font></span> hello_func<span><font color="#990000">.</font></span>c hello_api<span><font color="#990000">.</font></span>h
-hello_func.o: hello_func.c hello_api.h
+         gcc -Wall -c hello_func<span><font color="#990000">.</font></span>c -o hello_func<span><font color="#990000">.</font></span>o
-        gcc -Wall -c hello_func.c -o hello_func.o
+ <span><font color="#990000">.</font></span>PHONY<span><font color="#990000"><nowiki>:</nowiki></font></span> clean
-.PHONY: clean
+ clean<span><font color="#990000"><nowiki>:</nowiki></font></span>
-clean:
+         rm -f hello hello<span><font color="#990000">.</font></span>o hello_func<span><font color="#990000">.</font></span>o
-        rm -f hello hello.o hello_func.o
+ </tt>
-</source>
-=== Specifying Default Goal ===
+== Specifying Default Goal ==
-Make uses the first target in a makefile as its default goal. What if there is a need to explicitly set the default goal instead? Because it is not possible to actually change the "first target is the default goal" setting in make, this needs to be taken into account. So, a new target has to be added, and made sure that it will be processed as the first target in a makefile.
+Make will use the first target in a makefile as its default goal. What if there is a need to explicitly set the default goal instead? Since it is not possible to actually change the "first target is the default goal" setting in make, this needs to be taken into account. So, a new target has to be added, and made sure that it will be processed as the first target in a makefile.
-To achieve this, a new phony target must be created, and the wanted targets should be listed as the phony target's prerequisites. Any name can be used for the target, but all is a very common name for this use. The only thing that needs to be rememberd is that this target needs to be the first one in the makefile. [https://vcs.maemo.org/svn/maemoexamples/tags/maemo_5.0/simple-make-files/Makefile.4 simple-make-files/Makefile.4]
+In order to achieve this, a new phony target should be created, and the wanted targets should be listed as the phony target's prerequisites. Any name can be used for the target, but all is a very common name for this use. The only thing that needs to be rememberd is that this target needs to be the first one in the makefile. simple-make-files/Makefile.4
-<source lang="make">
+ <tt><span><font color="#990000">.</font></span>PHONY<span><font color="#990000"><nowiki>:</nowiki></font></span> all
-.PHONY: all
+ all<span><font color="#990000"><nowiki>:</nowiki></font></span> hello
-all: hello
+ hello<span><font color="#990000"><nowiki>:</nowiki></font></span> hello<span><font color="#990000">.</font></span>o hello_func<span><font color="#990000">.</font></span>o
-hello: hello.o hello_func.o
+         gcc -Wall hello<span><font color="#990000">.</font></span>o hello_func<span><font color="#990000">.</font></span>o -o hello
-        gcc -Wall hello.o hello_func.o -o hello
+ hello<span><font color="#990000">.</font></span>o<span><font color="#990000"><nowiki>:</nowiki></font></span> hello<span><font color="#990000">.</font></span>c hello_api<span><font color="#990000">.</font></span>h
-hello.o: hello.c hello_api.h
+         gcc -Wall -c hello<span><font color="#990000">.</font></span>c -o hello<span><font color="#990000">.</font></span>o
-        gcc -Wall -c hello.c -o hello.o
+ hello_func<span><font color="#990000">.</font></span>o<span><font color="#990000"><nowiki>:</nowiki></font></span> hello_func<span><font color="#990000">.</font></span>c hello_api<span><font color="#990000">.</font></span>h
-hello_func.o: hello_func.c hello_api.h
+         gcc -Wall -c hello_func<span><font color="#990000">.</font></span>c -o hello_func<span><font color="#990000">.</font></span>o
-        gcc -Wall -c hello_func.c -o hello_func.o
+ <span><font color="#990000">.</font></span>PHONY<span><font color="#990000"><nowiki>:</nowiki></font></span> clean
-.PHONY: clean
+ clean<span><font color="#990000"><nowiki>:</nowiki></font></span>
-clean:
+         rm -f hello hello<span><font color="#990000">.</font></span>o hello_func<span><font color="#990000">.</font></span>o
-        rm -f hello hello.o hello_func.o
+ </tt>
-</source>
-Something peculiar can be seen in the listing above. Because the first target is the default goal for make, would that not make <code>.PHONY</code> now to be the default target? Because <code>.PHONY</code> is a special target in GNU make, this is safe. Also, because of compatibility reasons, GNU make ignores any targets that start with a leading dot (.) when looking for the default goal.
+Something peculiar can be seen in the listing above. Since the first target is the default goal for make, would that not make .PHONY now to be the default target? Since .PHONY is a special target in GNU make, this is safe. Also, because of compatibility reasons, GNU make will ignore any targets that start with a leading dot (.) when looking for the default goal.
-=== Other Common Phony Goals ===
+== Other Common Phony Goals ==
-Many other phony goals are encountered in makefiles that projects use.
+Many other phony goals will be encountered in makefiles that projects use.
 Some of the more common ones include:
-* install: Prerequisites for install is the software application binary (or binaries). The commands (normally ''install'' is used on Linux) will specify which binary file to place under which directory on the system (<code>/usr/bin</code>, <code>/usr/local/bin</code>, etc).
+* install: Prerequisites for install is the software application binary (or binaries). The commands (normally ''install'' is used on Linux) will specify which binary file to place under which directory on the system (/usr/bin, /usr/local/bin, etc).
 * distclean: Similar to clean; removes object files and such, but removes other files as well (sounds scary). Normally this is used to implement the removal of Makefile in the case that it was created by some automatic tool (''configure'' for example).
 * package: Prerequisites are as in install, but instead of installing, creates an archive file (''tar'') with the files in question. This archive can then be used to distribute the software.
-For information on other common phony targets, see [http://www.gnu.org/software/make/manual/make.html GNU make manual].
+Other common phony targets can be found in the [http://www.gnu.org/software/make/manual/make.html GNU make manual].
-=== Variables in Makefiles ===
+==  Variables in Makefiles ==
 So far these files have been listing filenames explicitly. Writing makefiles this way can get rather tedious, if not error prone.
@@ Line 376: / Line 372: @@
 Variables work almost as they do inside regular UNIX command shells. They are a simple mechanism, by which a piece of text can be associated with a name that can be referenced later on in multiple places in the makefiles. Make variables are based on text replacement, just like shell variables are.
-==== Variable Flavors ====
+== Variable Flavors ==
 The variables that can be used in makefiles come in two basic styles or flavors.
-The default flavor is where referencing a variable causes make to expand the variable contents at the point of reference. This means that if the value of the variable is some text in which other variables are referenced, their contents is also replaced automatically. This flavor is called recursive.
+The default flavor is where referencing a variable will cause make to expand the variable contents at the point of reference. This means that if the value of the variable is some text in which other variables are referenced, their contents will also be replaced automatically. This flavor is called recursive.
 The other flavor is simple, meaning that the content of a variable is evaluated only once, when the variable is defined.
-Deciding on which flavor to use is important, when the evaluation of variable contents needs to be repeatable and fast. In these cases, simple variables are often the correct solution.
+Deciding on which flavor to use might be important, when the evaluation of variable contents needs to be repeatable and fast. In these cases, simple variables are often the correct solution.
-===== Recursive Variables =====
+== Recursive Variables ==
 Here are the rules for creating recursive variables:
 * Names must contain only ASCII alphanumerics and underscores (to preserve portability).
-* Use only lowercase letters in the names of the variables. Make is case sensitive, and variable names written in capital letters are used when it is necessary to communicate the variables outside make, or their origin is from outside (environment variables). This is, however, only a convention, and there will also be variables that are local to the makefile, but still written in uppercase.
+* Only lowercase letters should be used in the names of the variables. Make is case sensitive, and variable names written in capital letters are used when it is necessary to communicate the variables outside make, or their origin is from outside (environment variables). This is, however, only a convention, and there will also be variables that are local to the makefile, but still written in uppercase.
-* Values can contain any text. The text is evaluated by make when the variable is used, not when it is defined.
+* Values may contain any text. The text will be evaluated by make when the variable is used, not when it is defined.
-* Break up long lines with a backslash character (<code>\</code>) and newline combination. Use this same mechanism to continue other long lines as well (not just variables). Do not put any whitespace after the backslash.
+* Long lines may be broken up with a backslash character (<code>\</code>) and newline combination. This same mechanism can be used to continue other long lines as well (not just variables). Do not put any whitespace after the backslash.
-* Do not reference a variable that is being defined in its text portion. This results in an endless loop whenever this variable is used. If this happens GNU make stops to an error.
+* A variable that is being defined should not be referenced in its text portion. This would result in an endless loop whenever this variable is used. If this happens GNU make will stop to an error.
-Now the previously used makefile is reused, but some variables are introduced. This also shows the syntax of defining the variables, and how to use them (reference them): [https://vcs.maemo.org/svn/maemoexamples/tags/maemo_5.0/simple-make-files/Makefile.5 simple-make-files/Makefile.5]
+Now the previously used makefile will be reused, but some variables will be introduced. This also shows the syntax of defining the variables, and how to use them (reference them): simple-make-files/Makefile.5
-<source lang="make">
+ <tt><span>''<span><font color="#9A1900"><nowiki># define the command that we use for compilation</nowiki></font></span>''</span>
-# define the command that we use for compilation
+ CC <span><font color="#990000"><nowiki>=</nowiki></font></span> gcc -Wall
-CC = gcc -Wall
+ <span>''<span><font color="#9A1900"><nowiki># which targets do we want to build by default?</nowiki></font></span>''</span>
-# which targets do we want to build by default?
+ <span>''<span><font color="#9A1900"><nowiki># note that 'targets' is just a variable, its name</nowiki></font></span>''</span>
-# note that 'targets' is just a variable, its name
+ <span>''<span><font color="#9A1900"><nowiki># does not have any special meaning to make</nowiki></font></span>''</span>
-# does not have any special meaning to make
+ targets <span><font color="#990000"><nowiki>=</nowiki></font></span> hello
-targets = hello
+ <span>''<span><font color="#9A1900"><nowiki># first target defined will be the default target</nowiki></font></span>''</span>
-# first target defined will be the default target
+ <span>''<span><font color="#9A1900"><nowiki># we use the variable to hold the dependencies</nowiki></font></span>''</span>
-# we use the variable to hold the dependencies
+ <span><font color="#990000">.</font></span>PHONY<span><font color="#990000"><nowiki>:</nowiki></font></span> all
-.PHONY: all
+ all<span><font color="#990000"><nowiki>:</nowiki></font></span> <span><font color="#009900">$(targets)</font></span>
-all: $(targets)
+ hello<span><font color="#990000"><nowiki>:</nowiki></font></span> hello<span><font color="#990000">.</font></span>o hello_func<span><font color="#990000">.</font></span>o
-hello: hello.o hello_func.o
+         <span><font color="#009900">$(CC)</font></span> hello<span><font color="#990000">.</font></span>o hello_func<span><font color="#990000">.</font></span>o -o hello
-        $(CC) hello.o hello_func.o -o hello
+ hello<span><font color="#990000">.</font></span>o<span><font color="#990000"><nowiki>:</nowiki></font></span> hello<span><font color="#990000">.</font></span>c hello_api<span><font color="#990000">.</font></span>h
-hello.o: hello.c hello_api.h
+         <span><font color="#009900">$(CC)</font></span> -c hello<span><font color="#990000">.</font></span>c -o hello<span><font color="#990000">.</font></span>o
-        $(CC) -c hello.c -o hello.o
+ hello_func<span><font color="#990000">.</font></span>o<span><font color="#990000"><nowiki>:</nowiki></font></span> hello_func<span><font color="#990000">.</font></span>c hello_api<span><font color="#990000">.</font></span>h
-hello_func.o: hello_func.c hello_api.h
+         <span><font color="#009900">$(CC)</font></span> -c hello_func<span><font color="#990000">.</font></span>c -o hello_func<span><font color="#990000">.</font></span>o
-        $(CC) -c hello_func.c -o hello_func.o
+ <span>''<span><font color="#9A1900"><nowiki># we'll make our cleaning target more powerful</nowiki></font></span>''</span>
-# we'll make our cleaning target more powerful
+ <span>''<span><font color="#9A1900"><nowiki># we remove the targets that we build by default and also</nowiki></font></span>''</span>
-# we remove the targets that we build by default and also
+ <span>''<span><font color="#9A1900"><nowiki># remove all object files</nowiki></font></span>''</span>
-# remove all object files
+ <span><font color="#990000">.</font></span>PHONY<span><font color="#990000"><nowiki>:</nowiki></font></span> clean
-.PHONY: clean
+ clean<span><font color="#990000"><nowiki>:</nowiki></font></span>
-clean:
+         rm -f <span><font color="#009900">$(targets)</font></span> <span><font color="#990000"><nowiki>*.</nowiki></font></span>o
-        rm -f $(targets) *.o
+ </tt>
-</source>
-The CC variable is the standard variable to hold the name of the C compiler executable. GNU make comes preloaded with a list of tools that can be accessed in similar way (as will be shown with $(RM) shortly, but there are others). Most UNIX tools related to building software already have similar pre-defined variables in GNU make. Here one of them is overridden to demonstrate how it is done. Overriding variables like this is not recommended, because the user running make later might want to use some other compiler, and would have to edit the makefile to do so.
+The CC variable is the standard variable to hold the name of the C compiler executable. GNU make comes preloaded with a list of tools that can be accessed in similar way (as will be shown with $(RM) shortly, but there are others). Most UNIX tools related to building software already have similar pre-defined variables in GNU make. Here one of them will be overridden for no other reason than to demonstrate how it is done. Overriding variables like this is not recommended, since the user running make later might want to use some other compiler, and would have to edit the makefile to do so.
-===== Simple Variables =====
+== Simple Variables ==
-Suppose you have a makefile like this: [https://vcs.maemo.org/svn/maemoexamples/tags/maemo_5.0/simple-make-files/Makefile.6 simple-make-files/Makefile.6]
+Suppose you have a makefile like this: simple-make-files/Makefile.6
-<source lang="make">
+ <tt>CC <span><font color="#990000"><nowiki>=</nowiki></font></span> gcc -Wall
-CC = gcc -Wall
+ <span>''<span><font color="#9A1900"><nowiki># we want to add something to the end of the variable</nowiki></font></span>''</span>
-# we want to add something to the end of the variable
+ CC <span><font color="#990000"><nowiki>=</nowiki></font></span> <span><font color="#009900">$(CC)</font></span> -g
-CC = $(CC) -g
+ hello<span><font color="#990000">.</font></span>o<span><font color="#990000"><nowiki>:</nowiki></font></span> hello<span><font color="#990000">.</font></span>c hello_api<span><font color="#990000">.</font></span>h
-hello.o: hello.c hello_api.h
+         <span><font color="#009900">$(CC)</font></span> -c hello<span><font color="#990000">.</font></span>c -o hello<span><font color="#990000">.</font></span>o
-        $(CC) -c hello.c -o hello.o
+ </tt>
-</source>
-What might seem quite logical to a human reader, does not seem very logical to make.
+What might seem quite logical to a human reader, will not seem very logical to make.
-Because the contents of recursive variables are evaluated when they are referenced, it can be seen that the above fragment will lead to an infinite loop.
+Since the contents of recursive variables are evaluated when they are referenced, it can be seen that the above fragment will lead to an infinite loop.
-How can this be corrected? Make actually provides two mechanisms for this. This is the solution with simple variables: [https://vcs.maemo.org/svn/maemoexamples/tags/maemo_5.0/simple-make-files/Makefile.7 simple-make-files/Makefile.7]
+How can this be corrected? Make actually provides two mechanisms for this. This is the solution with simple variables: simple-make-files/Makefile.7
-<source lang="make">
+ <tt>CC <span><font color="#990000"><nowiki>:=</nowiki></font></span> gcc -Wall
-CC := gcc -Wall
+ <span>''<span><font color="#9A1900"><nowiki># we want to add something to the end of the variable</nowiki></font></span>''</span>
-# we want to add something to the end of the variable
+ CC <span><font color="#990000"><nowiki>:=</nowiki></font></span> <span><font color="#009900">$(CC)</font></span> -g
-CC := $(CC) -g
+ hello<span><font color="#990000">.</font></span>o<span><font color="#990000"><nowiki>:</nowiki></font></span> hello<span><font color="#990000">.</font></span>c hello_api<span><font color="#990000">.</font></span>h
-hello.o: hello.c hello_api.h
+         <span><font color="#009900">$(CC)</font></span> -c hello<span><font color="#990000">.</font></span>c -o hello<span><font color="#990000">.</font></span>o
-        $(CC) -c hello.c -o hello.o
+ </tt>
-</source>
 Notice that the equals character (=) has been changed into := .
-This is how simple variables are created. Whenever a simple variable is referenced, make just replaces the text that the variable contains without evaluating it. It does the evaluation only when the variable is defined. In the above example, <code>CC</code> is created with the content of <code>gcc -Wall</code> (which is evaluated, but is just plain text), and when the <code>CC</code> variable is defined next time, make evaluates <code>$(CC) -g</code> which is replaced with <code>gcc -Wall -g</code>.
+This is how simple variables are created. Whenever a simple variable is referenced, make will just replace the text that is contained in the variable without evaluating it. It will do the evaluation only when the variable is defined. In the above example, CC is created with the content of gcc -Wall (which is evaluated, but is just plain text), and when the CC variable is defined next time, make will evaluate $(CC) -g which will be replaced with gcc -Wall -g, as one might expect.
 So, the only two differences between the variable flavors are:
@@ Line 460: / Line 453: @@
 * make evaluates the contents, when the simple variable is defined, not when it is referenced later.
-Most of the time it is advisable to use the recursive variable flavor, because it does what is wanted.
+Most of the time it is advisable to use the recursive variable flavor, since it does what is wanted.
-Two ways of appending text to an existing variable were mentioned. The other mechanism is the += operation as follows: [https://vcs.maemo.org/svn/maemoexamples/tags/maemo_5.0/simple-make-files/Makefile.8 simple-make-files/Makefile.8]
+There was a mention about two ways of appending text to an existing variable. The other mechanism is the += operation as follows: simple-make-files/Makefile.8
-<source lang="make">
+ <tt>CC <span><font color="#990000"><nowiki>=</nowiki></font></span> gcc -Wall
-CC = gcc -Wall
+ <span>''<span><font color="#9A1900"><nowiki># we want to add something to the end of the variable</nowiki></font></span>''</span>
-# we want to add something to the end of the variable
+ CC <span><font color="#990000">+=</font></span> -g
-CC += -g
+ hello<span><font color="#990000">.</font></span>o<span><font color="#990000"><nowiki>:</nowiki></font></span> hello<span><font color="#990000">.</font></span>c hello_api<span><font color="#990000">.</font></span>h
-hello.o: hello.c hello_api.h
+         <span><font color="#009900">$(CC)</font></span> -c hello<span><font color="#990000">.</font></span>c -o hello<span><font color="#990000">.</font></span>o
-        $(CC) -c hello.c -o hello.o
+ </tt>
-</source>
 The prepending operation can also be used with simple variables. Make will not change the type of variable on the left side of the += operator.
-===== Automatic Variables =====
+== Automatic Variables ==
 There is a pre-defined set of variables inside make that can be used to avoid repetitive typing, when writing out the commands in a rule.
@@ Line 485: / Line 477: @@
 * <code>$?</code> : list of prerequisites that are newer than the target is (if target does not exist, they are all considered newer).
-By rewriting the makefile using automatic variables, the result is: [https://vcs.maemo.org/svn/maemoexamples/tags/maemo_5.0/simple-make-files/Makefile.9 simple-make-files/Makefile.9]
+By rewriting the makefile using automatic variables, the result is: simple-make-files/Makefile.9
-<source lang="make">
+ <tt><span>''<span><font color="#9A1900"><nowiki># add the warning flag to CFLAGS-variable</nowiki></font></span>''</span>
-# add the warning flag to CFLAGS-variable
+ CFLAGS <span><font color="#990000">+=</font></span> -Wall
-CFLAGS += -Wall
+ targets <span><font color="#990000"><nowiki>=</nowiki></font></span> hello
-targets = hello
+ <span><font color="#990000">.</font></span>PHONY<span><font color="#990000"><nowiki>:</nowiki></font></span> all
-.PHONY: all
+ all<span><font color="#990000"><nowiki>:</nowiki></font></span> <span><font color="#009900">$(targets)</font></span>
-all: $(targets)
+ hello<span><font color="#990000"><nowiki>:</nowiki></font></span> hello<span><font color="#990000">.</font></span>o hello_func<span><font color="#990000">.</font></span>o
-hello: hello.o hello_func.o
+         <span><font color="#009900">$(CC)</font></span> <span><font color="#009900">$^</font></span> -o <span><font color="#009900">$@</font></span>
-        $(CC) $^ -o $@
+ hello<span><font color="#990000">.</font></span>o<span><font color="#990000"><nowiki>:</nowiki></font></span> hello<span><font color="#990000">.</font></span>c hello_api<span><font color="#990000">.</font></span>h
-hello.o: hello.c hello_api.h
+         <span><font color="#009900">$(CC)</font></span> <span><font color="#009900">$(CFLAGS)</font></span> -c <span><font color="#009900">$&lt;</font></span> -o <span><font color="#009900">$@</font></span>
-        $(CC) $(CFLAGS) -c $< -o $@
+ hello_func<span><font color="#990000">.</font></span>o<span><font color="#990000"><nowiki>:</nowiki></font></span> hello_func<span><font color="#990000">.</font></span>c hello_api<span><font color="#990000">.</font></span>h
-hello_func.o: hello_func.c hello_api.h
+         <span><font color="#009900">$(CC)</font></span> <span><font color="#009900">$(CFLAGS)</font></span> -c <span><font color="#009900">$&lt;</font></span> -o <span><font color="#009900">$@</font></span>
-        $(CC) $(CFLAGS) -c $< -o $@
+ <span><font color="#990000">.</font></span>PHONY<span><font color="#990000"><nowiki>:</nowiki></font></span> clean
-.PHONY: clean
+ clean<span><font color="#990000"><nowiki>:</nowiki></font></span>
-clean:
+         <span><font color="#009900">$(RM)</font></span> <span><font color="#009900">$(targets)</font></span> <span><font color="#990000"><nowiki>*.</nowiki></font></span>o
-        $(RM) $(targets) *.o
+ </tt>
-</source>
-Notice the cases when <code>$^</code> is used instead of <code>$&lt;</code> in the above snippet. It is not desired to pass the header files for compilation to the compiler, because the source file already includes the header files. For this reason, <code>$&lt;</code> is used. On the other hand, when linking programs and there are multiple files to put into the executable, <code>$^</code> would normally be used.
+Notice the cases when <code>$^</code> is used instead of <code>$&lt;</code> in the above snippet. It is not desired to pass the header files for compilation to the compiler, since the source file already includes the header files. For this reason, <code>$&lt;</code> is used. On the other hand, when linking programs and there are multiple files to put into the executable, <code>$^</code> would normally be used.
 This relies on a couple of things:
-* <code>$(RM)</code> and <code>$(CC)</code> will be replaced with paths to the system compiler and removal commands.
+* $(RM) and $(CC) will be replaced with paths to the system compiler and removal commands. * $(CFLAGS) is a variable that contains a list of options to pass whenever make will invoke the C compiler.
-* <code>$(CFLAGS)</code> is a variable that contains a list of options to pass whenever make invokes the C compiler.
-It can also be noticed that all these variable names are in uppercase. This signifies that they have been communicated from the system environment to make. In fact, if creating an environment variable called <code>CFLAGS</code>, make will create it internally for any makefile that it will process. This is the mechanism to communicate variables into makefiles from outside.
+It can also be noticed that all these variable names are in uppercase. This signifies that they have been communicated from the system environment to make. In fact, if creating an environment variable called CFLAGS, make will create it internally for any makefile that it will process. This is the mechanism to communicate variables into makefiles from outside.
 Writing variables in uppercase is a convention signaling external variables, or environmental variables, so this is the reason why lowercase should be used in own private variables within a Makefile.
-=== Integrating with Pkg-Config ===
+== Integrating with Pkg-Config ==
-The above has provided the knowledge to write a simple Makefile for the Hello World example. To get the the result of [http://pkg-config.freedesktop.org/wiki/ pkg-config], the GNU make <code>$(shell command params)</code> function will be used here. Its function is similar to the backtick operation of the shell. [https://vcs.maemo.org/svn/maemoexamples/tags/maemo_5.0/simple-make-files/Makefile.10 simple-make-files/Makefile.10]
+The above has provided the knowledge to write a simple Makefile for the Hello World example. In order to get the the result of pkg-config, the GNU make $(shell command params) function will be used here. Its function is similar to the backtick operation of the shell. simple-make-files/Makefile.10
-<source lang="make">
+ <tt><span>''<span><font color="#9A1900"><nowiki># define a list of pkg-config packages we want to use</nowiki></font></span>''</span>
-# define a list of pkg-config packages we want to use
+ pkg_packages <span><font color="#990000"><nowiki>:=</nowiki></font></span> gtk<span><font color="#990000">+</font></span>-<span><font color="#993399">2.0</font></span> hildon-<span><font color="#993399">1</font></span>
-pkg_packages := gtk+-2.0 hildon-1
+ <span>''<span><font color="#9A1900"><nowiki># get the necessary flags for compiling</nowiki></font></span>''</span>
-# get the necessary flags for compiling
+ PKG_CFLAGS <span><font color="#990000"><nowiki>:=</nowiki></font></span> <span><font color="#009900">$(</font></span>shell pkg-config -cflags <span><font color="#009900">$(pkg_packages))</font></span>
-PKG_CFLAGS := $(shell pkg-config --cflags $(pkg_packages))
+ <span>''<span><font color="#9A1900"><nowiki># get the necessary flags for linking</nowiki></font></span>''</span>
-# get the necessary flags for linking
+ PKG_LDFLAGS <span><font color="#990000"><nowiki>:=</nowiki></font></span> <span><font color="#009900">$(</font></span>shell pkg-config -libs <span><font color="#009900">$(pkg_packages))</font></span>
-PKG_LDFLAGS := $(shell pkg-config --libs $(pkg_packages))
+ <span>''<span><font color="#9A1900"><nowiki># additional flags</nowiki></font></span>''</span>
-# additional flags
+ <span>''<span><font color="#9A1900"><nowiki># -Wall: warnings</nowiki></font></span>''</span>
-# -Wall: warnings
+ <span>''<span><font color="#9A1900"><nowiki># -g: debugging</nowiki></font></span>''</span>
-# -g: debugging
+ ADD_CFLAGS <span><font color="#990000"><nowiki>:=</nowiki></font></span> -Wall -g
-ADD_CFLAGS := -Wall -g
+ <span>''<span><font color="#9A1900"><nowiki># combine the flags (so that CFLAGS/LDFLAGS from the command line</nowiki></font></span>''</span>
-# combine the flags (so that CFLAGS/LDFLAGS from the command line
+ <span>''<span><font color="#9A1900"><nowiki># still work).</nowiki></font></span>''</span>
-# still work).
+ CFLAGS  <span><font color="#990000"><nowiki>:=</nowiki></font></span> <span><font color="#009900">$(PKG_CFLAGS)</font></span> <span><font color="#009900">$(ADD_CFLAGS)</font></span> <span><font color="#009900">$(CFLAGS)</font></span>
-CFLAGS  := $(PKG_CFLAGS) $(ADD_CFLAGS) $(CFLAGS)
+ LDFLAGS <span><font color="#990000"><nowiki>:=</nowiki></font></span> <span><font color="#009900">$(PKG_LDFLAGS)</font></span> <span><font color="#009900">$(LDFLAGS)</font></span>
-LDFLAGS := $(PKG_LDFLAGS) $(LDFLAGS)
+ targets <span><font color="#990000"><nowiki>=</nowiki></font></span> hildon_helloworld-<span><font color="#993399">1</font></span>
-targets = hildon_helloworld-1
+ <span><font color="#990000">.</font></span>PHONY<span><font color="#990000"><nowiki>:</nowiki></font></span> all
-.PHONY: all
+ all<span><font color="#990000"><nowiki>:</nowiki></font></span> <span><font color="#009900">$(targets)</font></span>
-all: $(targets)
+ hildon_helloworld-<span><font color="#993399">1</font></span><span><font color="#990000"><nowiki>:</nowiki></font></span> hildon_helloworld-<span><font color="#993399">1</font></span><span><font color="#990000">.</font></span>o
-hildon_helloworld-1: hildon_helloworld-1.o
+         <span><font color="#009900">$(CC)</font></span> <span><font color="#009900">$^</font></span> -o <span><font color="#009900">$@</font></span> <span><font color="#009900">$(LDFLAGS)</font></span>
-        $(CC) $^ -o $@ $(LDFLAGS)
+ hildon_helloworld-<span><font color="#993399">1</font></span><span><font color="#990000">.</font></span>o<span><font color="#990000"><nowiki>:</nowiki></font></span> hildon_helloworld-<span><font color="#993399">1</font></span><span><font color="#990000">.</font></span>c
-hildon_helloworld-1.o: hildon_helloworld-1.c
+         <span><font color="#009900">$(CC)</font></span> <span><font color="#009900">$(CFLAGS)</font></span> -c <span><font color="#009900">$&lt;</font></span> -o <span><font color="#009900">$@</font></span>
-        $(CC) $(CFLAGS) -c $< -o $@
+ <span><font color="#990000">.</font></span>PHONY<span><font color="#990000"><nowiki>:</nowiki></font></span> clean
-.PHONY: clean
+ clean<span><font color="#990000"><nowiki>:</nowiki></font></span>
-clean:
+         <span><font color="#009900">$(RM)</font></span> <span><font color="#009900">$(targets)</font></span> <span><font color="#990000"><nowiki>*.</nowiki></font></span>o
-        $(RM) $(targets) *.o
+ </tt>
-</source>
-You might wonder, where the <code>CC</code> and <code>RM</code> variables come from. They certainly were not declared anywhere in the Makefile. GNU make comes with a list of pre-defined variables for many programs and their arguments. GNU make also contains a preset list of pattern rules (which will not be dealt here), but basically these are pre-defined rules that are used when (for example) one needs an .o file from an .c file. The rules that were manually specified above are actually the same rules that GNU make already contains, so the Makefile can be made even more compact by only specifying the dependencies between files.
+One might wonder, where the CC and RM variables come from. They certainly were not declared anywhere in the Makefile. GNU make comes with a list of pre-defined variables for many programs and their arguments. GNU make also contains a preset list of pattern rules (which will not be dealt here), but basically these are pre-defined rules that are used when (for example) one needs an .o file from an .c file. The rules that were manually specified above are actually the same rules that GNU make already contains, so the Makefile can be made even more compact by only specifying the dependencies between files.
-This leads to the following, slightly simpler version: [https://vcs.maemo.org/svn/maemoexamples/tags/maemo_5.0/simple-make-files/Makefile.11 simple-make-files/Makefile.11]
+This leads to the following, slightly simpler version: simple-make-files/Makefile.11
-<source lang="make">
+ <tt><span>''<span><font color="#9A1900"><nowiki># define a list of pkg-config packages we want to use</nowiki></font></span>''</span>
-# define a list of pkg-config packages we want to use
+ pkg_packages <span><font color="#990000"><nowiki>:=</nowiki></font></span> gtk<span><font color="#990000">+</font></span>-<span><font color="#993399">2.0</font></span> hildon-<span><font color="#993399">1</font></span>
-pkg_packages := gtk+-2.0 hildon-1
+ PKG_CFLAGS <span><font color="#990000"><nowiki>:=</nowiki></font></span> <span><font color="#009900">$(</font></span>shell pkg-config -cflags <span><font color="#009900">$(pkg_packages))</font></span>
-PKG_CFLAGS := $(shell pkg-config -cflags $(pkg_packages))
+ PKG_LDFLAGS <span><font color="#990000"><nowiki>:=</nowiki></font></span> <span><font color="#009900">$(</font></span>shell pkg-config -libs <span><font color="#009900">$(pkg_packages))</font></span>
-PKG_LDFLAGS := $(shell pkg-config -libs $(pkg_packages))
+ ADD_CFLAGS <span><font color="#990000"><nowiki>:=</nowiki></font></span> -Wall -g
-ADD_CFLAGS := -Wall -g
+ <span>''<span><font color="#9A1900"><nowiki># combine the flags</nowiki></font></span>''</span>
-# combine the flags
+ CFLAGS  <span><font color="#990000"><nowiki>:=</nowiki></font></span> <span><font color="#009900">$(PKG_CFLAGS)</font></span> <span><font color="#009900">$(ADD_CFLAGS)</font></span> <span><font color="#009900">$(CFLAGS)</font></span>
-CFLAGS  := $(PKG_CFLAGS) $(ADD_CFLAGS) $(CFLAGS)
+ LDFLAGS <span><font color="#990000"><nowiki>:=</nowiki></font></span> <span><font color="#009900">$(PKG_LDFLAGS)</font></span> <span><font color="#009900">$(LDFLAGS)</font></span>
-LDFLAGS := $(PKG_LDFLAGS) $(LDFLAGS)
+ targets <span><font color="#990000"><nowiki>=</nowiki></font></span> hildon_helloworld-<span><font color="#993399">1</font></span>
-targets = hildon_helloworld-1
+ <span><font color="#990000">.</font></span>PHONY<span><font color="#990000"><nowiki>:</nowiki></font></span> all
-.PHONY: all
+ all<span><font color="#990000"><nowiki>:</nowiki></font></span> <span><font color="#009900">$(targets)</font></span>
-all: $(targets)
+ <span>''<span><font color="#9A1900"><nowiki># we can omit the rules and just specify the dependencies</nowiki></font></span>''</span>
-# we can omit the rules and just specify the dependencies
+ <span>''<span><font color="#9A1900"><nowiki># for our simple project this doesn't seem like a big win</nowiki></font></span>''</span>
-# for our simple project this doesn't seem like a big win
+ <span>''<span><font color="#9A1900"><nowiki># but for larger projects where you have multiple object</nowiki></font></span>''</span>
-# but for larger projects where you have multiple object
+ <span>''<span><font color="#9A1900"><nowiki># files, this will save considerable time.</nowiki></font></span>''</span>
-# files, this will save considerable time.
+ hildon_helloworld-<span><font color="#993399">1</font></span><span><font color="#990000"><nowiki>:</nowiki></font></span> hildon_helloworld-<span><font color="#993399">1</font></span><span><font color="#990000">.</font></span>o
-hildon_helloworld-1: hildon_helloworld-1.o
+ hildon_helloworld-<span><font color="#993399">1</font></span><span><font color="#990000">.</font></span>o<span><font color="#990000"><nowiki>:</nowiki></font></span> hildon_helloworld-<span><font color="#993399">1</font></span><span><font color="#990000">.</font></span>c
-hildon_helloworld-1.o: hildon_helloworld-1.c
+ <span><font color="#990000">.</font></span>PHONY<span><font color="#990000"><nowiki>:</nowiki></font></span> clean
-.PHONY: clean
+ clean<span><font color="#990000"><nowiki>:</nowiki></font></span>
-clean:
+         <span><font color="#009900">$(RM)</font></span> <span><font color="#009900">$(targets)</font></span> <span><font color="#990000"><nowiki>*.</nowiki></font></span>o
-        $(RM) $(targets) *.o
+ </tt>
-</source>
-== GNU Autotools ==
+= GNU Autotools =
 Creating portable software written in the C language has historically been challenging. The portability issues are not restricted just to the differences between binary architectures, but also encompass differences in system libraries and different implementations of UNIX APIs in different systems. This section introduces GNU autotools as one solution for managing this complexity. There are also other tools available, but the most likely to be encountered are autotoolized projects and also Debian packaging supports autotools.
-=== Brief History of Managing Portability ===
+== Brief History of Managing Portability ==
 When discussing portability challenges with C code, various issues crop up:
@@ Line 598: / Line 587: @@
 Besides autoconf, it became evident that a more general Makefile generation tool can be useful as part of the whole process. This is how GNU automake was born. GNU automake can also be used outside autoconf. A simple autoconf configuration file is presented next.
-=== GNU Autoconf ===
+== GNU Autoconf ==
-Autoconf is a tool that uses the GNU m4 macro preprocessor to process the configuration file and output a shell script based on the macros used in the file. Anything that m4 does not recognize as a macro is passed verbatim to the output script. This means that almost any wanted shell script fragments can be included into the <code>configure.ac</code> file (the modern name for the default configuration file for autoconf).
+Autoconf is a tool that uses the GNU m4 macro preprocessor to process the configuration file and output a shell script based on the macros used in the file. Anything that m4 does not recognize as a macro is passed verbatim to the output script. This means that almost any wanted shell script fragments can be included into the '''configure.ac''' (the modern name for the default configuration file for autoconf).
-The first subject here is a simple example to see how the basic configuration file works. Then some limitations of m4 syntax are covered, and hints on how to avoid problems with the syntax are given. [https://vcs.maemo.org/svn/maemoexamples/tags/maemo_5.0/autoconf-automake/example1/configure.ac autoconf-automake/example1/configure.ac]
+The first subject here is a simple example to see how the basic configuration file works. Then some limitations of m4 syntax are covered, and hints on how to avoid problems with the syntax are given. autoconf-automake/example1/configure.ac
-<source lang="autoconf">
+ <tt><span>''<span><font color="#9A1900"><nowiki># Specify the "application name" and application version</nowiki></font></span>''</span>
-# Specify the "application name" and application version
+ AC_INIT<span><font color="#990000">(</font></span>hello<span><font color="#990000">,</font></span> version-<span><font color="#993399">0.1</font></span><span><font color="#990000">)</font></span>
-AC_INIT(hello, version-0.1)
+ <span>''<span><font color="#9A1900"><nowiki># Because autoconf passes trough anything that it does not recognize</nowiki></font></span>''</span>
-# Because autoconf passes trough anything that it does not recognize
+ <span>''<span><font color="#9A1900"><nowiki># into the final script ('configure'), we can use any valid shell</nowiki></font></span>''</span>
-# into the final script ('configure'), we can use any valid shell
+ <span>''<span><font color="#9A1900"><nowiki># statements here. Note that you should restrict your shell to</nowiki></font></span>''</span>
-# statements here. Note that you should restrict your shell to
+ <span>''<span><font color="#9A1900"><nowiki># standard features that are available in all UNIX shells, but in our</nowiki></font></span>''</span>
-# standard features that are available in all UNIX shells, but in our
+ <span>''<span><font color="#9A1900"><nowiki># case, we are content with the most used shell on Linux systems</nowiki></font></span>''</span>
-# case, we are content with the most used shell on Linux systems
+ <span>''<span><font color="#9A1900"><nowiki># (bash).</nowiki></font></span>''</span>
-# (bash).
+ echo -e <span><font color="#FF0000">"</font></span><span><font color="#CC33CC">\n\n</font></span><span><font color="#FF0000">Hello from configure (using echo)!</font></span><span><font color="#CC33CC">\n\n</font></span><span><font color="#FF0000">"</font></span>
-echo -e "\n\nHello from configure (using echo)!\n\n"
+ <span>''<span><font color="#9A1900"><nowiki># We can use a macro for this messages. This is much preferred as it</nowiki></font></span>''</span>
-# We can use a macro for this messages. This is much preferred as it
+ <span>''<span><font color="#9A1900"><nowiki># is more portable.</nowiki></font></span>''</span>
-# is more portable.
+ AC_MSG_NOTICE<span><font color="#990000">([</font></span>Hello from configure using msg-notice<span><font color="#990000"><nowiki>!])</nowiki></font></span>
-AC_MSG_NOTICE([Hello from configure using msg-notice!])
+ <span>''<span><font color="#9A1900"><nowiki># Check that the C Compiler works.</nowiki></font></span>''</span>
-# Check that the C Compiler works.
+ AC_PROG_CC
-AC_PROG_CC
+ <span>''<span><font color="#9A1900"><nowiki># Check what is the AWK-program on our system (and that one exists).</nowiki></font></span>''</span>
-# Check what is the AWK-program on our system (and that one exists).
+ AC_PROG_AWK
-AC_PROG_AWK
+ <span>''<span><font color="#9A1900"><nowiki># Check whether the 'cos' function can be found in library 'm'</nowiki></font></span>''</span>
-# Check whether the 'cos' function can be found in library 'm'
+ <span>''<span><font color="#9A1900"><nowiki># (standard C math library).</nowiki></font></span>''</span>
-# (standard C math library).
+ AC_CHECK_LIB<span><font color="#990000">(</font></span>m<span><font color="#990000">,</font></span> cos<span><font color="#990000">)</font></span>
-AC_CHECK_LIB(m, cos)
+ <span>''<span><font color="#9A1900"><nowiki># Check for presence of system header 'unistd.h'.</nowiki></font></span>''</span>
-# Check for presence of system header 'unistd.h'.
+ <span>''<span><font color="#9A1900"><nowiki># This also tests a lot of other system include files (it is</nowiki></font></span>''</span>
-# This also tests a lot of other system include files (it is
+ <span>''<span><font color="#9A1900"><nowiki># semi-intelligent in determining which ones are required).</nowiki></font></span>''</span>
-# semi-intelligent in determining which ones are required).
+ AC_CHECK_HEADER<span><font color="#990000">(</font></span>unistd<span><font color="#990000">.</font></span>h<span><font color="#990000">)</font></span>
-AC_CHECK_HEADER(unistd.h)
+ <span>''<span><font color="#9A1900"><nowiki># You can also check for multiple system headers at the same time,</nowiki></font></span>''</span>
-# You can also check for multiple system headers at the same time,
+ <span>''<span><font color="#9A1900"><nowiki># but notice the different name of the test macro for this (plural).</nowiki></font></span>''</span>
-# but notice the different name of the test macro for this (plural).
+ AC_CHECK_HEADERS<span><font color="#990000">([</font></span>math<span><font color="#990000">.</font></span>h stdio<span><font color="#990000">.</font></span>h<span><font color="#990000">])</font></span>
-AC_CHECK_HEADERS([math.h stdio.h])
+ <span>''<span><font color="#9A1900"><nowiki># A way to implement conditional logic based on header file presence</nowiki></font></span>''</span>
-# A way to implement conditional logic based on header file presence
+ <span>''<span><font color="#9A1900"><nowiki># (we do not have a b0rk.h in our system).</nowiki></font></span>''</span>
-# (we do not have a b0rk.h in our system).
+ AC_CHECK_HEADER<span><font color="#990000">(</font></span>b0rk<span><font color="#990000">.</font></span>h<span><font color="#990000">,</font></span> <span><font color="#990000">[</font></span>echo <span><font color="#FF0000">"b0rk.h present in system"</font></span><span><font color="#990000">],</font></span> <span><font color="#990000">\</font></span>
-AC_CHECK_HEADER(b0rk.h, [echo "b0rk.h present in system"], \
+                         <span><font color="#990000">[</font></span>echo <span><font color="#FF0000">"b0rk.h not present in system"</font></span><span><font color="#990000">])</font></span>
-                        [echo "b0rk.h not present in system"])
+ echo <span><font color="#FF0000">"But that does not stop us from continuing!"</font></span>
-echo "But that does not stop us from continuing!"
+ echo <span><font color="#FF0000">"Directory to install binaries in is '$bindir'"</font></span>
-echo "Directory to install binaries in is '$bindir'"
+ echo <span><font color="#FF0000">"Directory under which data files go is '$datadir'"</font></span>
-echo "Directory under which data files go is '$datadir'"
+ echo <span><font color="#FF0000">"For more variables, check 'config.log' after running configure"</font></span>
-echo "For more variables, check 'config.log' after running configure"
+ echo <span><font color="#FF0000">"CFLAGS is '$CFLAGS'"</font></span>
-echo "CFLAGS is '$CFLAGS'"
+ echo <span><font color="#FF0000">"LDFLAGS is '$LDFLAGS'"</font></span>
-echo "LDFLAGS is '$LDFLAGS'"
+ echo <span><font color="#FF0000">"LIBS is '$LIBS'"</font></span>
-echo "LIBS is '$LIBS'"
+ echo <span><font color="#FF0000">"CC is '$CC'"</font></span>
-echo "CC is '$CC'"
+ echo <span><font color="#FF0000">"AWK is '$AWK'"</font></span>
-echo "AWK is '$AWK'"
+ </tt>
-</source>
 The listing is verbosely commented, so it should be pretty self-evident what the different macros do. The macros that test for a feature or an include file normally causes the generated configure script to generate small C code test programs that are run as part of the configuration process. If these programs run successfully, the relevant test succeeds and the configuration process continues to the next test.
@@ Line 655: / Line 643: @@
 The following convention holds true in respect to the names of macros that are commonly used and available:
-* <code>AC_*</code>: A macro that is included in autoconf or is meant for it.
+* '''AC_*'''<nowiki>: A macro that is included in autoconf or is meant for it. </nowiki>
-* <code>AM_*</code>: A macro that is meant for automake.
+* '''AM_*'''<nowiki>: A macro that is meant for automake. </nowiki>
 * Others: The autoconf system can be expanded by writing custom macros which can be stored in a custom directory. Some development packages also install new macros to be used.
-The next step is to run <code>autoconf</code>. Without any parameters, it reads <code>configure.ac</code> by default. If <code>configure.ac</code> does not exist, it tries to read <code>configure.in</code> instead.
+The next step is to run ''autoconf''. Without any parameters, it reads '''configure.ac''' by default. If configure.ac does not exist, it tries to read '''configure.in''' instead.
-Note that using the name <code>configure.in</code> is considered obsolete.
+Note that using the name configure.in is considered obsolete.
   <nowiki>
@@ Line 719: / Line 707: @@
   </nowiki>
-Autoconf does not output information about its progress. Normally, only errors are output on stdout. Instead, it creates a new script called <code>configure</code> in the same directory, and sets it as executable.
+Autoconf does not output information about its progress. Normally, only errors are output on stdout. Instead, it creates a new script called '''configure''' in the same directory, and sets it as executable.
 The configure script is the result of all of the macro processing. If taking a look at the generated file with an editor or by using less, it can be seen that it contains a lot of shell code.
@@ Line 745: / Line 733: @@
 If bad shell syntax is introduced into the configuration file, the bad syntax causes errors only when the generated script file is run (not when autoconf generates the script). In general, autoconf almost always succeeds but the generated script does not necessarily succeed. Knowing which error in the shell script corresponds to which line in the original configure.ac is not always easy but can be learned through experience.
-There is a line that reports the result of testing for <code>unistd.h</code>. It appears twice: the first time because it is the default test to run whenever testing for headers, and the second time because it was explicitly tested for. The second test output contains text (cached), which means that the test has been already run, and the result has been saved into a cache (the mysterious <code>autom4te.cache</code> directory). This means that for large projects, which cannot necessarily perform the same tests over and over, the tests are only run once, which makes running the script faster.
+There is a line that reports the result of testing for '''unistd.h'''. It appears twice: the first time because it is the default test to run whenever testing for headers, and the second time because it was explicitly tested for. The second test output contains text (cached), which means that the test has been already run, and the result has been saved into a cache (the mysterious '''autom4te.cache''' directory). This means that for large projects, which cannot necessarily perform the same tests over and over, the tests are only run once, which makes running the script faster.
 The last line's output above contains the values of variables. When the configure script runs, it automatically creates shell variables that can be used in shell code fragments. The macros for checking what programs are available for compiling must illustrate that point. Here awk was used as an example.
@@ Line 763: / Line 751: @@
   AWK is 'gawk'
   </nowiki>
 It can seem that giving the prefix does not change anything, but this is because the shell does not expand the value in this particular case. However, if the variable was used in the script for doing something, the shell would expand later on. In order to see some effect, try passing the datadir-option (because that is printed out explicitly).
-If you need to see which variables are available for configuration, read the generated <code>config.log</code> file. The variables are listed at the end of that file.
+If you need to see which variables are available for configuration, read the generated '''config.log''' file. The variables are listed at the end of that file.
-=== Substitutions ===
+== Substitutions ==
 Besides creating the configure script, autoconf can do other useful things as well. Some people say that autoconf is at least as powerful as emacs, if not more so. Unfortunately, with all this power comes also lot of complexity. Sometimes finding out why things do not quite work can be rather difficult.
-It can be useful to use the variables inside text files that are not directly related to the <code>configure.ac</code>'''. These might be configuration files or files that are used in some part of the building process later on. For this, autoconf provides a mechanism called ''substitution''. A special macro reads in an external file, replaces all instances of variable names in it, and then stores the resulting file as a new file. The convention in naming the input files is to add a suffix .in to the names. The name of generated output file are the same but without the suffix.
+It can be useful to use the variables inside text files that are not directly related to the '''configure.ac'''. These might be configuration files or files that are used in some part of the building process later on. For this, autoconf provides a mechanism called ''substitution''. A special macro reads in an external file, replaces all instances of variable names in it, and then stores the resulting file as a new file. The convention in naming the input files is to add a suffix .in to the names. The name of generated output file are the same but without the suffix.
 Note that the substitution is done when the generated configure script is run, not when autoconf is run.
@@ Line 778: / Line 767: @@
 The generated configure script replaces all occurrences of the variable name surrounded with 'at' (@) characters with the variable value when it reads through each of the input files.
-This is best illustrated with a small example. The input file contents are listed after the autoconf configuration file. In this example, the substitution is only made for one file, but it is also possible to process multiple files using the substitution mechanism. [https://vcs.maemo.org/svn/maemoexamples/tags/maemo_5.0/autoconf-automake/example2/configure.ac autoconf-automake/example2/configure.ac]
+This is best illustrated with a small example. The input file contents are listed after the autoconf configuration file. In this example, the substitution is only made for one file, but it is also possible to process multiple files using the substitution mechanism. autoconf-automake/example2/configure.ac
-<source lang="autoconf">
+ <tt><span>''<span><font color="#9A1900"><nowiki># An example showing how to use a variable-based substitution.</nowiki></font></span>''</span>
-# An example showing how to use a variable-based substitution.
+ AC_INIT<span><font color="#990000">(</font></span>hello<span><font color="#990000">,</font></span> version-<span><font color="#993399">0.1</font></span><span><font color="#990000">)</font></span>
-AC_INIT(hello, version-0.1)
+ AC_PROG_CC
-AC_PROG_CC
+ AC_PROG_AWK
-AC_PROG_AWK
+ AC_CHECK_HEADER<span><font color="#990000">(</font></span>unistd<span><font color="#990000">.</font></span>h<span><font color="#990000">)</font></span>
-AC_CHECK_HEADER(unistd.h)
+ AC_CHECK_HEADERS<span><font color="#990000">([</font></span>math<span><font color="#990000">.</font></span>h stdio<span><font color="#990000">.</font></span>h<span><font color="#990000">])</font></span>
-AC_CHECK_HEADERS([math.h stdio.h])
+ AC_CHECK_HEADER<span><font color="#990000">(</font></span>b0rk<span><font color="#990000">.</font></span>h<span><font color="#990000">,</font></span> <span><font color="#990000">[</font></span>echo <span><font color="#FF0000">"b0rk.h present in system"</font></span><span><font color="#990000">],</font></span> <span><font color="#990000">\</font></span>
-AC_CHECK_HEADER(b0rk.h, [echo "b0rk.h present in system"], \
+                         <span><font color="#990000">[</font></span>echo <span><font color="#FF0000">"b0rk.h not present in system"</font></span><span><font color="#990000">])</font></span>
-                        [echo "b0rk.h not present in system"])
+ echo <span><font color="#FF0000">"But that doesn't stop us from continuing!"</font></span>
-echo "But that doesn't stop us from continuing!"
+ <span>''<span><font color="#9A1900"><nowiki># Run the test-output.txt(.in) through autoconf substitution logic.</nowiki></font></span>''</span>
+ AC_OUTPUT<span><font color="#990000">(</font></span>test-output<span><font color="#990000">.</font></span>txt<span><font color="#990000">)</font></span>
+ </tt>
-# Run the test-output.txt(.in) through autoconf substitution logic.
+autoconf-automake/example2/test-output.txt.in
-AC_OUTPUT(test-output.txt)
-</source>
-[https://vcs.maemo.org/svn/maemoexamples/tags/maemo_5.0/autoconf-automake/example2/test-output.txt.in autoconf-automake/example2/test-output.txt.in]
+ <code>This file will go through autoconf variable substitution.
+ The output file will be named as 'test-output.txt' (the '.in'-suffix
-<pre>
+ is stripped).
-This file will go through autoconf variable substitution.
+ All the names surrounded by '@'-characters will be replaced by the values
-The output file will be named as 'test-output.txt' (the '.in'-suffix
+ of the variables (if present) by the configure script, when it is run
-is stripped).
+ by the end user.
-All the names surrounded by '@'-characters will be replaced by the values
+ Prefix: @prefix@
-of the variables (if present) by the configure script, when it is run
+ C compiler: @CC@
-by the end user.
+ This is a name for which there is no variable.
-Prefix: @prefix@
+ Stuff: @stuff@</code>
-C compiler: @CC@
-This is a name for which there is no variable.
-Stuff: @stuff@
-</pre>
 We then run autoconf and configure:
-<pre>
+ [sbox-FREMANTLE_X86: ~/example2] &gt; autoconf
-[sbox-FREMANTLE_X86: ~/example2] > autoconf
+ [sbox-FREMANTLE_X86: ~/example2] &gt; ./configure
-[sbox-FREMANTLE_X86: ~/example2] > ./configure
+ checking for gcc... gcc
-checking for gcc... gcc
+ checking for C compiler default output file name... a.out
-checking for C compiler default output file name... a.out
+ checking whether the C compiler works... yes
-checking whether the C compiler works... yes
+ checking whether we are cross compiling... no
-checking whether we are cross compiling... no
+ checking for suffix of executables...
-checking for suffix of executables...
+ checking for suffix of object files... o
-checking for suffix of object files... o
+ checking whether we are using the GNU C compiler... yes
-checking whether we are using the GNU C compiler... yes
+ checking whether gcc accepts -g... yes
-checking whether gcc accepts -g... yes
+ checking for gcc option to accept ANSI C... none needed
-checking for gcc option to accept ANSI C... none needed
+ checking for gawk... gawk
-checking for gawk... gawk
+ checking how to run the C preprocessor... gcc -E
-checking how to run the C preprocessor... gcc -E
+ checking for egrep... grep -E
-checking for egrep... grep -E
+ checking for ANSI C header files... yes
-checking for ANSI C header files... yes
+ checking for sys/types.h... yes
-checking for sys/types.h... yes
+ checking for sys/stat.h... yes
-checking for sys/stat.h... yes
+ checking for stdlib.h... yes
-checking for stdlib.h... yes
+ checking for string.h... yes
-checking for string.h... yes
+ checking for memory.h... yes
-checking for memory.h... yes
+ checking for strings.h... yes
-checking for strings.h... yes
+ checking for inttypes.h... yes
-checking for inttypes.h... yes
+ checking for stdint.h... yes
-checking for stdint.h... yes
+ checking for unistd.h... yes
-checking for unistd.h... yes
+ checking for unistd.h... (cached) yes
-checking for unistd.h... (cached) yes
+ checking math.h usability... yes
-checking math.h usability... yes
+ checking math.h presence... yes
-checking math.h presence... yes
+ checking for math.h... yes
-checking for math.h... yes
+ checking stdio.h usability... yes
-checking stdio.h usability... yes
+ checking stdio.h presence... yes
-checking stdio.h presence... yes
+ checking for stdio.h... yes
-checking for stdio.h... yes
+ checking b0rk.h usability... no
-checking b0rk.h usability... no
+ checking b0rk.h presence... no
-checking b0rk.h presence... no
+ checking for b0rk.h... no
-checking for b0rk.h... no
+ b0rk.h not present in system
-b0rk.h not present in system
+ But that doesn't stop us from continuing!
-But that doesn't stop us from continuing!
+ configure: creating ./config.status
-configure: creating ./config.status
+ config.status: creating test-output.txt
-config.status: creating test-output.txt
+ [sbox-FREMANTLE_X86: ~/example2] &gt; cat test-output.txt
-[sbox-FREMANTLE_X86: ~/example2] > cat test-output.txt
+ This file will go through autoconf variable substitution.
-This file will go through autoconf variable substitution.
+ The output file will be named as 'test-output.txt' (the '.in'-suffix
+ is stripped).
+ All names surrounded by '@'-characters will be replaced by the values
+ of the variables (if present) by the configure script when it is run
+ by end user.
+ Prefix: /usr/local
+ C compiler: gcc
+ This is a name for which there is no variable.
+ Stuff: @stuff@
-The output file will be named as 'test-output.txt' (the '.in'-suffix
-is stripped).
-All names surrounded by '@'-characters will be replaced by the values
+This feature is used later on. When you run your own version of the file, notice the creation of file called '''config.status'''. It is the file that actually does the substitution for external files, so if the configuration is otherwise complex, and you only want to re-run the substitution of the output files, you can run the config.status script.
-of the variables (if present) by the configure script when it is run
-by end user.
-Prefix: /usr/local
+== Introducing Automake ==
-C compiler: gcc
-This is a name for which there is no variable.
-Stuff: @stuff@
-</pre>
-This feature is used later on. When you run your own version of the file, notice the creation of file called <code>config.status</code>. It is the file that actually does the substitution for external files, so if the configuration is otherwise complex, and you only want to re-run the substitution of the output files, you can run the config.status script.
-=== Introducing Automake ===
 The next step is to create a small project that consists of yet another hello world. This time, there is a file implementing the application (main), a header file describing the API (printHello()) and the implementation of the function.
-As it happens, GNU automake is designed so that it can be easily integrated with autoconf. Makefiles are generated by a configure script, and it contains the necessary settings for the system on which configure is run.
+As it happens, GNU automake is designed so that it can be easily integrated into autoconf. This is utilized in the next example, so that the Makefile does not have to be written by hand anymore. Instead, the Makefile is generated by the configure script, and it contains the necessary settings for the system on which configure is run.
 In order for this to work, two things are necessary:
-* A configuration file for automake (conventionally <code>Makefile.am</code>) which contains the files to be generated using make
+* A configuration file for automake (conventionally Makefile.am).
-* A configuration file for autoconf (conventionally <code>configure.ac</code>) which lists the tests which are required to ensure that the system has all the required dependencies
+* Telling the autoconf that it should create Makefile.in based on Makefile.am by using automake.
-Running automake will generate a file <code>Makefile.in</code> containing a number of standard targets for make, and running autoconf will generate a configure script which will test your system, and generate final Makefiles and other files based on the software it finds present on the system.
+The example starts with the autoconf configuration file: autoconf-automake/example3/configure.ac
-The example starts with the autoconf configuration file: autoconf-[https://vcs.maemo.org/svn/maemoexamples/tags/maemo_5.0/autoconf-automake/example3/configure.ac automake/example3/configure.ac]
+ <tt><span>''<span><font color="#9A1900"><nowiki># Any source file name related to our project is ok here.</nowiki></font></span>''</span>
+ AC_INIT<span><font color="#990000">(</font></span>helloapp<span><font color="#990000">,</font></span> <span><font color="#993399">0.1</font></span><span><font color="#990000">)</font></span>
+ <span>''<span><font color="#9A1900"><nowiki># We are using automake, so we init it next. The name of the macro</nowiki></font></span>''</span>
+ <span>''<span><font color="#9A1900"><nowiki># starts with 'AM' which means that it is related to automake ('AC'</nowiki></font></span>''</span>
+ <span>''<span><font color="#9A1900"><nowiki># is related to autoconf).</nowiki></font></span>''</span>
+ <span>''<span><font color="#9A1900"><nowiki># Initing automake means more or less generating the .in file from</nowiki></font></span>''</span>
+ <span>''<span><font color="#9A1900"><nowiki># the .am file although it can also be generated at other steps.</nowiki></font></span>''</span>
+ AM_INIT_AUTOMAKE
+ <span>''<span><font color="#9A1900"><nowiki># Compiler check.</nowiki></font></span>''</span>
+ AC_PROG_CC
+ <span>''<span><font color="#9A1900"><nowiki># Check for 'install' program.</nowiki></font></span>''</span>
+ AC_PROG_INSTALL
+ <span>''<span><font color="#9A1900"><nowiki># Generate the Makefile from Makefile.in (using substitution logic).</nowiki></font></span>''</span>
+ AC_OUTPUT<span><font color="#990000">(</font></span>Makefile<span><font color="#990000">)</font></span>
+ </tt>
-<source lang="autoconf">
+Then the configuration file is presented for automake: autoconf-automake/example3/Makefile.am
-# Any source file name related to our project is ok here.
-AC_INIT(helloapp, 0.1)
-# We are using automake, so we init it next. The name of the macro
-# starts with 'AM' which means that it is related to automake ('AC'
-# is related to autoconf).
-# Initing automake means more or less generating the .in file from
-# the .am file although it can also be generated at other steps.
-AM_INIT_AUTOMAKE
-# Compiler check.
-AC_PROG_CC
-# Check for 'install' program.
-AC_PROG_INSTALL
-# Generate the Makefile from Makefile.in (using substitution logic).
-AC_OUTPUT(Makefile)
-</source>
-Then the configuration file is presented for automake: [https://vcs.maemo.org/svn/maemoexamples/tags/maemo_5.0/autoconf-automake/example3/Makefile.am autoconf-automake/example3/Makefile.am]
+ <tt><span>''<span><font color="#9A1900"><nowiki># Automake rule primer:</nowiki></font></span>''</span>
+ <span>''<span><font color="#9A1900"><nowiki># 1) Left side_ tells what kind of target this is.</nowiki></font></span>''</span>
+ <span>''<span><font color="#9A1900"><nowiki># 2) _right side tells what kind of dependencies are listed.</nowiki></font></span>''</span>
+ <span>''<span><font color="#9A1900"><nowiki>#</nowiki></font></span>''</span>
+ <span>''<span><font color="#9A1900"><nowiki># As an example, below:</nowiki></font></span>''</span>
+ <span>''<span><font color="#9A1900"><nowiki># 1) bin = binaries</nowiki></font></span>''</span>
+ <span>''<span><font color="#9A1900"><nowiki># 2) PROGRAMS lists the programs to generate Makefile.ins for.</nowiki></font></span>''</span>
+ bin_PROGRAMS <span><font color="#990000"><nowiki>=</nowiki></font></span> helloapp
+ <span>''<span><font color="#9A1900"><nowiki># Listing source dependencies:</nowiki></font></span>''</span>
+ <span>''<span><font color="#9A1900"><nowiki>#</nowiki></font></span>''</span>
+ <span>''<span><font color="#9A1900"><nowiki># The left side_ gives the name of the application to which the</nowiki></font></span>''</span>
+ <span>''<span><font color="#9A1900"><nowiki># dependencies are related to.</nowiki></font></span>''</span>
+ <span>''<span><font color="#9A1900"><nowiki># _right side gives again the type of dependencies.</nowiki></font></span>''</span>
+ <span>''<span><font color="#9A1900"><nowiki>#</nowiki></font></span>''</span>
+ <span>''<span><font color="#9A1900"><nowiki># Here we then list the source files that are necessary to build the</nowiki></font></span>''</span>
+ <span>''<span><font color="#9A1900"><nowiki># helloapp -binary.</nowiki></font></span>''</span>
+ helloapp_SOURCES <span><font color="#990000"><nowiki>=</nowiki></font></span> helloapp<span><font color="#990000">.</font></span>c hello<span><font color="#990000">.</font></span>c hello<span><font color="#990000">.</font></span>h
+ <span>''<span><font color="#9A1900"><nowiki># For other files that cannot be automatically deduced by automake,</nowiki></font></span>''</span>
+ <span>''<span><font color="#9A1900"><nowiki># you need to use the EXTRA_DIST rule which should list the files</nowiki></font></span>''</span>
+ <span>''<span><font color="#9A1900"><nowiki># that should be included. Files can also be in other directories or</nowiki></font></span>''</span>
+ <span>''<span><font color="#9A1900"><nowiki># even whole directories can be included this way (not recommended).</nowiki></font></span>''</span>
+ <span>''<span><font color="#9A1900"><nowiki>#</nowiki></font></span>''</span>
+ <span>''<span><font color="#9A1900"><nowiki># EXTRA_DIST = some.service.file.service some.desktop.file.desktop</nowiki></font></span>''</span>
+ </tt>
-<source lang="make">
+This material tries to introduce just enough of automake for it to be useful for small projects. Because of this, the detailed syntax of Makefile.am is not explained. Based on the above description, automake knows what kind of Makefile.in to create, and autoconf takes it over from there and fills in the missing pieces.
-# Automake rule primer:
-# 1) Left side_ tells what kind of target this is.
-# 2) _right side tells what kind of dependencies are listed.
-#
-# As an example, below:
-# 1) bin = binaries
-# 2) PROGRAMS lists the programs to generate Makefile.ins for.
-bin_PROGRAMS = helloapp
-# Listing source dependencies:
-#
-# The left side_ gives the name of the application to which the
-# dependencies are related to.
-# _right side gives again the type of dependencies.
-#
-# Here we then list the source files that are necessary to build the
-# helloapp -binary.
-helloapp_SOURCES = helloapp.c hello.c hello.h
-# For other files that cannot be automatically deduced by automake,
-# you need to use the EXTRA_DIST rule which should list the files
-# that should be included. Files can also be in other directories or
-# even whole directories can be included this way (not recommended).
-EXTRA_DIST = some.service.file.service some.desktop.file.desktop
-</source>
-This material tries to introduce just enough of automake for it to be useful for small projects. Because of this, the detailed syntax of <code>Makefile.am</code> is not explained. Based on the above description, automake knows what kind of <code>Makefile.in</code> to create, and autoconf takes it over from there and fills in the missing pieces.
+The source files for the project are as simple as possible, but notice the implementation of printHello. autoconf-automake/example3/helloapp.c
-The source files for the project are as simple as possible, but notice the implementation of printHello. [https://vcs.maemo.org/svn/maemoexamples/tags/maemo_5.0/autoconf-automake/example3/helloapp.c autoconf-automake/example3/helloapp.c]
+ <tt><span>''<span><font color="#9A1900">/**</font></span>''</span>
+ <span>''<span><font color="#9A1900"> * This maemo code example is licensed under a MIT-style license,</font></span>''</span>
+ <span>''<span><font color="#9A1900"> * that can be found in the file called "License" in the same</font></span>''</span>
+ <span>''<span><font color="#9A1900"> * directory as this file.</font></span>''</span>
+ <span>''<span><font color="#9A1900"> * Copyright (c) 2007-2008 Nokia Corporation. All rights reserved.</font></span>''</span>
+ <span>''<span><font color="#9A1900"> */</font></span>''</span>
+ <span>'''<span><font color="#000080"><nowiki>#include</nowiki></font></span>'''</span> <span><font color="#FF0000">&lt;stdlib.h&gt;</font></span>
+ <span>'''<span><font color="#000080"><nowiki>#include</nowiki></font></span>'''</span> <span><font color="#FF0000">"hello.h"</font></span>
+ <span><font color="#009900">int</font></span> <span>'''<span><font color="#000000">main</font></span>'''</span><span><font color="#990000">(</font></span><span><font color="#009900">int</font></span> argc<span><font color="#990000">,</font></span> <span><font color="#009900">char</font></span><span><font color="#990000"><nowiki>**</nowiki></font></span> argv<span><font color="#990000">)</font></span> <span><font color="#FF0000">{</font></span>
+   <span>'''<span><font color="#000000">printHello</font></span>'''</span><span><font color="#990000">();</font></span>
+   <span>'''<span><font color="#0000FF">return</font></span>'''</span> EXIT_SUCCESS<span><font color="#990000"><nowiki>;</nowiki></font></span>
+ <span><font color="#FF0000">}</font></span>
+ </tt>
-<source lang="c">
+autoconf-automake/example3/hello.h
-/**
- * This maemo code example is licensed under a MIT-style license,
- * that can be found in the file called "License" in the same
- * directory as this file.
- * Copyright (c) 2007-2008 Nokia Corporation. All rights reserved.
- */
-#include <stdlib.h>
-#include "hello.h"
-int main(int argc, char** argv) {
-  printHello();
-  return EXIT_SUCCESS;
-}
-</source>
-[https://vcs.maemo.org/svn/maemoexamples/tags/maemo_5.0/autoconf-automake/example3/hello.h autoconf-automake/example3/hello.h]
+ <tt><span>''<span><font color="#9A1900">/**</font></span>''</span>
+ <span>''<span><font color="#9A1900"> * This maemo code example is licensed under a MIT-style license,</font></span>''</span>
+ <span>''<span><font color="#9A1900"> * that can be found in the file called "License" in the same</font></span>''</span>
+ <span>''<span><font color="#9A1900"> * directory as this file.</font></span>''</span>
+ <span>''<span><font color="#9A1900"> * Copyright (c) 2007-2008 Nokia Corporation. All rights reserved.</font></span>''</span>
+ <span>''<span><font color="#9A1900"> */</font></span>''</span>
+ <span>'''<span><font color="#000080"><nowiki>#ifndef</nowiki></font></span>'''</span> INCLUDE_HELLO_H
+ <span>'''<span><font color="#000080"><nowiki>#define</nowiki></font></span>'''</span> INCLUDE_HELLO_H
+ <span>'''<span><font color="#0000FF">extern</font></span>'''</span> <span><font color="#009900">void</font></span> <span>'''<span><font color="#000000">printHello</font></span>'''</span><span><font color="#990000">(</font></span><span><font color="#009900">void</font></span><span><font color="#990000">);</font></span>
+ <span>'''<span><font color="#000080"><nowiki>#endif</nowiki></font></span>'''</span>
+ </tt>
-<source lang="c">
+autoconf-automake/example3/hello.c
-/**
- * This maemo code example is licensed under a MIT-style license,
- * that can be found in the file called "License" in the same
- * directory as this file.
- * Copyright (c) 2007-2008 Nokia Corporation. All rights reserved.
- */
-#ifndef INCLUDE_HELLO_H
-#define INCLUDE_HELLO_H
-extern void printHello(void);
-#endif
-</source>
-[https://vcs.maemo.org/svn/maemoexamples/tags/maemo_5.0/autoconf-automake/example3/hello.c autoconf-automake/example3/hello.c]
+ <tt><span>''<span><font color="#9A1900">/**</font></span>''</span>
+ <span>''<span><font color="#9A1900"> * This maemo code example is licensed under a MIT-style license,</font></span>''</span>
-<source lang="c">
+  <span>''<span><font color="#9A1900"> * that can be found in the file called "License" in the same</font></span>''</span>
-/**
+  <span>''<span><font color="#9A1900"> * directory as this file.</font></span>''</span>
- * This maemo code example is licensed under a MIT-style license,
+  <span>''<span><font color="#9A1900"> * Copyright (c) 2007-2008 Nokia Corporation. All rights reserved.</font></span>''</span>
-  * that can be found in the file called "License" in the same
+  <span>''<span><font color="#9A1900"> */</font></span>''</span>
-  * directory as this file.
-  * Copyright (c) 2007-2008 Nokia Corporation. All rights reserved.
+ <span>'''<span><font color="#000080"><nowiki>#include</nowiki></font></span>'''</span> <span><font color="#FF0000">&lt;stdio.h&gt;</font></span>
-  */
+ <span>'''<span><font color="#000080"><nowiki>#include</nowiki></font></span>'''</span> <span><font color="#FF0000">"hello.h"</font></span>
-#include <stdio.h>
+ <span><font color="#009900">void</font></span> <span>'''<span><font color="#000000">printHello</font></span>'''</span><span><font color="#990000">(</font></span><span><font color="#009900">void</font></span><span><font color="#990000">)</font></span> <span><font color="#FF0000">{</font></span>
-#include "hello.h"
+   <span>''<span><font color="#9A1900">/* Note that these are available as defines now. */</font></span>''</span>
+   <span>'''<span><font color="#000000">printf</font></span>'''</span><span><font color="#990000">(</font></span><span><font color="#FF0000">"("</font></span> PACKAGE <span><font color="#FF0000">" "</font></span> VERSION <span><font color="#FF0000">")</font></span><span><font color="#CC33CC">\n</font></span><span><font color="#FF0000">"</font></span><span><font color="#990000">);</font></span>
-void printHello(void) {
+   <span>'''<span><font color="#000000">printf</font></span>'''</span><span><font color="#990000">(</font></span><span><font color="#FF0000">"Hello world!</font></span><span><font color="#CC33CC">\n</font></span><span><font color="#FF0000">"</font></span><span><font color="#990000">);</font></span>
-  /* Note that these are available as defines now. */
+ <span><font color="#FF0000">}</font></span>
-  printf("(" PACKAGE " " VERSION ")\n");
+ </tt>
-  printf("Hello world!\n");
-}
-</source>
-The <code>PACKAGE</code> and <code>VERSION</code> defines are passed to the build process automatically.
+The PACKAGE and VERSION defines is passed to the build process automatically.
   [sbox-FREMANTLE_X86: ~/example3] &gt; autoconf
@@ Line 995: / Line 974: @@
 Autoconf is complaining about a macro, for which it cannot find a definition (actually m4 is the program that does the complaining). The problem is that by default, autoconf only knows about built-in macros. When using a macro for integration or a macro that comes with another package, autoconf needs to be told about it. Luckily, this process is quite painless.
-A local <code>aclocal.m4</code> file needs to be created into the same directory with the <code>configure.ac</code>. When starting, autoconf reads this file, and it is enough to put the necessary macros there.
+A local '''aclocal.m4''' file needs to be created into the same directory with the '''configure.ac'''. When starting, autoconf reads this file, and it is enough to put the necessary macros there.
-For this, a utility program called aclocal is used, which scans the configure.ac and copy the relevant macros into the local <code>aclocal.m4</code>. The directory for all the extension macros is usually <code>/usr/share/aclocal/</code>, which should be checked out at some point.
+For this, a utility program called aclocal is used, which scans the configure.ac and copy the relevant macros into the local aclocal.m4. The directory for all the extension macros is usually '''/usr/share/aclocal/''', which should be checked out at some point.
 Now it is time to run aclocal, and then try and run autoconf again.
@@ Line 1,003: / Line 982: @@
 Note that the messages that are introduced into the process from now on are inevitable, because some macros use obsolete features or have incomplete syntax, and thus trigger warnings. There is no easy solution to this, other than to fix the macros themselves.
-<pre>
+ [sbox-FREMANTLE_X86: ~/example3] &gt; aclocal
-[sbox-FREMANTLE_X86: ~/example3] > aclocal
+ /scratchbox/tools/share/aclocal/pkg.m4:5: warning:
-/scratchbox/tools/share/aclocal/pkg.m4:5: warning:
+  underquoted definition of PKG_CHECK_MODULES
- underquoted definition of PKG_CHECK_MODULES
+   run info '(automake)Extending aclocal' or see
-  run info '(automake)Extending aclocal' or see
+   http://sources.redhat.com/automake/automake.html#Extending%20aclocal
-  http://sources.redhat.com/automake/automake.html#Extending%20aclocal
+ /usr/share/aclocal/pkg.m4:5: warning:
-/usr/share/aclocal/pkg.m4:5: warning:
+  underquoted definition of PKG_CHECK_MODULES
- underquoted definition of PKG_CHECK_MODULES
+ /usr/share/aclocal/gconf-2.m4:8: warning:
-/usr/share/aclocal/gconf-2.m4:8: warning:
+  underquoted definition of AM_GCONF_SOURCE_2
- underquoted definition of AM_GCONF_SOURCE_2
+ /usr/share/aclocal/audiofile.m4:12: warning:
-/usr/share/aclocal/audiofile.m4:12: warning:
+  underquoted definition of AM_PATH_AUDIOFILE
- underquoted definition of AM_PATH_AUDIOFILE
+ [sbox-FREMANTLE_X86: ~/example3] &gt; autoconf
-[sbox-FREMANTLE_X86: ~/example3] > autoconf
+ [sbox-FREMANTLE_X86: ~/example3] &gt; ./configure
-[sbox-FREMANTLE_X86: ~/example3] > ./configure
+ configure: error: cannot find install-sh or install.sh in
-configure: error: cannot find install-sh or install.sh in
+  ~/example3 ~/ ~/..
- ~/example3 ~/ ~/..
-</pre>
-Listing the contents of the directory reveals that the <code>Makefile.in</code> is not among the contents. Automake needs to be run manually, so that the file is created. At the same time, the missing files need to be introduced to the directory (such as the install.sh that configure seems to complain about).
+Listing the contents of the directory reveals that the '''Makefile.in''' is not among the contents. Automake needs to be run manually, so that the file is created. At the same time, the missing files need to be introduced to the directory (such as the install.sh that configure seems to complain about).
-This is done by executing automake -ac, which creates the Makefile.in and also copy the missing files into their proper places. ''This step also copies a file called <code>COPYING</code> into the directory, which by default contains the GPL.'' So, if the software is going to be distributed under some other license, this is the correct moment to replace the license file with the appropriate one.
+This is done by executing automake -ac, which creates the Makefile.in and also copy the missing files into their proper places. ''This step also copies a file called COPYING into the directory, which by default contains the GPL.'' So, if the software is going to be distributed under some other license, this is the correct moment to replace the license file with the appropriate one.
-<pre>
+ [sbox-FREMANTLE_X86: ~/example3] &gt; automake -ac
-[sbox-FREMANTLE_X86: ~/example3] > automake -ac
+ configure.ac: installing `./install-sh'
-configure.ac: installing `./install-sh'
+ configure.ac: installing `./missing'
-configure.ac: installing `./missing'
+ Makefile.am: installing `./depcomp'
-Makefile.am: installing `./depcomp'
+ [sbox-FREMANTLE_X86: ~/example3] &gt; ./configure
-[sbox-FREMANTLE_X86: ~/example3] > ./configure
+ checking for a BSD-compatible install... /scratchbox/tools/bin/install -c
-checking for a BSD-compatible install... /scratchbox/tools/bin/install -c
+ checking whether build environment is sane... yes
-checking whether build environment is sane... yes
+ checking for gawk... gawk
-checking for gawk... gawk
+ checking whether make sets $(MAKE)... yes
-checking whether make sets $(MAKE)... yes
+ checking for gcc... gcc
-checking for gcc... gcc
+ checking for C compiler default output file name... a.out
-checking for C compiler default output file name... a.out
+ checking whether the C compiler works... yes
-checking whether the C compiler works... yes
+ checking whether we are cross compiling... no
-checking whether we are cross compiling... no
+ checking for suffix of executables...
-checking for suffix of executables...
+ checking for suffix of object files... o
-checking for suffix of object files... o
+ checking whether we are using the GNU C compiler... yes
-checking whether we are using the GNU C compiler... yes
+ checking whether gcc accepts -g... yes
-checking whether gcc accepts -g... yes
+ checking for gcc option to accept ANSI C... none needed
-checking for gcc option to accept ANSI C... none needed
+ checking for style of include used by make... GNU
-checking for style of include used by make... GNU
+ checking dependency style of gcc... gcc3
-checking dependency style of gcc... gcc3
+ checking for a BSD-compatible install... /scratchbox/tools/bin/install -c
-checking for a BSD-compatible install... /scratchbox/tools/bin/install -c
+ configure: creating ./config.status
-configure: creating ./config.status
+ config.status: creating Makefile
-config.status: creating Makefile
+ config.status: executing depfiles commands
-config.status: executing depfiles commands
-</pre>
-Notice the second to last line of the output, which shows that configure just created a Makefile (based on the <code>Makefile.in</code> that ''automake'' created).
+Notice the second to last line of the output, telling that autoconf just created a Makefile (based on the Makefile.in that ''automake'' created).
-Performing all these steps manually each time to make sure that all the generated files are really generated can be rather tedious. Most developers create a script called '''autogen.sh''', which implements the necessary bootstrap procedures for them. Below is a file that is suitable for this example. Real-life projects can have more steps because of localization and other requirements. [https://vcs.maemo.org/svn/maemoexamples/tags/maemo_5.0/autoconf-automake/example3/autogen.sh autoconf-automake/example3/autogen.sh]
+Performing all these steps manually each time to make sure that all the generated files are really generated can be rather tedious. Most developers create a script called '''autogen.sh''', which implements the necessary bootstrap procedures for them. Below is a file that is suitable for this example. Real-life projects can have more steps because of localization and other requirements. autoconf-automake/example3/autogen.sh
-<source lang="bash">
+ <tt><span>''<span><font color="#9A1900"><nowiki>#!/bin/sh</nowiki></font></span>''</span>
-#!/bin/sh
+ <span>''<span><font color="#9A1900"><nowiki>#</nowiki></font></span>''</span>
-#
+ <span>''<span><font color="#9A1900"><nowiki># A utility script to setup the autoconf environment for the first</nowiki></font></span>''</span>
-# A utility script to setup the autoconf environment for the first
+ <span>''<span><font color="#9A1900"><nowiki># time. Normally this script is run when checking out a</nowiki></font></span>''</span>
-# time. Normally this script is run when checking out a
+ <span>''<span><font color="#9A1900"><nowiki># development version of the software from SVN/version control.</nowiki></font></span>''</span>
-# development version of the software from SVN/version control.
+ <span>''<span><font color="#9A1900"><nowiki># Regular users expect to download .tar.gz/tar.bz2 source code</nowiki></font></span>''</span>
-# Regular users expect to download .tar.gz/tar.bz2 source code
+ <span>''<span><font color="#9A1900"><nowiki># instead, and those should come with with 'configure' script so that</nowiki></font></span>''</span>
-# instead, and those should come with with 'configure' script so that
+ <span>''<span><font color="#9A1900"><nowiki># users do not require the autoconf/automake tools.</nowiki></font></span>''</span>
-# users do not require the autoconf/automake tools.
+ <span>''<span><font color="#9A1900"><nowiki>#</nowiki></font></span>''</span>
-#
+ <span>''<span><font color="#9A1900"><nowiki># Scan configure.ac and copy the necessary macros into aclocal.m4.</nowiki></font></span>''</span>
-# Scan configure.ac and copy the necessary macros into aclocal.m4.
+ aclocal
-aclocal
+ <span>''<span><font color="#9A1900"><nowiki># Generate Makefile.in from Makefile.am (and copy necessary support</nowiki></font></span>''</span>
-# Generate Makefile.in from Makefile.am (and copy necessary support
+ <span>''<span><font color="#9A1900"><nowiki># files, because of -ac).</nowiki></font></span>''</span>
-# files, because of -ac).
+ automake -ac
-automake -ac
+ <span>''<span><font color="#9A1900"><nowiki># This step is not normally necessary, but documented here for your</nowiki></font></span>''</span>
-# This step is not normally necessary, but documented here for your
+ <span>''<span><font color="#9A1900"><nowiki># convenience. The files listed below need to be present to stop</nowiki></font></span>''</span>
-# convenience. The files listed below need to be present to stop
+ <span>''<span><font color="#9A1900"><nowiki># automake from complaining during various phases of operation.</nowiki></font></span>''</span>
-# automake from complaining during various phases of operation.
+ <span>''<span><font color="#9A1900"><nowiki>#</nowiki></font></span>''</span>
-#
+ <span>''<span><font color="#9A1900"><nowiki># You also should consider maintaining these files separately once</nowiki></font></span>''</span>
-# You also should consider maintaining these files separately once
+ <span>''<span><font color="#9A1900"><nowiki># you release your project into the wild.</nowiki></font></span>''</span>
-# you release your project into the wild.
+ <span>''<span><font color="#9A1900"><nowiki>#</nowiki></font></span>''</span>
-#
+ <span>''<span><font color="#9A1900"><nowiki># touch NEWS README AUTHORS ChangeLog</nowiki></font></span>''</span>
-# touch NEWS README AUTHORS ChangeLog
+ <span>''<span><font color="#9A1900"><nowiki># Run autoconf (creates the 'configure'-script).</nowiki></font></span>''</span>
-# Run autoconf (creates the 'configure'-script).
+ autoconf
-autoconf
+ echo <span><font color="#FF0000">'Ready to go (run configure)'</font></span>
-echo 'Ready to go (run configure)'
+ </tt>
-</source>
 In the above code, the line with touch is commented. This can raise a question. There is a target called distcheck that automake creates in the Makefile, and this target checks whether the distribution tarball contains all the necessary files. The files listed on the touch line are necessary (even if empty), so they need to be created at some point. Without these files, the penultimate Makefile complains when running the distcheck-target.
@@ Line 1,113: / Line 1,087: @@
   rm -f *.o
-=== Checking for Distribution Sanity ===
+== Checking for Distribution Sanity ==
-The generated Makefile contains various targets that can be used when creating distribution tarballs (tar files containing the source code and the necessary files to build the software). The most important of these is the dist-target, which by default creates a .tar.gz-file out of the source, including the configure script and other necessary files (which are specified in <code>Makefile.am</code>).
+The generated Makefile contains various targets that can be used when creating distribution tarballs (tar files containing the source code and the necessary files to build the software). The most important of these is the dist-target, which by default creates a .tar.gz-file out of the source, including the configure script and other necessary files (which are specified in Makefile.am).
 To test whether building the software from the distribution tarball is possible, execute the distcheck-target. It first creates a distribution tarball, then extracts it in a new subdirectory, runs configure there and tries and builds the software with the default make target. If it fails, the relevant error is given.
-Making the distcheck target each time before making a dist target is recommended, so that you can be sure that the distribution tarball can be used outside the source tree. This step is especially critical later when [[packaging|making Debian packages]].
+Making the distcheck target each time before making a dist target is recommended, so that you can be sure that the distribution tarball can be used outside the source tree. This step is especially critical later when making Debian packages.
-=== Cleaning up ===
+== Cleaning up ==
-For the sake of convenience, the example3 directory also includes a script called <code>antigen.sh</code>, which tries its best to get rid of all generated files (it is necessary to <code>autogen.sh</code> the project afterwards).
+For the sake of convenience, the example3 directory also includes a script called antigen.sh, which will try its best to get rid of all generated files (it will be necessary to autogen.sh the project afterwards).
-Having a clean-up script is not very common in open source projects, but it is especially useful when starting autotools development because it allows testing the toolchain easily from scratch.
+Having a clean-up script is not very common in open source projects, but it is especially useful when starting autotools development, as it allows testing the toolchain easily from scratch.
-The contents of antigen.sh that is suitable for simple projects: [https://vcs.maemo.org/svn/maemoexamples/tags/maemo_5.0/autoconf-automake/example3/antigen.sh autoconf-automake/example3/antigen.sh]
+The contents of antigen.sh that is suitable for simple projects: autoconf-automake/example3/antigen.sh
-<source lang="bash">
+ <tt><span>''<span><font color="#9A1900"><nowiki>#!/bin/sh</nowiki></font></span>''</span>
-#!/bin/sh
+ <span>''<span><font color="#9A1900"><nowiki>#</nowiki></font></span>''</span>
-#
+ <span>''<span><font color="#9A1900"><nowiki># A utility script to remove all generated files.</nowiki></font></span>''</span>
-# A utility script to remove all generated files.
+ <span>''<span><font color="#9A1900"><nowiki>#</nowiki></font></span>''</span>
-#
+ <span>''<span><font color="#9A1900"><nowiki># Running autogen.sh will be required after running this script since</nowiki></font></span>''</span>
-# Running autogen.sh will be required after running this script since
+ <span>''<span><font color="#9A1900"><nowiki># the 'configure' script will also be removed.</nowiki></font></span>''</span>
-# the 'configure' script will also be removed.
+ <span>''<span><font color="#9A1900"><nowiki>#</nowiki></font></span>''</span>
-#
+ <span>''<span><font color="#9A1900"><nowiki># This script is mainly useful when testing autoconf/automake changes</nowiki></font></span>''</span>
-# This script is mainly useful when testing autoconf/automake changes
+ <span>''<span><font color="#9A1900"><nowiki># and as a part of their development process.</nowiki></font></span>''</span>
-# and as a part of their development process.
+ <span>''<span><font color="#9A1900"><nowiki># If there's a Makefile, then run the 'distclean' target first (which</nowiki></font></span>''</span>
-# If there's a Makefile, then run the 'distclean' target first (which
+ <span>''<span><font color="#9A1900"><nowiki># will also remove the Makefile).</nowiki></font></span>''</span>
-# will also remove the Makefile).
+ <span>'''<span><font color="#0000FF">if</font></span>'''</span> <span>'''<span><font color="#0000FF">test</font></span>'''</span> -f Makefile<span><font color="#990000"><nowiki>;</nowiki></font></span> <span>'''<span><font color="#0000FF">then</font></span>'''</span>
-if test -f Makefile; then
+   make distclean
-  make distclean
+ <span>'''<span><font color="#0000FF">fi</font></span>'''</span>
-fi
+ <span>''<span><font color="#9A1900"><nowiki># Remove all tar-files (assuming there are some packages).</nowiki></font></span>''</span>
-# Remove all tar-files (assuming there are some packages).
+ rm -f <span><font color="#990000"><nowiki>*.</nowiki></font></span>tar<span><font color="#990000">.*</font></span> <span><font color="#990000"><nowiki>*.</nowiki></font></span>tgz
-rm -f *.tar.* *.tgz
+ <span>''<span><font color="#9A1900"><nowiki># Also remove the autotools cache directory.</nowiki></font></span>''</span>
-# Also remove the autotools cache directory.
+ rm -Rf autom4te<span><font color="#990000">.</font></span>cache
-rm -Rf autom4te.cache
+ <span>''<span><font color="#9A1900"><nowiki># Remove rest of the generated files.</nowiki></font></span>''</span>
-# Remove rest of the generated files.
+ rm -f Makefile<span><font color="#990000">.</font></span><span>'''<span><font color="#0000FF">in</font></span>'''</span> aclocal<span><font color="#990000">.</font></span>m4 configure depcomp install-sh missing
-rm -f Makefile.in aclocal.m4 configure depcomp install-sh missing
+ </tt>
-</source>
-=== Integration with Pkg-Config ===
+== Integration with Pkg-Config ==
-The last part that is covered for autoconf is how to integrate pkg-config support into the projects when using <code>configure.ac</code>.
+The last part that is covered for autoconf is how to integrate pkg-config support into the projects when using configure.ac.
 Pkg-config comes with a macro package ('''pkg.m4'''), which contains some useful macros for integration. The best documentation for these can be found in the pkg-config manual pages.
-For the purpose of this example, only one macro is used, <code>PKG_CHECK_MODULES</code>, which is used as part of <code>configure.ac</code> for pkg-config integration
+Here only one will be used, PKG_CHECK_MODULES, which should be used like this: Part of configure.ac for pkg-config integration
-<source lang="text">
+ <tt><span>''<span><font color="#9A1900"><nowiki># Check whether the necessary pkg-config packages are present. The</nowiki></font></span>''</span>
-# Check whether the necessary pkg-config packages are present. The
+ <span>''<span><font color="#9A1900"><nowiki># PKG_CHECK_MODULES macro is supplied by pkg-config</nowiki></font></span>''</span>
-# PKG_CHECK_MODULES macro is supplied by pkg-config
+ <span>''<span><font color="#9A1900"><nowiki># (/usr/share/aclocal/).</nowiki></font></span>''</span>
-# (/usr/share/aclocal/).
+ <span>''<span><font color="#9A1900"><nowiki>#</nowiki></font></span>''</span>
-#
+ <span>''<span><font color="#9A1900"><nowiki># The first parameter will be the variable name prefix that will be</nowiki></font></span>''</span>
-# The first parameter is the variable name prefix that is
+ <span>''<span><font color="#9A1900"><nowiki># used to create two variables: one to hold the CFLAGS required by</nowiki></font></span>''</span>
-# used to create two variables: one to hold the CFLAGS required by
+ <span>''<span><font color="#9A1900"><nowiki># the packages, and one to hold the LDFLAGS (LIBS) required by the</nowiki></font></span>''</span>
-# the packages, and one to hold the LDFLAGS (LIBS) required by the
+ <span>''<span><font color="#9A1900"><nowiki># packages. The variable name prefix (HHW) can be chosen freely.</nowiki></font></span>''</span>
-# packages. The variable name prefix (HHW) can be chosen freely.
+ PKG_CHECK_MODULES<span><font color="#990000">(</font></span>HHW<span><font color="#990000">,</font></span> gtk<span><font color="#990000">+</font></span>-<span><font color="#993399">2.0</font></span> hildon-<span><font color="#993399">1</font></span> hildon-fm-<span><font color="#993399">2</font></span> gnome-vfs-<span><font color="#993399">2.0</font></span> <span><font color="#990000">\</font></span>
-PKG_CHECK_MODULES(HHW, gtk+-2.0 hildon-1 hildon-fm-2 gnome-vfs-2.0 \
+                        gconf-<span><font color="#993399">2.0</font></span> libosso<span><font color="#990000">)</font></span>
-                       gconf-2.0 libosso)
+ <span>''<span><font color="#9A1900"><nowiki># At this point HHW_CFLAGS will contain the necessary compiler flags</nowiki></font></span>''</span>
-# At this point HHW_CFLAGS contains the necessary compiler flags
+ <span>''<span><font color="#9A1900"><nowiki># and HHW_LIBS will contain the linker options necessary for all the</nowiki></font></span>''</span>
-# and HHW_LIBS contains the linker options necessary for all the
+ <span>''<span><font color="#9A1900"><nowiki># packages listed above.</nowiki></font></span>''</span>
-# packages listed above.
+ <span>''<span><font color="#9A1900"><nowiki>#</nowiki></font></span>''</span>
-#
+ <span>''<span><font color="#9A1900"><nowiki># Add the pkg-config supplied values to the ones that are used by</nowiki></font></span>''</span>
-# Add the pkg-config supplied values to the ones that are used by
+ <span>''<span><font color="#9A1900"><nowiki># Makefile or supplied by the user running ./configure.</nowiki></font></span>''</span>
-# Makefile or supplied by the user running ./configure.
+ <span><font color="#009900">CFLAGS</font></span><span><font color="#990000"><nowiki>=</nowiki></font></span><span><font color="#FF0000">"$HHW_CFLAGS $CFLAGS"</font></span>
-CFLAGS="$HHW_CFLAGS $CFLAGS"
+ <span><font color="#009900">LIBS</font></span><span><font color="#990000"><nowiki>=</nowiki></font></span><span><font color="#FF0000">"$HHW_LIBS $LIBS"</font></span></tt>
-LIBS="$HHW_LIBS $LIBS"
-</source>
-The proper placing for this code is after all the <code>AC_PROG_*</code> checks and before the <code>AC_OUTPUT</code> macros (so that the build flags may affect the substituted files).
+The proper placing for this code is after all the AC_PROG_* checks and before the AC_OUTPUT macros (so that the build flags may affect the substituted files).
-Check also the validity of the package names by using:
+One should also check the validity of the package names by using:
   pkg-config --list-all
-to make sure you do not try to get the wrong library information.
+to make sure one does not try to get the wrong library information.
-[[Category:Development]]
-[[Category:Documentation]]
-[[Category:Fremantle]]