# Project Management

Anjuta has a powerful Project Manager plugin which can open most automake/autoconf based projects. It might fail on some oddly configured projects, but as long as the project is done by using automake/autoconf in a typical way, it should work.

The neat thing is that it does not store any project information beyond what is already available in project structure. That is, there is no separate project data maintained by Anjuta and all project processing are done directly within the project structure. This allows the project to be maintained or developed outside Anjuta without having to so-called 'porting' or 'switching' to a new platform. Since technically Anjuta projects are just automake projects, mixed development of it (Anjuta and non-Anjuta users) or switching back and forth between Anjuta and other tools is quite possible without any hindrance.

## Creating a New Project

### New project from template

The project wizard plugin uses a powerful template processing engine called autogen. All new projects are created from templates that are written in autogen syntax. Project wizard lets you create new projects from a selection of project templates. The selection includes simple generic, flat (no subdirectory), gtk+, gnome, java, python projects and more. New templates can be easily downloaded and installed since they are just a collection of text files.

Choose the menu item FileNew Project … to start the application wizard. Read the first page carefully. Click on Next to proceed.

Select the type of application you want to create in the second page. Click on Next to proceed.

On the next pages, enter all necessary details for your project. You can change these settings later also, but it is advisable to put them right in first run to maintain the project's integrity. White spaces or any non-alphanumeric characters, except underscore (_) and dash (-), are not allowed in many of the entry boxes that would follow (except perhaps the Author text box).

You can also specify whether your project will have internationalization support using gettext (read the gettext info page for more details). This gives your project multilingual support for different regional languages such as English, French, Dutch etc.. The rest of the options are for setting whether the GNU copyright statement should appear in the comments at the top of each file, and enabling GNOME desktop menu information if necessary. Shared library support allows adding shared library modules later in the project. If you plan to have libraries in your project, it would be good to enable. Depending on the project type that is being created, there would be other information requested.

The final step is to verify the information you have just supplied. Click on Finish to start generating the project.

Once project generation is over, you can try it out by building the project and executing it.

### Importing Projects

The import project feature is used to import an already existing project and convert it into anjuta project. Activate the import project wizard from FileNew Project from existing sources and follow instructions dictated by the wizard. Once the project is imported, it could be opened in anjuta subsequently just like any other anjuta project.

The import project features only works if your existing project is using autoconf/automake and, to a very limited extend, plain makefiles.

## Loading and Saving Projects

### Loading Projects

To open a project, choose the menu item File Open …. Select the project file (`*.anjuta`) in the dialog and click OK.

If the project has recently been opened, then you will find it listed in the menu FileRecent. Choose the project file from the list, and the project will be opened.

As soon as a project is opened, Anjuta will enter Project mode. There are three panes in the project window. The first is the project pane and lists the project files organized in file types. The second is the symbol browser, which has already been discussed in section Symbol Browser and tags Browser. The third pane is the file view of the project and is more or less similar to a mini file-manager. In file view, all the files present in the project tree is visible. Right clicking on these files will pop up the file Operation menu.

If the project is also a CVS tree, then corresponding file revision numbers are also listing on the right of file names in the file view pane.

### Saving Projects

The project is automatically saved when you close because all changes are made directly in the project structure.

## Project structure

Here is the Project window with the the Operation menu (accessible by clicking on the right mouse button).

### Project window

The Project window

Project window lists the project in standard automake hierarchy organized into groups of targets. Groups correspond to directories in your project and targets correspond to normal automake targets (not to be confused with make targets). Project window actually has two parts; one part (lower one) shows complete project hierarchy and the other part (upper one) lists important targets directly. Important targets constitute executable and library targets -- making them very accessible in from the view. This is particularly useful in big projects where the hierarchy could be deep and hard to navigate from the tree alone. Targets are, in turn, composed of source files.

- Groups are used to logically organize targets. A project can contain any number of groups. Each group can have sub-groups as well as targets. In automake projects, groups are just sub-directories in the project. The top level group is called root and is always "/".

- Targets are the build targets in project, such as programs (executable binaries), scripts, libraries, miscellaneous data etc. Not all target types are built from sources, but exist just to organize the sources and therefore may not exist physically (e.g. Miscellaneous data target). Targets exist under groups. See "Adding targets" for full list of available target types.

