Node: Project files



Project files

General overview

Emacs provides a full Integrated Development Environment for GNAT and Ada programmers. That is to say, editing, compiling, executing and debugging can be performed within Emacs in a convenient and natural way.

To take full advantage of this features, it is possible to create a file in the main directory of your application, with a '.adp' extension. This file contain all needed information dealing with the way your application is organized between directories, the commands to compile, run and debug it etc. Creating this file is not mandatory and convenient defaults are automatically provided for simple setups. It only becomes necessary when those above mentioned defaults need customizing.

A simple way to edit this file is provided for Emacs 20.2 or newer, with the following functions, that you can access also through the Ada menu. It is also possible to edit the project file as a regular text file.

Once in the buffer for editing the project file, you can save your modification using the '[OK]' button at the bottom of the buffer, or simply use the usual C-x C-s binding. To cancel your modifications, simply kill the buffer or click on the '[CANCEL]' button at the button.

Each buffer using Ada mode will be associated with one project file when there is one available, so that Emacs can easily navigate through related source files for instance.

The exact algorithm to determine which project file should be used is described in the next section, but you can force the project file you want to use by setting one or two variables in your .emacs file.

C-c u ada-customize menu: Ada->Project->New/Edit
Create or edit the project file for the current buffer.
C-c c ada-change-prj
Change the project file associated with the current Ada buffer.
C-c d
Change the default project file for the current directory. Every new file opened from this directory will be associated with that file by default.
ada-set-default-project-file menu: Ada->Project->Set Default
Set the default project file to use for *any* Ada file opened anywhere on your system. This sets this file only for the current Emacs session.

Project file variables

The following variables can be defined in a project file. They all have a default value, so that small projects do not need to create a project file.

Some variables below can be referenced in other variables, using a shell-like notation. For instance, if the variable comp_cmd contains a sequence like ${comp_opt}, the value of that variable will be substituted.

Here is the list of variables:

src_dir [default: "./"]
This is a list of directories where the Ada mode will look for source files. These directories are used mainly in two cases, both as a switch for the compiler and for the cross-references.
obj_dir [default: "./"]
This is a list of directories where to look for object and library files. The library files are the .ali files generated by Gnat and that contain cross-reference informations.
comp_opt [default: ""]
Creates a variable which can be referred to subsequently by using the ${comp_opt} notation. This is intended to store the default switches given to `gnatmake' and `gcc'.
bind_opt=SWITCHES [default: ""]
Creates a variable which can be referred to subsequently by using the ${bind_opt} notation. This is intended to store the default switches given to `gnatbind'.
link_opt=SWITCHES [default: ""]
Creates a variable which can be referred to subsequently by using the ${link_opt} notation. This is intended to store the default switches given to `gnatlink'.
main=EXECUTABLE [default: ""]
Specifies the name of the executable for the application. This variable can be referred to in the following lines by using the ${main} notation.
cross_prefix=PREFIX [default: ""]
This variable should be set if you are working in a cross-compilation environment. This is the prefix used in front of the gnatmake commands.
remote_machine=MACHINE [default: ""]
This is the name of the machine to log into before issuing the compilation command. If this variable is empty, the command will be run on the local machine. This will not work on Windows NT machines, since the Ada mode will simply precede the compilation command with a 'rsh' command, unknown on Windows.
comp_cmd=COMMAND [default: "${cross_prefix}gcc -c -I${src_dir} -g -gnatq"]
Specifies the command used to compile a single file in the application. The name of the file will be added at the end of this command.
make_cmd=COMMAND [default: "${cross_prefix}gnatmake ${main} -aI${src_dir} -aO${obj_dir} -g -gnatq -cargs ${comp_opt} -bargs ${bind_opt} -largs ${link_opt}"]'
Specifies the command used to recompile the whole application.
run_cmd=COMMAND [default: "${main}"]
Specifies the command used to run the application.
debug_cmd=COMMAND [default: "${cross_prefix}gdb ${main}"]
Specifies the command used to debug the application

Detailed algorithm

This section gives more details on the project file setup and is only of interest for advanced users.

Usually, an Ada file is part of a larger application, whose sources and objects can be spread over multiple directories. The first time emacs is asked to compile, run or debug an application, or when a cross reference function is used (goto declaration for instance), the following steps are taken: