GNU Info
(ada-mode)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.
* To set up a default project file to use for any directory, anywhere
on your system, set the variable `ada-prj-default-project-file' to
the name of that file.
(set 'ada-prj-default-project-file "/dir1/dir2/file")
* For finer control, you can set a per-directory project file. This
is done through the variable `ada-xref-default-prj-file'.
(set 'ada-xref-default-prj-file
'(("/dir1/dir2" . "/dir3/file1")
("/dir4/dir5" . "/dir6/file2")))
Note: This has a higher priority than the first variable, so the
first choice is to use this variable settings, and otherwise
`ada-prj-default-project-file'.
`C-c u'
Create or edit the project file for the current buffer
(`ada-customize').
`C-c c'
Change the project file associated with the current Ada buffer
(`ada-change-prj').
`C-c d'
Change the default project file for the current directory
(`ada-change-default-project'). Every new file opened from this
directory will be associated with that file by default.
`ada-set-default-project-file'
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 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 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:
* find the appropriate project file, open and parse it. All the
fields read in the project file are then stored by emacs
locally. Finding the project file requires a few steps:
- if a file from the same directory was already associated with
a project file, use the same one. This is the variable
`ada-xref-default-prj-file' described above.
- if the variable `ada-prj-default-project-file' is set, use
the project file specified in this variable.
- if there is a project file whose name is the same as the
source file except for the suffix, use this one.
- if there's only one project file in the source directory, use
that one.
- if there are more than one project file in the source
directory, ask the user.
- if there are no project files in the source directory use
standard default values.
The first project file that is selected in a given directory
becomes the default project file for this directory and is used
implicitly for other sources unless specified otherwise by the
user.
* look for the corresponding `.ali' file in the `obj_dir' defined in
the project file. If this file can not be found, emacs proposes
to compile the source using the `comp_cmd' defined in the project
file in order to create the ali file.
* when cross referencing is requested, the `.ali' file is parsed to
determine the file and line of the identifier definition.
It is possible for the `.ali' file to be older than the source
file, in which case it will be recompiled if the variable
`ada-xref-create-ali' is set, otherwise the reference is searched
in the obsolete ali file with possible inaccurate results.
* look for the file containing the declaration using the source
path `src_dir' defined in the project file. Put the cursor at the
correct position and display this new cursor.
automatically generated by info2www version 1.2.2.9