- Source files are the files used to build the targets or just to be part of it. They exist only under targets. Many target types expect certain type of source files (e.g. programs and libraries target types), but some can accept any file (e.g. Miscellaneous data target).

Each of the project groups and targets is configurable in standard automake way. You can set complier and linker flags directly for each target, or set configure variables. Groups allow setting installation destinations for its targets.

Just like file manager, project manager view also has convenience actions (accessible from the Operation menu) for the source files and targets.

Many command-line tools are available to maintain and manage a project, and each tool has its own specific rules and capabilities. Anjuta tries to automate most of the common operations using plugins. However, you might occasionally still need to do them manually.

It is possible to make use of other tools or hand edit the project files simultaneously. It doesn't matter if the project is loaded in Anjuta or not. Anjuta would update itself with any external changes made to project.

## Groups and targets

### Adding Groups

To add a new group (a directory in automake based projects):

- Select Project Add Group and a dialog to add a new group would popup.

- Select the group under which to add new group.

- Give a name of the new group and click Ok.

With automake projects, a new directory with the given name would be created under the parent group's directory.

New group can also be added from the Operation menu in Project window by selecting Add Group. First select the group under which to add the group in Project window.

### Removing Groups

To remove a group:

- Select the target in Project Manager view.

- Select Remove from the Operation menu.

The target and sources associated with the group will also be removed from the project (they are not deleted from the file system, though. You can still add them later).

### Adding Targets

To add a new target:

- Select Project Add Target and a dialog to add a new target would popup.

- Select the group under which to add the target.

- Select the target type.

- Give a name of the new target and click Ok.

New target can also be added from the Operation menu in Project window by selecting Add target. First select the group under which to add the target in Project window.

Target names usually require some standard prefix and suffix, depending on the type of target. Anjuta would warn if the name is not valid and may give an example of a name.

There are several target types for automake project. They are:

- Program target type is for executable binaries. Select this if you want to add an executable to the project. By default, all program targets would be installed in standard executable directory, e.g. /usr/bin or /usr/local/bin. You can override it by specifying a different installation directory in its group properties.

- Shared Library target type is for shared or dynamic libraries. Select this if you are adding a shared library to the project. By default, all shared libraries are installed in standard libraries directory, e.g. /usr/lib or /usr/local/lib. You can override it by specifying a different installation directory in its group properties.

- Static Library target type is for static library. Select this if you are adding a static library to the project. By default, all static libraries are installed in standard libraries directory, e.g. /usr/lib or /usr/local/lib. You can override it by specifying a different installation directory in its group properties.

- Java module target type is for java module. Select this if you are grouping java sources into a module. You need to provide an installation directory for this target where the .class files will be installed. It can be set in group properties of the group where this target belongs.

  There can really be only one java module in a group. This is a restriction put by automake. Please read automake info page for more details.

- Python module target type is for python module. Select this if you are grouping python sources into a module. You need to provide an installation directory for this target where the sources will be installed. It can be set in group properties of the group where this target belongs.

- Scripts target is to group scripts. They will be installed in standard executable directory.

- Miscellaneous Data target type is to group simple files in the project. An installation directory needs to be specified in its group properties.

- Header Files target type is to group C/C++ header files that need to be installed in system (for example as part of library API). For header files that do not need to be installed, make them part of the Program target along with the sources. They will be installed in standard include directory unless installation path is specified in its group properties.

- Man documentation and Info documentation target types are for grouping man and info documentation respectively. By default, they will be installed in standard installation directories.

### Removing Targets

To remove a target:

- Select the target in Project Manager view

- Select Remove from the Operation menu.

The sources associated with the targets will also be removed from the project (they are not deleted from the file system, though).

## Adding and Removing Files

### Adding Source Files

Select menu item Project Add Source File. From the dialog, select the target to which the file should be added and the file itself. You can add multiple files at once. To do that, select multiple files from the file selection dialog using either SHIFT or CONTROL key. Then click Add button to finally add the files in project.

By default, current editor file would be preselected for addition in the dialog. Other convenient way to add a file is to select it in File Manager and choosing Add to project from the Operation menu.

If the file you choose has already been added to the project, then Anjuta will not add it again. It will also give you a warning that the file is already added.

