# Project Management

## Introduction to managing projects

If the program or application you are developing is a small one, and it is only going to be run on your computer, then a single source file will often serve the purpose. If the application is more complex, with multiple source files, it is useful to be able to keep track of your program and its resources. Such a program becomes a project.

Many command-line tools are available to maintain and manage a project, and each tool has its own specific rules and capabilities. Do not worry — Anjuta will take care of everything.

It is still possible to make use of other tools, which has the added advantage of making your project more flexible and more adaptable. However, before you start editing all those makefiles, bear in mind the files that Anjuta manages. These files will all be overwritten.

If you do not want to get involved with manually editing project files, just relax and let Anjuta do it all.

## Creating a New Project

Choose the menu item File New 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 third page, enter all the necessary details for your project. You cannot change these settings later. No white spaces or any non-alphanumeric characters, except underscore (_) and dash (-), are allowed in any of the entry boxes in this page (except the Author text box). You should also select the Programming language which should be used for the initial project generation. Only C and C++ are supported at the moment. Finally, click on Next to proceed.

Enter a short description of your project on the fourth page. Click on Next to proceed.

On the fifth page, 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. Click on Next to proceed.

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.

## Loading and Saving Projects

### Loading Projects

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

If the project has recently been opened, then you will find it listed in the menu File Recent Projects. 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 Brwoser. 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 submenu.

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

### Importing Projects

The import project feature is used to import an already existing project and convert it into anjuta projcect. Activate the import project wizard from File Import project 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.

### Saving Projects

To save the current project, choose the menu item File Save Project or click on the Save Project button on the Extended toolbar. When a project is saved, only the files that need to be updated are actually written to disk, to avoid breaking any unnecessary dependencies.

Any build files that are flagged Disable Overwriting in the project configuration will also not be touched.

## Adding and Removing Files

There are various different types of file that Anjuta will manage for you in the project:

1. Source files

2. Document files

3. Pixmap files

4. Help files

5. Data files

6. PO files

Each of these different types exist in their own specific directories inside the project.

### Adding Files

Choose the corresponding menu item from the Project Import File submenu, or right-click on the project in the Project Listing and select the type of file from the Import File submenu on the Operations popup menu. Select the file you want to add in the dialog and click OK.

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 directory corresponding to the type you have selected, you will be asked to confirm that you wish to copy the file into that directory. Anjuta cannot add files which are outside of their correct directories.

### Removing Files

To remove a file from the project, select the file you want to remove from the Project Listing, right-click to open the Operation popup 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

Projects created by the wizard are further customizable. During the course of your project development, you are likely to add more features and more codes which will require new configuration setup. Goto Project Project Configuration to bring up the configuration dialog.

1. Descriptoin: This page contains the short descrption of your project which was provided during the project creation. Description of the project could be updated from here.

2. Build files: Some of the project's build files are managed by anjuta by default. These files are configure.in and various Makefile.am of the project. If you need to manually edit these files, disable them from being overwritten by anjuta. They could be disabled from overwriting by selecting the check boxes against them. Once that is done, anjuta will no longer overwrite them and hence you can freely edit those files.

3. Configuration scripts: Configure.in file, which could be found in the top level project directory, contains autoconf macros and scripts for configuring your application. You can provide additional scripts here for testing, setting macro variable etc. for your project. This would require you to have enough knowledge of autoconf/automake and to code them properly.

4. Extra Modules:Application wizard creates only a set of most common directories for your project. If you later wish to add more directories (for example when your project becomes bigger), you can specify the sub-directories here. These subdirectories will be made part of your project and their Makefiles will be configured when the project is configured. The sub-directory names should be space sapareted in the list. Two lists could be formed. First one will be build before src directory and second one will be build after the src directory. One important thing to note here is that anjuta will not manage the Makefile.am files in these sub-directories. You will have to keep them updated yourself.

5. Top level Makefile: Occationally, we need to provide additional make rules and other additional stuff in the top level Makefile.am (found in the top level directory) of the project. You can provide those codes here and anjuta will append them to the Makefile.am after it is updated.

### Updating project version

Currently, there is no easy way to set a version number to your project direcly through an interface. (wizard creates your project with 0.1 version). The next best thing you can to do is: Make sure the project is not open in anjuta, open the *.prj file of your project and edit the project.version propery. Save the project file and open it in anjuta. Save the project again from anjuta. You project version should now have bumped to the new value.

## Getting Project Information

To display the information for the current project, choose Project Project Information. A dialog will appear displaying various details about the project generation options.

### Project Information dialog

Project Information dialog

## Managing Project Files

This section details some of the more advanced information about the management of project files. If you do not want to know about low-level specifics, feel free to skip this section.

Anjuta will manage the following files of a project:

1. Project file --> [ `*.prj` file ]

2. Top level configure.in --> [ `configure.in` ]

3. Top level Makefile.am --> [ `Makefile.am` ]

4. Source Makefile.am --> [ `Makefile.am` in the `src` subdirectory ]

5. Document Makefile.am --> [ `Makefile.am` in the `doc` subdirectory ]

6. Help Makefile.am --> [ `Makefile.am` in the `help` subdirectory ]

7. Data Makefile.am --> [ `Makefile.am` in the `data` subdirectory ]

8. Pixmaps Makefile.am --> [ `Makefile.am` in the `pixmaps` subdirectory ]

9. POTFILE.in --> [ `POTFILE.in` the `po` subdirectory ]

If you are doing your own work on the build files for an individual project, then you should avoid conflicting with what Anjuta does. It is recommended that these files should not be touched.

If you wish to modify these files, choose Project Project Configuration … from the menubar, and disable the overwrite option for each of them on the Build files tabbed page.

You can also create your own subdirectories in the project. Managing build files in these directories is solely your job.

If your project has multiple executables, then do not mix them with the main executable for the project in the source directory. Create separate directories for them. Again, it is your job to manage them.

Enure that you add modules in to accommodate the subdirectories you have created. To do so, choose Project Project Configuration … from the menubar, and add the module information on the Modules tabbed page.

## Compiling, Building and Executing a Project

### 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 click on the Compile icon on the extended toolbar. 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 All 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 Distribution. 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.

### Configure

To run the `configure` script found in the top level project directory, choose the menu item Build 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 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 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 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 Auto generate 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 All 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 All

There is not a great deal to say about Clean All (which might also be called Clean distribution, or clean dist for short). It cleans the project and leaves it in a state that requires Configure and Build All 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 All to completely clean the project.