# Building

Anjuta handles autotools projects. It is able to cope with other kinds of projects, such as projects using a user-written Makefile, but the current build interface is targeted at autotools projects. Some knowledge of them is useful to better understand the way a project is built.

An autotools project is built in three steps:

1. Generate

2. Configure

3. Build

Build is the main step in which all target files are generated from the source files. It can be divided into two subphases: Compile and Link. In the Compile phase each object file is generated from its corresponding source file. For instance, a source file `hello.c` will generate `hello.o` after compilation. Usually you do not need to worry about these object files — just think of them as intermediate files. In the Link phase, all object files and libraries are linked together to create the final executable. Some programming languages do not need a Compile and a Link phase. Moreover the Build step may be used to generate other files, like documentation which doesn't need such phases.

Configure is the step in which the source tree is adjusted to your system. autotools projects can be built on a wide range of systems using different compilers and having different library functions. This step runs a script named `configure` that will check for various characteristics of your system and create some of the files required to perform a build (such as `Makefile` and `config.h`). This step is used to select build options, too; for instance, a build option may disable optimization to make debugging easier or disable some experimental part of a program.

Generate is the step in which the `configure` script and other related files are created. The `configure` script used above needs to run on various systems and checks a lot of things. It would be quite difficult to write it by hand. Moreover autotools enforces some project organization rules such as the presence of some mandatory files: `NEWS` and `COPYING`, for example. It includes several tools to create necessary files from simpler files written by the developer such as `configure.in` (or `configure.ac`) and `Makefile.am`. All these tools are commonly run from a script named `autogen.sh` in the project directory. This step is useful only for a developer (someone modifying the source files), as the `configure` script depends only on the source files, and is distributed within the project package. Note that the makefiles created by configure include some rules to automatically regenerate the project when needed, so it often not needed to rerun it directly.

Read the info pages of automake and autoconf for more details on how these tools work.

## Generate and Configure

### Configure a project

You need to run this step before being able to build your project. This is usually run only once at the beginning of the first build process — for example, just after you have extracted a source tarball of a project distribution. After that, configuration is automatically handled by the subsequent build processes. If you have used the Application Wizard to create the application, then you will not need to run this separately: the wizard will run it as a part of the project generation process.

There is no requirement to run this only once. It can be run at any time, usually when the configuration options need to be changed. One thing to note is that if the `config.h` file in the top level directory is changed, running `configure` again will not overwrite it.

Both generate and configure steps are launched with a single menu item: Build Configure Project…. This menu item brings a dialog where you can choose:

- Whether you want to run the generate step or not

  The generate step needs to be run once at the beginning of the project; then it is automatically handled by the build process. You can force it to run by checking the checkbox Regenerate project; you might do this if you encounter difficulties while building a project (e.g. if you receive build errors after you've modified lots of build files).

- The configuration name

  This name is used to refer to each configuration. Some configurations (Default, Debug, Optimized) are already defined by default. One configuration includes a build directory and some configuration options.

- The build directory

  This is the build directory name. In the Default configuration, it is the same directory as the source directory but autotools supports building in a different directory.

  Each configuration must have a different build directory and if one configuration uses the source directory, you cannot have other configurations at the same time. You need to run Build Remove Configuration on the configuration using the source directory before adding a new configuration.

- Configure options

  These options are passed to the `configure` script. Some are standard, such as --prefix and CFLAGS; others depend on the project. You can get a list of allowed configuration options by running the `configure` script with the `--help` argument.

### Select a configuration

If you have created different configurations, you can select which one is active by selecting it in Build Select Configuration.

### Clean a configuration

To clean the project and leave it in a state that requires rerunning the configure step, choose Build Remove Configuration. It run `make distclean` and deletes more files than Clean Project. In other words, it leaves the project as though it has just been extracted from a distribution tarball. Note that it does not remove the configuration directory itself; you can do that yourself if you like.

## Compile and Build

### Compiling a file

In a project, individual source files can be compiled separately into objects (`*.o` files). Although you do not have to worry about these object files, sometimes it is handy to compile a file first (for example, to make sure there are no syntax errors). Building a whole project can take a lot of time, especially in the case of larger and more complex applications. Therefore, you will probably go through a series of edit-compile iterations while developing a project.

To compile a file, choose the menu item Build Compile or press F11. This will compile the active file.

### Building an executable

Anjuta has no separate link command, simply because it is not necessary. The build process will compile all source files and link them together along with the necessary libraries. The build command will not recompile those files which are already up-to-date (this is called the dependency check). If you have already compiled all files individually, then the only thing the build step performs is the link. If you have already built the project and no dependent file has been modified, even the link stage will be skipped.

So how exactly does the dependency check influence project development? If you have modified a file, then all of the source files that depend on the modified file are recompiled. All files (not just the object files and executable) in the project are checked for these dependencies during the build process. If it is found that a particular file is dependent on some other file which has been modified, then that file will be regenerated.

Can you imagine how your life (as a programmer) would be if the dependency check were not there? If you cannot answer just yet, then you will find out when you start developing big projects!

Build Build will build all files in the directory of the currently active file.

Build Build Project will build the whole project — all subdirectories are built recursively.

## Other operations

### Creating a distribution package

To build a tarball distribution of the project choose Build Build Tarball. This will create a tarball (`*.tar.gz`) and put it in the top-level project directory. Copy the file to a safe place for distribution.

### Installing a project

Choosing the menu item Build Install will install the generated application on your system.

#### System-wide installation

You must be logged in as root to perform a system-wide install. Also note that for a GNOME application to use the pixmaps in the project, it must be installed as a system-wide application. Otherwise, when the application is executed in your project, there will be lots of "pixmap not found" errors. You can configure Anjuta to use `sudo` or `su` before installing the project in the build preferences.

### Cleaning

This deletes all of the files generated by the build process, including all object files (`*.o` files) and the executable(s). It can be applied on one directory or the whole project.

Choose the menu item Build Clean Project to clean all project files.

Choose the menu item Build Clean to clean only the directory of the current active file.