If the file you choose is not in the project directory, you will be asked to confirm that you wish to copy the file into the target's directory. Anjuta cannot add files which are outside of target's directory.

### Removing Source Files

To remove a file from the project, select the file you want to remove from the Project window, right-click to open the Operation menu and choose Remove.

A confirmation dialog will appear, and the file will be removed from the project.

#### The file is not deleted!

The file is not deleted from the filesystem. It still exists, and you can add it back again later if you so wish. The file is only removed from the project listing, and will not take part in any of the project operations such as compiling, building, distribution etc..

## Project Configuration

Project configuration involves setting the correct build flags for targets, groups and project itself. You can set these flags in their respective properties dialog.

You can freely use autoconf and automake variables that are automatically set for the project during configuration. Apart from these automatically set variables, you can also defined your own variables in Project Properties use them in properties. This will make it easy to update flags later, especially when the variable is used in several targets.

Some of the many common variables are listed here. For full list of them see automake info documentation.

- $(prefix): The installation prefix. The project is installed under various sub-directories under this prefix. By default it is /usr/local.

- $(bindir): The installation directory for executable binaries. All your executable and scripts targets would be installed in this directory. By default, it is $(prefix)/bin.

- $(libdir): The installation directory for libraries. All your library targets (both shared and static) would be installed in this directory or a subdirectory below it. By default, it is $(prefix)/lib.

- $(module_CFLAGS) and $(module_LIBS): These flags are set by configure for the packages that your project depends on. The packages used by the project are set in Project Properties. 'module' is the packages group that you give in project properties.

### Project properties

Project properties dialog can be only brought by choosing Project Properties. You can:

- Set project name, version and URL in General page. Configure variables can also be use in these fields. The URL is the bug report URL for the project.

- Add and remove dependencies for your project in Packages page. See below for details.

- Create more configure variables in Variables page to use in group and target properties.

Dependencies are external packages that the project uses and hence required to build it. Only packages installed using pkg-config can be added from this interface. For others, the configure.ac file can be edited manually.

#### Project properties dialog

Project properties dialog

External package dependencies are grouped into modules, so that their combined build flags can be conveniently added to different targets. Modules are just arbitrary names given to group the packages and can be named anything (only alphanumeric and _ are allowed in module name). Usually, they follow the name of targets they would be use in. Consequently, for small projects with single targets, just one module to hold all dependencies is enough.

Each package exports a set of compiler flags and libraries. They are aggregated together for all packages under a module and configure variables $(module_CFLAGS) and $(module_LIBS) are defined. These variables can then be used in Group properties and Target properties.

To add a package dependency:

- Select Project Properties to bring up project properties dialog.

- Select the tab Packages to bring up packages page.

- Select the module to add the package to. If there is no module created yet or there is no appropriate module, create one by clicking Add module. Give a sensible name to the module, preferably in UPPERCASE to match with rest of configure variables (only use alphanumeric and '_' characters) and press Enter to create it.

- Click Add Package to bring up package selection dialog.

- Select the package to add and click Add.

- Click Close to close the properties dialog.

### Group properties

To set group properties, select it in the Project window and active it. You can also bring it by selecting Operation menu Properties

Group Properties set to a group applies to all the targets under it. So any compiler or linker flags set there would be automatically be part of all the targets in it (in addition the targets individual properties). Following flags are available in group properties.

- Includes: Set your $(module_CFLAGS) variables and other include directories for your c and c++ targets. You need to provide the full include options of the compiler here, e.g. -I/usr/include/blah. The include paths will be use to find the include files in your source files. You can also add other sort of compiler flags here, but they are preferred to be set in their respective compiler flags properties (see below).

  Usually your configure script would also make some automatically determined compiler flags. The variables usually end with _CFLAGS, e.g $(PACKAGE_CFLAGS). They are also set here. See setting Project properties for more details on these variables.

- Compiler settings: Set your compiler specific flags here. There are different fields for different compiler categories. Flags that can be set here depend on the actual compiler used. The default compiler use for c/c++ is gcc/g++ (gnu c compiler). Check out gcc info documentation for more details.

- Install directories: Targets in the group that require installation directories would each get a field to enter the installation directory. Set their installation directories as relative to one of the many automake directory variables, such as $(prefix), $(bindir), $(libdir), $(datadir) etc.

### Target properties

To set target properties, select it in the Project window and active it. You can also bring it by selecting Operation menu Properties

Target Properties set to a target applies to that target. So any compiler or linker flags set there would be just part of it (in addition the its group properties). Following flags are available in target properties.

- Compiler settings: Set your compiler specific flags here. There are different fields for different compiler categories. Flags that can be set here depend on the actual compiler used. The default compiler use for c/c++ is gcc/g++ (gnu c compiler). Check out gcc info documentation for more details.

- Linker flags: Set linker flags that should be used when linking the target. It applies only to Program and library targets. See ld info documentation for available linker options.

- Libraries: Set the libraries that the target depends on. Usually they are the $(module_LIBS) configure variables. See setting Project properties for more details on these variables.

## Compiling and Building

### Overview

An executable for a project is generated in two steps:

1. Compiling

2. Linking

These steps are collectively known as Building. Some other steps may also be involved in the build process, but for the sake of simplicity, we will only look at these two steps.

Compiling is the step in which object files are generated from their corresponding source files. 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 involved in creating the final executable.

Once the object files (`*.o` files) are ready, they are all linked together (along with any libraries) to generate the final executable. This step is called Linking.

### Compiling the source

In a project, the 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-edit-compile-.... loops while a developing the 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 the source files and link them together along with the libraries. The build command will note recompile those files which are already up-to-date (this is called the dependency check). If you have already compiled all of the 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 the 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 only 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 re-generated.

Since you have now got a rough understanding of the value of the dependency check, can you imagine how your life (as a programmer) would be if it had not been there? If you cannot answer just yet, then will find out when you start developing big projects!

Build Build will build all of the files in the `src` (source) directory, and generate the executable. Build Build Project will build the whole project — all of the subdirectories (including `src`), are built recursively.

### Creating a distribution package

To build the 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.

### Install

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.

### Configure

To run the `configure` script found in the top level project directory, choose the menu item Build Run Configure…. The script will determine the system configuration and create some of the files required to perform a build (such as `Makefile` and `config.h`). This is necessary because the application may depend on specific configuration of some of these options.

#### When to run configure

Until you run `configure`, you cannot start building the project.

The `configure` script 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 `configure` separately: the wizard will run it as a part of the project generation process.

You can also supply additional options to the configuration script. After choosing the Run Configure… menu item, a dialog will appear to prompt for additional options.

#### Configure options dialog

Configure options dialog

Enter any options (or leave it blank to accept the defaults) and click OK. To find out the options available to the `configure` script, enter `--help` in the option entry box and click OK. The options will be displayed in the Message window.

There is no requirement to run `configure` 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.

### Auto generate

Auto generation consists of two steps: running automake and then running autoconf. If an executable `autogen.sh` script is found in the top level project directory, this file will be executed instead of the two steps. Like configuration, auto generation is automatically handled by the build process. It can also be run in cases where it is difficult to configure the project (such as lots of errors reported due to mis-synchronization after modifying lots of build files).

#### When to run autogen.sh

Unlike configuration, auto generation does not need to be run even once — in fact, it does not need to be run at all! The option is available because it can be handy in some circumstances.

Choose the menu item Build Run Autogenerate… to auto generate the project.

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

### Clean

This option cleans the project and leaves it in a state that requires Build Project to be performed. It deletes all of the files generated by the build process, including all object files (`*.o` files) and the executable(s) in the `src` directory (and other directories).

Choose the menu item Build Clean to clean the project.

### Clean Project

There is not a great deal to say about Clean Project (which might also be called Clean distribution, or clean dist for short). It cleans the project and leaves it in a state that requires Run Configure… and Build Project to be performed. It deletes all of the files generated by the build processes, including all the object files (`*.o` files), executable(s) and Makefiles. In other words, it leaves the project as though it has just been extracted from a distribution tarball.

Choose the menu item Build Clean Project to completely clean the project.

## Executing program

Once an executable is ready after the build, you can execute it by choosing the menu item Build Execute, or pressing F3. You can specify which executable you want to use in case your project provides more than one and specify command line arguments.

### Dependencies

Unlike the build stage, execution doesn't check for dependencies (at least for the time being). In other words, it does not check if the executable is up-to-date before it executes the program. So, you must take care of that yourself.

### Choose executable and set program parameters

Setting program parameters