Commit | Line | Data |
---|---|---|
00ce3714 | 1 | \input texinfo @c -*-texinfo-*- |
f895bc1f | 2 | @setfilename ../info/ada-mode |
00ce3714 | 3 | @settitle Ada Mode |
4c2ca4f3 | 4 | @dircategory Emacs |
056565f7 GM |
5 | @direntry |
6 | * Ada mode: (ada-mode). The GNU Emacs mode for editing Ada. | |
7 | @end direntry | |
00ce3714 | 8 | |
8ba00a55 GM |
9 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
10 | @comment The following lines inserts the copyright notice | |
11 | @comment into the Info file. | |
12 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
00ce3714 | 13 | |
8ba00a55 GM |
14 | @ifnottex |
15 | Copyright @copyright{} 1999, 2000, 2001 Free Software Foundation, Inc. | |
00ce3714 | 16 | |
8ba00a55 GM |
17 | Permission is granted to copy, distribute and/or modify this document |
18 | under the terms of the GNU Free Documentation License, Version 1.1 or | |
19 | any later version published by the Free Software Foundation; with the | |
20 | Invariant Sections being ``The GNU Manifesto'', ``Distribution'' and | |
21 | ``GNU GENERAL PUBLIC LICENSE'', with the Front-Cover texts being ``A GNU | |
22 | Manual'', and with the Back-Cover Texts as in (a) below. A copy of the | |
23 | license is included in the section entitled ``GNU Free Documentation | |
24 | License'' in the Emacs manual. | |
00ce3714 | 25 | |
8ba00a55 GM |
26 | (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify |
27 | this GNU Manual, like GNU software. Copies published by the Free | |
28 | Software Foundation raise funds for GNU development.'' | |
00ce3714 | 29 | |
8ba00a55 GM |
30 | This document is part of a collection distributed under the GNU Free |
31 | Documentation License. If you want to distribute this document | |
32 | separately from the collection, you can do so by adding a copy of the | |
33 | license to the document, as described in section 6 of the license. | |
34 | @end ifnottex | |
35 | ||
36 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
37 | @comment TeX title page | |
38 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
00ce3714 GM |
39 | |
40 | @titlepage | |
41 | @sp 10 | |
42 | @title{Ada Mode} | |
43 | @sp 2 | |
44 | @subtitle An Emacs major mode for programming Ada 95 with GNAT | |
45 | @subtitle July 1998 for Ada Mode Version 3.0 | |
46 | @sp 2 | |
47 | ||
00ce3714 GM |
48 | @page |
49 | @vskip 0pt plus 1filll | |
8ba00a55 GM |
50 | Copyright @copyright{} 1999, 2000, 2001 Free Software Foundation, Inc. |
51 | @sp 1 | |
52 | Permission is granted to copy, distribute and/or modify this document | |
53 | under the terms of the GNU Free Documentation License, Version 1.1 or | |
54 | any later version published by the Free Software Foundation; with the | |
55 | Invariant Sections being ``The GNU Manifesto'', ``Distribution'' and | |
56 | ``GNU GENERAL PUBLIC LICENSE'', with the Front-Cover texts being ``A GNU | |
57 | Manual'', and with the Back-Cover Texts as in (a) below. A copy of the | |
58 | license is included in the section entitled ``GNU Free Documentation | |
59 | License'' in the Emacs manual. | |
00ce3714 | 60 | |
8ba00a55 GM |
61 | (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify |
62 | this GNU Manual, like GNU software. Copies published by the Free | |
63 | Software Foundation raise funds for GNU development.'' | |
00ce3714 | 64 | |
8ba00a55 GM |
65 | This document is part of a collection distributed under the GNU Free |
66 | Documentation License. If you want to distribute this document | |
67 | separately from the collection, you can do so by adding a copy of the | |
68 | license to the document, as described in section 6 of the license. | |
00ce3714 GM |
69 | @end titlepage |
70 | ||
8ba00a55 | 71 | |
00ce3714 GM |
72 | @node Top, Overview, (dir), (dir) |
73 | ||
74 | @menu | |
75 | * Overview:: | |
2e78ad14 RS |
76 | * Installation:: Installing Ada mode on your system |
77 | * Customization:: Setting up Ada mode to your taste | |
00ce3714 GM |
78 | * Project files:: Describing the organization of your project |
79 | * Syntax highlighting:: Using specific colors and fonts to highlight | |
80 | the structure of your files | |
81 | * Moving Through Ada Code:: Moving easily through Ada sources | |
82 | * Identifier completion:: Finishing words automatically | |
83 | * Index Menu of Subprograms:: A menu of all the types and subprograms | |
84 | defined in your application | |
85 | * File Browser:: Easy access to your files | |
86 | * Automatic Smart Indentation:: Indenting your code automatically as you type | |
87 | * Formatting Parameter Lists:: Formating subprograms parameter lists | |
88 | automatically | |
89 | * Automatic Casing:: Adjusting the case of words automatically | |
90 | * Statement Templates:: Inserting code templates | |
91 | * Comment Handling:: Reformatting comments easily | |
92 | * Compiling Executing:: Working with your application within Emacs | |
93 | * Debugging:: Debugging your application | |
94 | * Using non-standard file names:: Configuring Emacs for special file names | |
95 | * Working Remotely:: Working on a different machine | |
de803500 | 96 | * Index:: |
00ce3714 GM |
97 | @end menu |
98 | ||
99 | ||
100 | @c ----------------------------------------------------------------------- | |
101 | @node Overview, Installation, Top, Top | |
102 | @chapter Overview | |
103 | @c ----------------------------------------------------------------------- | |
104 | ||
105 | The Emacs mode for programming in Ada 95 with GNAT helps the user in | |
106 | understanding existing code and facilitates writing new code. It | |
107 | furthermore provides some utility functions for easier integration of | |
108 | standard Emacs features when programming in Ada. | |
109 | ||
110 | @section General features: | |
111 | ||
112 | @itemize @bullet | |
2e78ad14 RS |
113 | @item |
114 | full Integrated Development Environment: | |
00ce3714 | 115 | @itemize @bullet |
2e78ad14 RS |
116 | @item |
117 | support of ``project files'' for the configuration (directories, | |
00ce3714 | 118 | compilation options,...) |
2e78ad14 RS |
119 | @item |
120 | compiling and stepping through error messages. | |
121 | @item | |
122 | running and debugging your applications within Emacs. | |
00ce3714 | 123 | @end itemize |
2e78ad14 RS |
124 | @item |
125 | easy to use for beginners by pull-down menus, | |
126 | @item | |
127 | user configurable by many user-option variables. | |
00ce3714 GM |
128 | @end itemize |
129 | ||
130 | @section Ada mode features that help understanding code: | |
131 | ||
132 | @itemize @bullet | |
2e78ad14 RS |
133 | @item |
134 | functions for easy and quick stepping through Ada code, | |
135 | @item | |
136 | getting cross reference information for identifiers (e.g. find the | |
00ce3714 | 137 | defining place by a keystroke), |
2e78ad14 RS |
138 | @item |
139 | displaying an index menu of types and subprograms and move point to | |
00ce3714 | 140 | the chosen one, |
2e78ad14 RS |
141 | @item |
142 | automatic color highlighting of the various entities in Ada code. | |
00ce3714 GM |
143 | @end itemize |
144 | ||
145 | @section Emacs support for writing Ada code: | |
146 | ||
147 | @itemize @bullet | |
2e78ad14 RS |
148 | @item |
149 | switching between spec and body files with eventually | |
00ce3714 | 150 | auto-generation of body files, |
2e78ad14 RS |
151 | @item |
152 | automatic formating of subprograms parameter lists. | |
153 | @item | |
154 | automatic smart indentation according to Ada syntax, | |
155 | @item | |
156 | automatic completion of identifiers, | |
157 | @item | |
158 | automatic casing of identifiers, keywords, and attributes, | |
159 | @item | |
160 | insertion of statement templates, | |
161 | @item | |
162 | filling comment paragraphs like filling normal text, | |
00ce3714 GM |
163 | @end itemize |
164 | ||
165 | @c ----------------------------------------------------------------------- | |
166 | @node Installation, Customization, Overview, Top | |
167 | @chapter Installation | |
168 | @c ----------------------------------------------------------------------- | |
169 | ||
2e78ad14 | 170 | If you got Ada mode as a separate distribution, you should have a |
00ce3714 GM |
171 | look at the @file{README} file. It explains the basic steps necessary |
172 | for a good installation of the emacs Ada mode. | |
173 | ||
174 | Installing the Ada mode is basically just a matter of copying a few | |
175 | files into the Emacs library directories. Every time you open a file | |
176 | with a file extension of @file{.ads} or @file{.adb}, Emacs will | |
2e78ad14 | 177 | automatically load and activate Ada mode. |
00ce3714 | 178 | |
744e59f6 | 179 | @xref{Using non-standard file names}, if your files do |
00ce3714 GM |
180 | not use these extensions and if you want Emacs to automatically start the |
181 | Ada mode every time you edit an Ada file. | |
182 | ||
744e59f6 RC |
183 | Also, for general usage variables that you might want to set, |
184 | see | |
185 | @iftex | |
186 | @cite{The GNU Emacs Manual}. | |
187 | @end iftex | |
188 | @ifhtml | |
189 | @cite{The GNU Emacs Manual}. | |
190 | @end ifhtml | |
191 | @ifinfo | |
192 | @ref{Top, , The GNU Emacs Manual, emacs, The GNU Emacs Manual}. | |
193 | @end ifinfo | |
00ce3714 GM |
194 | |
195 | @c --------------------------------------------------------------------- | |
196 | @section Required files | |
197 | @c --------------------------------------------------------------------- | |
198 | ||
199 | This Ada mode works best with Emacs 20.3 or higher (the easy editing | |
200 | features for the project files won't work with any older version), but | |
201 | most of the commands should work with older versions too. Please try to | |
202 | install the most recent version of Emacs on your system before | |
2e78ad14 | 203 | installing Ada mode. |
00ce3714 | 204 | |
2e78ad14 | 205 | Although part of Ada mode is compiler-independent, the most advanced |
00ce3714 GM |
206 | features are specific to the Gnat compiler @url{http://www.gnat.com}. |
207 | ||
208 | The following files are provided with the Ada mode distribution: | |
209 | ||
210 | @itemize @bullet | |
211 | ||
2e78ad14 RS |
212 | @item |
213 | @file{ada-mode.el}: The main file for Ada mode. | |
00ce3714 GM |
214 | This is the only file which does not require Gnat. It contains the |
215 | functions for indentation, formatting of parameter lists, stepping | |
216 | through code, comment handling and automatic casing. Emacs versions | |
217 | 20.2 and higher already contain Ada mode version 2.27, which is an older | |
218 | version of this file and should be replaced. Loading @file{ada-mode.el} | |
219 | from the current distribution supersedes the standard installation. | |
220 | ||
2e78ad14 RS |
221 | @item |
222 | @file{ada-stmt.el}: Contains the statement templates feature. | |
00ce3714 | 223 | |
2e78ad14 RS |
224 | @item |
225 | @file{ada-xref.el}: This file provides the main support for Gnat. | |
00ce3714 GM |
226 | This is where the functions for cross-references, completion of |
227 | identifiers, support for project files and compilation of your | |
228 | application are defined. | |
229 | ||
2e78ad14 RS |
230 | @item |
231 | @file{ada-prj.el}: The functions to use for easy-edition of the | |
232 | project files. This file is the only one which really requires Emacs | |
233 | at least 20.2. It uses the new widget features from Emacs. | |
00ce3714 GM |
234 | |
235 | @end itemize | |
236 | ||
237 | @c -------------------------------------------------------------------- | |
238 | @node Customization, Project files, Installation, Top | |
2e78ad14 | 239 | @chapter Customizing Ada mode |
00ce3714 GM |
240 | @c --------------------------------------------------------------------- |
241 | ||
2e78ad14 | 242 | Ada mode is fully customizable. Everything, from the file names to |
00ce3714 GM |
243 | the automatic indentation and the automatic casing can be adapted to |
244 | your own needs. | |
245 | ||
246 | There are two different kinds of variables that control this | |
247 | customization, both are easy to modify. | |
248 | ||
249 | The first set of variables are standard Emacs variables. Of course, some | |
2e78ad14 | 250 | are defined only for Ada mode, whereas others have a more general |
00ce3714 GM |
251 | meaning in Emacs. Please see the Emacs documentation for more |
252 | information on the latest. In this documentation, we will detail all the | |
2e78ad14 | 253 | variables that are specific to Ada mode, and a few others. The names |
00ce3714 GM |
254 | will be given, as in @code{ada-case-identifier}. |
255 | ||
256 | Emacs provides an easy way to modify them, through a special mode called | |
257 | customization. To access this mode, select the menu | |
2e78ad14 | 258 | @samp{Ada->Customize}. This will open a new buffer with some fields that |
00ce3714 GM |
259 | you can edit. For instance, you will get something like: |
260 | @example | |
261 | Put below the compiler switches. | |
262 | comp_opt= _____________________________________ | |
263 | @end example | |
264 | The first line gives a brief description of the variable. The second | |
265 | line is the name of the variable and the field where you can give a | |
266 | value for this variable. Simply type what you want in the field. | |
267 | ||
268 | When you are finished modifying the variables, you can simply click on | |
269 | the @b{Save for future sessions} button at the top of the buffer (click | |
270 | with the middle mouse button). This will save the values in your | |
271 | @file{.emacs} file, so that next time you start Emacs they will have the | |
272 | same values. | |
273 | ||
274 | To modify a specific variable, you can directly call the function | |
2e78ad14 RS |
275 | @code{customize-variable} from Emacs (just type @kbd{M-x |
276 | customize-variable @key{RET} @var{variable-name} @key{RET}}). | |
00ce3714 GM |
277 | |
278 | Some users might prefer to modify the variables directly in their | |
279 | configuration file, @file{.emacs}. This file is coded in Emacs lisp, and | |
280 | the syntax to set a variable is the following: | |
281 | @example | |
282 | (setq variable-name value) | |
283 | @end example | |
284 | ||
285 | The second set of variables for customization are set through the use of | |
286 | project files. These variables are specific to a given project, whereas | |
287 | the first set was more general. For more information, please | |
288 | @xref{Project files}. | |
289 | ||
290 | @c --------------------------------------------------------------------- | |
291 | @node Project files, Syntax highlighting, Customization, Top | |
292 | @chapter Project files | |
293 | @c --------------------------------------------------------------------- | |
294 | ||
295 | @c --------------------------------------------------------------------- | |
296 | @section General overview | |
297 | @c --------------------------------------------------------------------- | |
298 | ||
299 | Emacs provides a full Integrated Development Environment for GNAT and | |
300 | Ada programmers. That is to say, editing, compiling, executing and | |
301 | debugging can be performed within Emacs in a convenient and natural way. | |
302 | ||
303 | To take full advantage of this features, it is possible to create a file | |
2e78ad14 | 304 | in the main directory of your application, with a @samp{.adp} extension. |
00ce3714 GM |
305 | This file contain all needed information dealing with the way your |
306 | application is organized between directories, the commands to compile, | |
307 | run and debug it etc. Creating this file is not mandatory and convenient | |
308 | defaults are automatically provided for simple setups. It only becomes | |
309 | necessary when those above mentioned defaults need customizing. | |
310 | ||
311 | A simple way to edit this file is provided for Emacs 20.2 or newer, with | |
312 | the following functions, that you can access also through the Ada | |
313 | menu. It is also possible to edit the project file as a regular text | |
314 | file. | |
315 | ||
316 | Once in the buffer for editing the project file, you can save your | |
2e78ad14 | 317 | modification using the @samp{[OK]} button at the bottom of the buffer, or |
00ce3714 | 318 | simply use the usual @kbd{C-x C-s} binding. To cancel your |
2e78ad14 | 319 | modifications, simply kill the buffer or click on the @samp{[CANCEL]} button |
00ce3714 GM |
320 | at the button. |
321 | ||
322 | Each buffer using Ada mode will be associated with one project file when | |
323 | there is one available, so that Emacs can easily navigate through | |
324 | related source files for instance. | |
325 | ||
326 | The exact algorithm to determine which project file should be used is | |
327 | described in the next section, but you can force the project file you | |
328 | want to use by setting one or two variables in your @file{.emacs} file. | |
329 | ||
330 | @itemize @bullet | |
2e78ad14 RS |
331 | @item |
332 | To set up a default project file to use for any directory, anywhere | |
00ce3714 GM |
333 | on your system, set the variable @code{ada-prj-default-project-file} to |
334 | the name of that file. | |
2e78ad14 | 335 | |
00ce3714 | 336 | @example |
2e78ad14 | 337 | (set 'ada-prj-default-project-file "/dir1/dir2/file") |
00ce3714 GM |
338 | @end example |
339 | ||
2e78ad14 RS |
340 | @item |
341 | For finer control, you can set a per-directory project file. | |
00ce3714 | 342 | This is done through the variable @code{ada-xref-default-prj-file}. |
2e78ad14 | 343 | |
00ce3714 GM |
344 | @example |
345 | (set 'ada-xref-default-prj-file | |
346 | '(("/dir1/dir2" . "/dir3/file1") | |
347 | ("/dir4/dir5" . "/dir6/file2"))) | |
348 | @end example | |
2e78ad14 | 349 | |
00ce3714 GM |
350 | Note: This has a higher priority than the first variable, so the first |
351 | choice is to use this variable settings, and otherwise | |
352 | @code{ada-prj-default-project-file}. | |
353 | @end itemize | |
354 | ||
355 | ||
356 | @table @kbd | |
2e78ad14 | 357 | @item C-c u |
de803500 | 358 | @findex ada-customize |
2e78ad14 RS |
359 | Create or edit the project file for the current buffer (@code{ada-customize}). |
360 | @item C-c c | |
de803500 | 361 | @findex ada-change-prj |
2e78ad14 | 362 | Change the project file associated with the current Ada buffer (@code{ada-change-prj}). |
00ce3714 | 363 | @item C-c d |
de803500 EZ |
364 | @findex ada-change-default-project |
365 | Change the default project file for the current directory | |
366 | (@code{ada-change-default-project}). Every new file opened from this | |
367 | directory will be associated with that file by default. | |
2e78ad14 | 368 | @item ada-set-default-project-file |
de803500 | 369 | @findex ada-set-default-project-file |
00ce3714 GM |
370 | Set the default project file to use for *any* Ada file opened anywhere |
371 | on your system. This sets this file only for the current Emacs session. | |
372 | @end table | |
373 | ||
374 | @c --------------------------------------------------------------------- | |
375 | @section Project file variables | |
376 | @c --------------------------------------------------------------------- | |
377 | ||
378 | The following variables can be defined in a project file. They all have | |
379 | a default value, so that small projects do not need to create a project | |
380 | file. | |
381 | ||
382 | Some variables below can be referenced in other variables, using a | |
383 | shell-like notation. For instance, if the variable @code{comp_cmd} | |
384 | contains a sequence like @code{$@{comp_opt@}}, the value of that variable | |
385 | will be substituted. | |
386 | ||
387 | Here is the list of variables: | |
388 | ||
2e78ad14 RS |
389 | @table @asis |
390 | @item @code{src_dir} [default: @code{"./"}] | |
391 | This is a list of directories where Ada mode will look for source | |
00ce3714 GM |
392 | files. These directories are used mainly in two cases, both as a switch |
393 | for the compiler and for the cross-references. | |
394 | ||
2e78ad14 RS |
395 | @item @code{obj_dir} [default: @code{"./"}] |
396 | This is a list of directories where to look for object and library | |
397 | files. The library files are the @samp{.ali} files generated by Gnat | |
398 | and that contain cross-reference informations. | |
00ce3714 | 399 | |
2e78ad14 | 400 | @item @code{comp_opt} [default: @code{""}] |
00ce3714 GM |
401 | Creates a variable which can be referred to subsequently by using the |
402 | @code{$@{comp_opt@}} notation. This is intended to store the default | |
2e78ad14 | 403 | switches given to @command{gnatmake} and @command{gcc}. |
00ce3714 | 404 | |
2e78ad14 | 405 | @item @code{bind_opt=@var{switches}} [default: @code{""}] |
00ce3714 GM |
406 | Creates a variable which can be referred to subsequently by using the |
407 | @code{$@{bind_opt@}} notation. This is intended to store the default | |
2e78ad14 | 408 | switches given to @command{gnatbind}. |
00ce3714 | 409 | |
2e78ad14 | 410 | @item @code{link_opt=@var{switches}} [default: @code{""}] |
00ce3714 GM |
411 | Creates a variable which can be referred to subsequently by using the |
412 | @code{$@{link_opt@}} notation. This is intended to store the default | |
2e78ad14 | 413 | switches given to @command{gnatlink}. |
00ce3714 | 414 | |
2e78ad14 | 415 | @item @code{main=@var{executable}} [default: @code{""}] |
00ce3714 GM |
416 | Specifies the name of the executable for the application. This variable |
417 | can be referred to in the following lines by using the @code{$@{main@}} | |
418 | notation. | |
419 | ||
2e78ad14 | 420 | @item @code{cross_prefix=@var{prefix}} [default: @code{""}] |
00ce3714 GM |
421 | This variable should be set if you are working in a cross-compilation |
422 | environment. This is the prefix used in front of the gnatmake commands. | |
423 | ||
2e78ad14 RS |
424 | @item @code{remote_machine=@var{machine}} [default: @code{""}] |
425 | This is the name of the machine to log into before issuing the | |
426 | compilation command. If this variable is empty, the command will be | |
427 | run on the local machine. This will not work on Windows NT machines, | |
428 | since Ada mode will simply precede the compilation command with a | |
429 | @command{rsh} command, unknown on Windows. | |
00ce3714 | 430 | |
2e78ad14 | 431 | @item @code{comp_cmd=@var{command}} [default: @code{"$@{cross_prefix@}gcc -c -I$@{src_dir@} -g -gnatq"}] |
00ce3714 GM |
432 | Specifies the command used to compile a single file in the application. |
433 | The name of the file will be added at the end of this command. | |
434 | ||
2e78ad14 | 435 | @item @code{make_cmd=@var{command}} [default: @code{"$@{cross_prefix@}gnatmake $@{main@} -aI$@{src_dir@} -aO$@{obj_dir@} -g -gnatq -cargs $@{comp_opt@} -bargs $@{bind_opt@} -largs $@{link_opt@}"]}' |
00ce3714 GM |
436 | Specifies the command used to recompile the whole application. |
437 | ||
2e78ad14 | 438 | @item @code{run_cmd=@var{command}} [default: @code{"$@{main@}"}] |
00ce3714 GM |
439 | Specifies the command used to run the application. |
440 | ||
2e78ad14 | 441 | @item @code{debug_cmd=@var{command}} [default: @code{"$@{cross_prefix@}gdb $@{main@}"}] |
00ce3714 GM |
442 | Specifies the command used to debug the application |
443 | ||
444 | @end table | |
445 | ||
446 | @c --------------------------------------------------------------------- | |
447 | @section Detailed algorithm | |
448 | @c --------------------------------------------------------------------- | |
449 | ||
450 | This section gives more details on the project file setup and is only of | |
451 | interest for advanced users. | |
452 | ||
453 | Usually, an Ada file is part of a larger application, whose sources and | |
454 | objects can be spread over multiple directories. The first time emacs is | |
455 | asked to compile, run or debug an application, or when a cross reference | |
456 | function is used (goto declaration for instance), the following steps | |
457 | are taken: | |
458 | ||
459 | @itemize @bullet | |
2e78ad14 RS |
460 | @item |
461 | find the appropriate project file, open and parse it. | |
00ce3714 GM |
462 | All the fields read in the project file are then stored by emacs |
463 | locally. Finding the project file requires a few steps: | |
464 | ||
465 | @itemize @minus | |
2e78ad14 RS |
466 | @item |
467 | if a file from the same directory was already associated with | |
00ce3714 GM |
468 | a project file, use the same one. This is the variable |
469 | @code{ada-xref-default-prj-file} described above. | |
2e78ad14 RS |
470 | @item |
471 | if the variable @code{ada-prj-default-project-file} is set, | |
00ce3714 | 472 | use the project file specified in this variable. |
2e78ad14 RS |
473 | @item |
474 | if there is a project file whose name is the same as the source file | |
475 | except for the suffix, use this one. | |
476 | @item | |
477 | if there's only one project file in the source directory, use | |
00ce3714 | 478 | that one. |
2e78ad14 RS |
479 | @item |
480 | if there are more than one project file in the source directory, | |
00ce3714 | 481 | ask the user. |
2e78ad14 RS |
482 | @item |
483 | if there are no project files in the source directory use standard | |
00ce3714 GM |
484 | default values. |
485 | @end itemize | |
486 | ||
487 | The first project file that is selected in a given directory becomes the | |
488 | default project file for this directory and is used implicitly for other | |
489 | sources unless specified otherwise by the user. | |
490 | ||
2e78ad14 | 491 | @item |
1cd0f7e3 | 492 | look for the corresponding @samp{.ali} file in the @code{obj_dir} defined |
00ce3714 GM |
493 | in the project file. If this file can not be found, emacs proposes to |
494 | compile the source using the @code{comp_cmd} defined in the project file | |
495 | in order to create the ali file. | |
496 | ||
2e78ad14 | 497 | @item |
1cd0f7e3 | 498 | when cross referencing is requested, the @samp{.ali} file is parsed to |
00ce3714 | 499 | determine the file and line of the identifier definition. It is |
1cd0f7e3 EZ |
500 | possible for the @samp{.ali} file to be older than the source file, |
501 | in which case it will be recompiled if the variable | |
502 | @code{ada-xref-create-ali} is set, otherwise the reference is searched | |
503 | in the obsolete ali file with possible inaccurate results. | |
00ce3714 | 504 | |
2e78ad14 RS |
505 | @item |
506 | look for the file containing the declaration using the source | |
00ce3714 GM |
507 | path @code{src_dir} defined in the project file. Put the cursor at the |
508 | correct position and display this new cursor. | |
509 | @end itemize | |
510 | ||
511 | @c ----------------------------------------------------------------------- | |
512 | @node Syntax highlighting, Moving Through Ada Code, Project files, Top | |
513 | @chapter Syntax highlighting | |
514 | @c ----------------------------------------------------------------------- | |
515 | ||
2e78ad14 | 516 | Ada mode is made to help you understand the structure of your source |
00ce3714 GM |
517 | files. Some people like having colors or different fonts depending on |
518 | the context: commands should be displayed differently than keywords, | |
2e78ad14 | 519 | which should also be different from strings, @dots{} |
00ce3714 GM |
520 | |
521 | Emacs is able to display in a different way the following syntactic | |
522 | entities: | |
523 | ||
524 | @itemize @bullet | |
525 | @item keywords | |
526 | @item commands | |
527 | @item strings | |
528 | @item gnatprep statements (preprocessor) | |
529 | @item types (under certain conditions) | |
530 | @item other words | |
531 | @end itemize | |
532 | ||
533 | This is not the default behavior for Emacs. You have to explicitly | |
534 | activate it. This requires that you add a new line in your @file{.emacs} | |
535 | file (if this file does not exist, just create it). | |
536 | ||
537 | @example | |
2e78ad14 | 538 | (global-font-lock-mode t) |
00ce3714 GM |
539 | @end example |
540 | ||
541 | But the default colors might not be the ones you like. Fortunately, | |
542 | there is a very easy way to change them. Just select the menu | |
2e78ad14 RS |
543 | @samp{Help->Customize->Specific Face...} and press @key{RET}. This |
544 | will display a buffer will all the ``faces'' (the colors) that Emacs knows | |
00ce3714 GM |
545 | about. You can change any of them. |
546 | ||
547 | ||
548 | @c ----------------------------------------------------------------------- | |
549 | @node Moving Through Ada Code, Identifier completion, Syntax highlighting, Top | |
550 | @chapter Moving Through Ada Code | |
551 | @c ----------------------------------------------------------------------- | |
552 | ||
553 | There are several easy to use commands to stroll through Ada code. All | |
554 | these functions are available through the Ada menu, and you can also use | |
555 | the following key bindings or the command names: | |
556 | ||
557 | @table @kbd | |
718fb8a1 | 558 | @item C-M-e |
de803500 | 559 | @findex ada-next-procedure |
2e78ad14 RS |
560 | Move to the next function/procedure/task, which ever comes next |
561 | (@code{ada-next-procedure}). | |
718fb8a1 | 562 | @item C-M-a |
de803500 | 563 | @findex ada-previous-procedure |
2e78ad14 RS |
564 | Move to previous function/procedure/task |
565 | (@code{ada-previous-procedure}). | |
566 | @item M-x ada-next-package | |
de803500 | 567 | @findex ada-next-package |
00ce3714 | 568 | Move to next package. |
2e78ad14 | 569 | @item M-x ada-prev-package |
de803500 | 570 | @findex ada-prev-package |
00ce3714 | 571 | Move to previous package. |
2e78ad14 | 572 | @item C-c C-a |
de803500 | 573 | @findex ada-move-to-start |
2e78ad14 RS |
574 | Move to matching start of @code{end} (@code{ada-move-to-start}). If |
575 | point is at the end of a subprogram, this command jumps to the | |
576 | corresponding @code{begin} if the user option | |
577 | @code{ada-move-to-declaration} is @code{nil} (default), it jumps to | |
578 | the subprogram declaration otherwise. | |
579 | @item C-c C-e | |
de803500 | 580 | @findex ada-move-to-end |
2e78ad14 RS |
581 | Move point to end of current block (@code{ada-move-to-end}). |
582 | @item C-c o | |
583 | Switch between corresponding spec and body file | |
584 | (@code{ff-find-other-file}). If the cursor is on a subprogram, switch | |
585 | between declaration and body. | |
00ce3714 | 586 | @item C-c c-d |
de803500 | 587 | @findex ada-goto-declaration |
00ce3714 GM |
588 | Move from any reference to its declaration and switch between |
589 | declaration and body (for procedures, tasks, private and incomplete | |
590 | types). | |
2e78ad14 | 591 | @item C-c C-r |
de803500 | 592 | @findex ada-find-references |
2e78ad14 RS |
593 | runs the @file{gnatfind} command to search for all references to the |
594 | entity pointed by the cursor (@code{ada-find-references}). Use | |
595 | @kbd{C-x `} (@code{next-error}) to visit each reference (as for | |
596 | compilation errors). | |
00ce3714 GM |
597 | @end table |
598 | ||
599 | These functions use the information in the output of the Gnat Ada | |
600 | compiler. However, if your application was compiled with the | |
2e78ad14 | 601 | @samp{-gnatx} switch, these functions will not work, since no extra |
00ce3714 GM |
602 | information is generated by GNAT. See GNAT documentation for further |
603 | information. | |
604 | ||
605 | Emacs will try to run Gnat for you whenever the cross-reference | |
606 | informations are older than your source file (provided the | |
2e78ad14 | 607 | @code{ada-xref-create-ali} variable is non-@code{nil}). Gnat then produces a |
00ce3714 | 608 | file with the same name as the current Ada file but with the extension |
2e78ad14 | 609 | changed to @file{.ali}. This files are normally used by the binder, but |
00ce3714 GM |
610 | they will also contain additional cross-referencing information. |
611 | ||
612 | @c ----------------------------------------------------------------------- | |
613 | @node Identifier completion, Index Menu of Subprograms, Moving Through Ada Code, Top | |
614 | @chapter Identifier completion | |
615 | @c ----------------------------------------------------------------------- | |
616 | ||
617 | @c ----------------------------------------------------------------------- | |
618 | @section Overview | |
619 | @c ----------------------------------------------------------------------- | |
620 | ||
2e78ad14 | 621 | Emacs and Ada mode provide two general ways for the completion of |
00ce3714 GM |
622 | identifiers. This is an easy way to type faster: you just have to type |
623 | the first few letters of an identifiers, and then loop through all the | |
624 | possible completions. | |
625 | ||
626 | The first method is general for Emacs. It will work both with Ada | |
2e78ad14 | 627 | buffers, but also in C buffers, Java buffers, @enddots{} The idea is to parse |
00ce3714 GM |
628 | all the opened buffers for possible completions. |
629 | ||
2e78ad14 RS |
630 | For instance, if the words @samp{my_identifier}, @samp{my_subprogram} |
631 | are the only words starting with @samp{my} in any of the opened files, | |
632 | then you will have this scenario: | |
633 | ||
634 | @quotation | |
00ce3714 | 635 | You type: my@key{M-/} |
2e78ad14 RS |
636 | Emacs inserts: @samp{my_identifier} |
637 | If you press @key{M-/} once again, Emacs replaces @samp{my_identifier} with | |
638 | @samp{my_subprogram}. | |
639 | Pressing @key{M-/} once more will bring you back to @samp{my_identifier}. | |
640 | @end quotation | |
00ce3714 GM |
641 | |
642 | This is a very fast way to do completion, and the casing of words will | |
643 | also be respected. | |
644 | ||
645 | The second method is specific to Ada buffer, and even to users of the | |
1cd0f7e3 EZ |
646 | Gnat compiler. Emacs will search the cross-information found in the |
647 | @samp{.ali} files generated by Gnat for possible completions. | |
00ce3714 GM |
648 | |
649 | The main advantage is that this completion is more accurate: only | |
650 | existing identifier will be suggested, you don't need to have a file | |
2e78ad14 | 651 | opened that already contains this identifiers, @enddots{} |
00ce3714 GM |
652 | |
653 | On the other hand, this completion is a little bit slower and requires | |
654 | that you have compiled your file at least once since you created that | |
655 | identifier. | |
656 | ||
657 | @c ----------------------------------------------------------------------- | |
658 | @section Summary of commands | |
659 | @c ----------------------------------------------------------------------- | |
660 | ||
661 | @table @kbd | |
2e78ad14 | 662 | @item C-@key{TAB} |
de803500 | 663 | @findex ada-complete-identifier |
2e78ad14 RS |
664 | Complete accurately current identifier using information in @samp{.ali} file |
665 | (@code{ada-complete-identifier}). | |
00ce3714 | 666 | @item M-/ |
2e78ad14 | 667 | Complete identifier using buffer information (not Ada-specific). |
00ce3714 GM |
668 | @end table |
669 | ||
670 | @c ----------------------------------------------------------------------- | |
671 | @node Index Menu of Subprograms, File Browser, Identifier completion, Top | |
672 | @chapter Index Menu of Subprograms | |
673 | @c ----------------------------------------------------------------------- | |
674 | ||
675 | You can display a choice menu with all procedure/function/task | |
676 | declarations in the file and choose an item by mouse click to get to its | |
2e78ad14 RS |
677 | declaration. This function is accessible through the @samp{Ada} menu when |
678 | editing a Ada file, or simply through the following key binding: | |
00ce3714 GM |
679 | |
680 | @table @kbd | |
6aa73dc4 | 681 | @item C-S-Mouse-3 |
00ce3714 GM |
682 | display index menu |
683 | @end table | |
684 | ||
685 | @c ----------------------------------------------------------------------- | |
686 | @node File Browser, Automatic Smart Indentation, Index Menu of Subprograms, Top | |
687 | @chapter File Browser | |
688 | @c ----------------------------------------------------------------------- | |
689 | ||
690 | Emacs provides a special mode, called @code{speedbar}. When this mode is | |
691 | activated, a new frame is displayed, with a file browser. The files from | |
692 | the current directory are displayed, and you can click on them as you | |
693 | would with any file browser. The following commands are then available. | |
694 | ||
695 | You can click on a directory name or file name to open it. The editor | |
696 | will automatically select the best possible mode for this file, | |
2e78ad14 | 697 | including of course Ada mode for files written in Ada. |
00ce3714 | 698 | |
2e78ad14 | 699 | If you click on the @samp{[+]} symbol near a file name, all the symbols (types, |
00ce3714 GM |
700 | variables and subprograms) defined in that file will be displayed, and |
701 | you can directly click on them to open the right file at the right | |
702 | place. | |
703 | ||
704 | You can activate this mode by typing @key{M-x speedbar} in the editor. | |
705 | This will open a new frame. A better way might be to assicate the | |
706 | following key binding | |
707 | ||
708 | @example | |
709 | (global-set-key [f7] 'speedbar-get-focus) | |
710 | @end example | |
711 | ||
2e78ad14 | 712 | Every time you press @key{F7}, the mouse will automatically move to the |
00ce3714 GM |
713 | speedbar frame (which will be created if it does not exist). |
714 | ||
715 | @c ----------------------------------------------------------------------- | |
716 | @node Automatic Smart Indentation, Formatting Parameter Lists, File Browser, Top | |
717 | @chapter Automatic Smart Indentation | |
718 | @c ----------------------------------------------------------------------- | |
719 | ||
2e78ad14 | 720 | Ada mode comes with a full set of rules for automatic indentation. |
00ce3714 GM |
721 | You can of course configure the indentation as you want, by setting the |
722 | value of a few variables. | |
723 | ||
724 | As always, the preferred way to modify variables is to use the | |
2e78ad14 | 725 | @samp{Ada->Customize} menu (don't forget to save your changes!). This |
00ce3714 GM |
726 | will also show you some example of code where this variable is used, and |
727 | hopefully make things clearer. | |
728 | ||
729 | The relevant variables are the following: | |
730 | ||
2e78ad14 RS |
731 | @table @asis |
732 | @item @code{ada-broken-indent} (default value: 2) | |
733 | Number of columns to indent the continuation of a broken line. | |
00ce3714 | 734 | |
2e78ad14 RS |
735 | @item @code{ada-indent} (default value: 3) |
736 | Width of the default indentation. | |
00ce3714 | 737 | |
2e78ad14 RS |
738 | @item @code{ada-indent-record-rel-type} (default value: 3) |
739 | Indentation for @code{record} relative to @code{type} or @code{use}. | |
00ce3714 | 740 | |
2e78ad14 RS |
741 | @item @code{ada-indent-return} (default value: 0) |
742 | Indentation for @code{return} relative to @code{function} (if | |
743 | @code{ada-indent-return} is greater than 0), or the open parenthesis | |
744 | (if @code{ada-indent-return} is negative or null). Note that in the second | |
745 | case, when there is no open parenthesis, the indentation is done | |
746 | relative to @code{function} with the value of @code{ada-broken-indent}. | |
00ce3714 | 747 | |
2e78ad14 RS |
748 | @item @code{ada-label-indent} (default value: -4) |
749 | Number of columns to indent a label. | |
00ce3714 | 750 | |
2e78ad14 RS |
751 | @item @code{ada-stmt-end-indent} (default value: 0) |
752 | Number of columns to indent a statement @code{end} keyword on a separate line. | |
00ce3714 | 753 | |
2e78ad14 RS |
754 | @item @code{ada-when-indent} (default value: 3) |
755 | Indentation for @code{when} relative to @code{exception} or @code{case}. | |
00ce3714 | 756 | |
2e78ad14 RS |
757 | @item @code{ada-indent-is-separate} (default value: t) |
758 | Non-@code{nil} means indent @code{is separate} or @code{is abstract} if on a single line. | |
00ce3714 | 759 | |
2e78ad14 RS |
760 | @item @code{ada-indent-to-open-paren} (default value: t) |
761 | Non-@code{nil} means indent according to the innermost open parenthesis. | |
00ce3714 | 762 | |
2e78ad14 RS |
763 | @item @code{ada-indent-after-return} (default value: t) |
764 | Non-@code{nil} means that the current line will also be re-indented before | |
765 | inserting a newline, when you press @key{RET}. | |
00ce3714 GM |
766 | @end table |
767 | ||
768 | Most of the time, the indentation will be automatic, i.e when you will | |
2e78ad14 | 769 | press @key{RET}, the cursor will move to the correct column on the |
00ce3714 GM |
770 | next line. |
771 | ||
772 | However, you might want or need sometimes to re-indent the current line | |
773 | or a set of lines. For this, you can simply go to that line, or select | |
2e78ad14 | 774 | the lines, and then press @key{TAB}. This will automatically re-indent |
00ce3714 GM |
775 | the lines. |
776 | ||
2e78ad14 RS |
777 | Another mode of indentation exists that helps you to set up your |
778 | indentation scheme. If you press @kbd{C-c @key{TAB}}, Ada mode will do | |
779 | the following: | |
780 | ||
00ce3714 | 781 | @itemize @bullet |
2e78ad14 RS |
782 | @item |
783 | Reindent the current line, as @key{TAB} would do. | |
784 | @item | |
785 | Temporarily move the cursor to a reference line, i.e., the line that | |
786 | was used to calculate the current indentation. | |
787 | @item | |
788 | Display at the bottom of the window the name of the variable that | |
789 | provided the offset for the indentation. | |
00ce3714 GM |
790 | @end itemize |
791 | ||
792 | The exact indentation of the current line is the same as the one for the | |
793 | reference line, plus an offset given by the variable. | |
794 | ||
2e78ad14 RS |
795 | Once you know the name of the variable, you can either modify it |
796 | through the usual @samp{Ada->Customize} menu, or by typing @kbd{M-x | |
797 | customize-variable @key{RET}} in the Emacs window, and then give the | |
798 | name of the variable. | |
00ce3714 GM |
799 | |
800 | @table @kbd | |
2e78ad14 RS |
801 | @item @key{TAB} |
802 | Indent the current line or the current region. | |
718fb8a1 | 803 | @item C-M-\ |
2e78ad14 RS |
804 | Indent lines in the current selected block. |
805 | @item C-c @key{TAB} | |
806 | Indent the current line and prints the name of the variable used for | |
00ce3714 GM |
807 | indentation. |
808 | @end table | |
809 | ||
810 | ||
811 | ||
812 | @c ----------------------------------------------------------------------- | |
813 | @node Formatting Parameter Lists, Automatic Casing, Automatic Smart Indentation, Top | |
814 | @chapter Formatting Parameter Lists | |
815 | @c ----------------------------------------------------------------------- | |
816 | ||
2e78ad14 RS |
817 | To help you correctly align fields in a subprogram parameter list, |
818 | Emacs provides one function that will do most of the work for you. | |
819 | This function will align the declarations on the colon (@samp{:}) | |
820 | separating argument names and argument types, plus align the | |
821 | @code{in}, @code{out} and @code{in out} keywords if required. | |
00ce3714 GM |
822 | |
823 | @table @kbd | |
2e78ad14 | 824 | @item C-c C-f |
de803500 | 825 | @findex ada-format-paramlist |
2e78ad14 | 826 | Format the parameter list (@code{ada-format-paramlist}). |
00ce3714 GM |
827 | @end table |
828 | ||
829 | @c ----------------------------------------------------------------------- | |
830 | @node Automatic Casing, Statement Templates, Formatting Parameter Lists, Top | |
831 | @chapter Automatic Casing | |
832 | @c ----------------------------------------------------------------------- | |
833 | ||
834 | Casing of identifiers, attributes and keywords is automatically | |
835 | performed while typing when the variable @code{ada-auto-case} is set. | |
836 | Every time you press a word separator, the previous word is | |
837 | automatically cased. | |
838 | ||
839 | You can customize the automatic casing differently for keywords, | |
840 | attributes and identifiers. The relevant variables are the following: | |
841 | @code{ada-case-keyword}, @code{ada-case-attribute} and | |
842 | @code{ada-case-identifier}. | |
843 | ||
844 | All these variables can have one of the following values: | |
845 | ||
2e78ad14 | 846 | @table @code |
00ce3714 GM |
847 | @item downcase-word |
848 | The previous word will simply be in all lower cases. For instance | |
849 | @code{My_vARIable} is converted to @code{my_variable}. | |
850 | ||
851 | @item upcase-word | |
852 | The previous word will be fully converted to upper cases. For instance | |
853 | @code{My_vARIable} is converted to @code{MY_VARIABLE}. | |
854 | ||
855 | @item ada-capitalize-word | |
856 | All letters, except the first one of the word and every letter after the | |
2e78ad14 | 857 | @samp{_} character are lower cased. Other letters are upper cased. For |
00ce3714 GM |
858 | instance @code{My_vARIable} is converted to @code{My_Variable}. |
859 | ||
860 | @item ada-loose-case-word | |
861 | No letters is modified in the previous word, except the ones after the | |
2e78ad14 | 862 | @samp{_} character that are upper cased. For instance @code{My_vARIable} is |
00ce3714 GM |
863 | converted to @code{My_VARIable}. |
864 | @end table | |
865 | ||
866 | These functions, although they will work in most cases, will not be | |
867 | accurate sometimes. The Ada mode allows you to define some exceptions, | |
868 | that will always be cased the same way. | |
869 | ||
870 | The idea is to create a dictionary of exceptions, and store it in a | |
871 | file. This file should contain one identifier per line, with the casing | |
872 | you want to force. The default name for this file is | |
873 | @file{~/.emacs_case_exceptions}. You can of course change this name, | |
874 | through the variable @code{ada-case-exception-file}. | |
875 | ||
876 | Note that each line in this file must start with the key word whose | |
877 | casing you want to specify. The rest of the line can be used for | |
878 | comments (explaining for instance what an abbreviation means, as | |
2e78ad14 | 879 | recommended in the Ada 95 Quality and Style, paragraph 3.1.4). Thus, a |
00ce3714 GM |
880 | good example for this file could be: |
881 | ||
882 | @example | |
883 | DOD Department of Defense | |
884 | Text_IO | |
885 | GNAT The GNAT compiler from Ada Core Technologies | |
886 | @end example | |
887 | ||
888 | When working on project involving multiple programmers, we recommend | |
889 | that every member of the team sets this variable to the same value, | |
890 | which should point to a system-wide file that each of them can | |
891 | write. That way, you will ensure that the casing is consistent | |
892 | throughout your application(s). | |
893 | ||
de803500 | 894 | @findex ada-create-case-exception |
00ce3714 GM |
895 | There are two ways to add new items to this file: you can simply edit it |
896 | as you would edit any text file, and add or suppress entries in this | |
897 | file. Remember that you should put one entity per line. The other, | |
898 | easier way, is to position the cursor over the word you want to add, in | |
899 | an Ada buffer. This word should have the casing you want. Then simply | |
2e78ad14 | 900 | select the menu @samp{Ada->Edit->Create Case Exception}, or the key |
de803500 EZ |
901 | @kbd{C-c C-y} (@code{ada-create-case-exception}). The word will |
902 | automatically be added to the current list of exceptions and to the file. | |
00ce3714 GM |
903 | |
904 | It is sometimes useful to have multiple exception files around (for | |
905 | instance, one could be the standard Ada acronyms, the second some | |
906 | company specific exceptions, and the last one some project specific | |
907 | exceptions). If you set up the variable @code{ada-case-exception-file} | |
908 | as a list of files, each of them will be parsed and used in your emacs | |
909 | session. | |
910 | ||
911 | However, when you save a new exception through the menu, as described | |
912 | above, the new exception will be added to the first file in the list | |
913 | only. You can not automatically add an exception to one of the other | |
914 | files, although you can of course edit the files by hand at any time. | |
915 | ||
916 | Automatic casing can be performed on port or whole buffer using: | |
2e78ad14 | 917 | |
00ce3714 GM |
918 | @table @kbd |
919 | @item C-c C-b | |
de803500 EZ |
920 | @findex ada-adjust-case-buffer |
921 | Adjust case in the whole buffer (@code{ada-adjust-case-buffer}). | |
00ce3714 GM |
922 | @item C-c C-y |
923 | Create a new entry in the exception dictionary, with the word under | |
de803500 | 924 | the cursor (@code{ada-create-case-exception}) |
00ce3714 | 925 | @item C-c C-t |
de803500 | 926 | @findex ada-case-read-exceptions |
00ce3714 | 927 | Rereads the exception dictionary from the file |
de803500 | 928 | @code{ada-case-exception-file} (@code{ada-case-read-exceptions}). |
00ce3714 GM |
929 | @end table |
930 | ||
931 | @c ----------------------------------------------------------------------- | |
932 | @node Statement Templates, Comment Handling, Automatic Casing, Top | |
933 | @chapter Statement Templates | |
934 | @c ----------------------------------------------------------------------- | |
935 | ||
936 | NOTE: This features are not available on VMS for Emacs 19.28. The | |
937 | functions used here do not exist on Emacs 19.28. | |
938 | ||
939 | Templates exist for most Ada statements. They can be inserted in the | |
940 | buffer using the following commands: | |
941 | ||
942 | @table @kbd | |
943 | @item C-c t b | |
de803500 EZ |
944 | @findex ada-exception-block |
945 | exception Block (@code{ada-exception-block}). | |
00ce3714 | 946 | @item C-c t c |
de803500 EZ |
947 | @findex ada-case |
948 | case (@code{ada-case}). | |
00ce3714 | 949 | @item C-c t d |
de803500 EZ |
950 | @findex ada-declare-block |
951 | declare Block (@code{ada-declare-block}). | |
00ce3714 | 952 | @item C-c t e |
de803500 EZ |
953 | @findex ada-else |
954 | else (@code{ada-else}). | |
00ce3714 | 955 | @item C-c t f |
de803500 EZ |
956 | @findex ada-for-loop |
957 | for Loop (@code{ada-for-loop}). | |
00ce3714 | 958 | @item C-c t h |
de803500 EZ |
959 | @findex ada-header |
960 | Header (@code{ada-header}). | |
00ce3714 | 961 | @item C-c t i |
de803500 EZ |
962 | @findex ada-if |
963 | if (@code{ada-if}). | |
00ce3714 | 964 | @item C-c t k |
de803500 EZ |
965 | @findex ada-package-body |
966 | package Body (@code{ada-package-body}). | |
00ce3714 | 967 | @item C-c t l |
de803500 EZ |
968 | @findex ada-loop |
969 | loop (@code{ada-loop}). | |
970 | @item C-c p | |
971 | @findex ada-subprogram-body | |
972 | subprogram body (@code{ada-subprogram-body}). | |
00ce3714 | 973 | @item C-c t t |
de803500 EZ |
974 | @findex ada-task-body |
975 | task Body (@code{ada-task-body}). | |
00ce3714 | 976 | @item C-c t w |
de803500 EZ |
977 | @findex ada-while |
978 | while Loop (@code{ada-while}). | |
00ce3714 | 979 | @item C-c t u |
de803500 EZ |
980 | @findex ada-use |
981 | use (@code{ada-use}). | |
00ce3714 | 982 | @item C-c t x |
de803500 EZ |
983 | @findex ada-exit |
984 | exit (@code{ada-exit}). | |
00ce3714 | 985 | @item C-c t C-a |
de803500 EZ |
986 | @findex ada-array |
987 | array (@code{ada-array}). | |
00ce3714 | 988 | @item C-c t C-e |
de803500 EZ |
989 | @findex ada-elsif |
990 | elsif (@code{ada-elsif}). | |
00ce3714 | 991 | @item C-c t C-f |
de803500 EZ |
992 | @findex ada-function-spec |
993 | function Spec (@code{ada-function-spec}). | |
00ce3714 | 994 | @item C-c t C-k |
de803500 EZ |
995 | @findex ada-package-spec |
996 | package Spec (@code{ada-package-spec}). | |
00ce3714 | 997 | @item C-c t C-p |
de803500 EZ |
998 | @findex ada-procedure-spec |
999 | procedure Spec (@code{ada-package-spec}. | |
00ce3714 | 1000 | @item C-c t C-r |
de803500 EZ |
1001 | @findex ada-record |
1002 | record (@code{ada-record}). | |
00ce3714 | 1003 | @item C-c t C-s |
de803500 EZ |
1004 | @findex ada-subtype |
1005 | subtype (@code{ada-subtype}). | |
00ce3714 | 1006 | @item C-c t C-t |
de803500 EZ |
1007 | @findex ada-task-spec |
1008 | task Spec (@code{ada-task-spec}). | |
00ce3714 | 1009 | @item C-c t C-u |
de803500 EZ |
1010 | @findex ada-with |
1011 | with (@code{ada-with}). | |
00ce3714 | 1012 | @item C-c t C-v |
de803500 EZ |
1013 | @findex ada-private |
1014 | private (@code{ada-private}). | |
00ce3714 | 1015 | @item C-c t C-w |
de803500 EZ |
1016 | @findex ada-when |
1017 | when (@code{ada-when}). | |
00ce3714 | 1018 | @item C-c t C-x |
de803500 EZ |
1019 | @findex ada-exception |
1020 | exception (@code{ada-exception}). | |
00ce3714 | 1021 | @item C-c t C-y |
de803500 EZ |
1022 | @findex ada-type |
1023 | type (@code{ada-type}). | |
00ce3714 GM |
1024 | @end table |
1025 | ||
1026 | @c ----------------------------------------------------------------------- | |
1027 | @node Comment Handling, Compiling Executing, Statement Templates, Top | |
1028 | @chapter Comment Handling | |
1029 | @c ----------------------------------------------------------------------- | |
1030 | ||
1031 | By default, comment lines get indented like Ada code. There are a few | |
1032 | additional functions to handle comments: | |
1033 | ||
1034 | ||
1035 | @table @kbd | |
1036 | @item M-; | |
1037 | Start a comment in default column. | |
1038 | @item M-j | |
1039 | Continue comment on next line. | |
2e78ad14 | 1040 | @item C-c ; |
00ce3714 GM |
1041 | Comment the selected region (add -- at the beginning of lines). |
1042 | @item C-c : | |
1043 | Uncomment the selected region | |
1044 | @item M-q | |
1045 | autofill the current comment. | |
1046 | @end table | |
1047 | ||
1048 | @c ----------------------------------------------------------------------- | |
1049 | @node Compiling Executing, Debugging, Comment Handling, Top | |
1050 | @chapter Compiling Executing | |
1051 | @c ----------------------------------------------------------------------- | |
1052 | ||
1053 | Ada mode provides a much complete environment for compiling, debugging | |
1054 | and running an application within Emacs. | |
1055 | ||
1056 | All the commands used by Emacs to manipulate your application can be | |
1057 | customized in the project file. Some default values are provided, but | |
1058 | these will likely not be good enough for a big or even medium-sized | |
1059 | project. See the section on the project file for an explanation on how | |
1060 | to set up the commands to use. | |
1061 | ||
1062 | One of the variables you can set in your project file, | |
1063 | @code{cross_prefix}, indicates whether you are using a cross-compilation | |
1064 | environment, and if yes for which target. The default command used for | |
1065 | compilation will add this @code{cross_prefix} in front of the name: | |
1066 | @code{gcc} will become @code{cross_prefix}-@code{gcc}, @code{gnatmake} | |
1cd0f7e3 | 1067 | will become @code{cross_prefix}-@code{gnatmake}, @enddots{} |
00ce3714 GM |
1068 | |
1069 | This will also modify the way your application is run and debugged, | |
1070 | although this is not implemented at the moment. | |
1071 | ||
1072 | Here are the commands for building and using an Ada application | |
1073 | ||
1074 | @itemize @bullet | |
1075 | ||
1076 | @item Compiling the current source | |
1077 | This command is issued when issuing the @code{compile} command from the | |
1078 | Ada menu. It compiles unconditionally the current source using the | |
1079 | @code{comp_cmd} variable of the project file. Compilation options can be | |
1080 | customized with the variable @code{comp_opt} of the project file. | |
1081 | ||
1082 | Emacs will display a new buffer that contains the result of the | |
1083 | compilation. Each line associated with an error will become active: you | |
1084 | can simply click on it with the middle button of the mouse, or move the | |
2e78ad14 | 1085 | cursor on it and press @key{RET}. Emacs will then display the |
00ce3714 GM |
1086 | relevant source file and put the cursor on the line and column the error |
1087 | was found at. | |
1088 | ||
1089 | You can also simply press the @kbd{C-x `} key and Emacs will jump to the | |
1090 | first error. If you press that key again, it will move you to the second | |
1091 | error, and so on. | |
1092 | ||
1093 | Some error messages might also include references to some files. These | |
1094 | references are also clickable in the same way. | |
1095 | ||
1096 | ||
1097 | @item (Re)building the whole application | |
1098 | This command is issued when you select the @code{build} command from the | |
1099 | Ada menu. It compiles all obsolete units of the current application | |
1100 | using the @code{make_cmd} variable of the project file. Compilation | |
1101 | options can be customized with the variable @code{comp_opt} of the | |
1102 | project file, binder options with @code{bind_opt} and linker options | |
1103 | with @code{link_opt}. The main unit of the application may be specified | |
1104 | with @code{main}. | |
1105 | ||
1106 | The compilation buffer is also active in the same way it was for the above | |
1107 | command. | |
1108 | ||
1109 | @item Running the application | |
1110 | This command is issued when you select the @code{run} command from the | |
1111 | Ada menu. It executes the current application in an emacs | |
1112 | buffer. Arguments can be passed through before executing. The execution | |
1113 | buffer allows for interactive input/output. | |
1114 | ||
1115 | This command is not yet available in a cross-compilation | |
1116 | toolchain. Emacs would first need to log on the target before running | |
1117 | the application. This will be implemented in a future release of Gnat. | |
1118 | ||
1119 | @end itemize | |
1120 | ||
1121 | @c --------------------------------------------------------------------- | |
1122 | @node Debugging, Using non-standard file names, Compiling Executing, Top | |
1123 | @chapter Debugging your application | |
1124 | @c --------------------------------------------------------------------- | |
1125 | ||
1126 | You can set up in the project file a command to use to debug your | |
1127 | application. Emacs is compatible with a lot of debuggers, and provide an | |
1128 | easy interface to them. | |
1129 | ||
1130 | This selection will focus on the gdb debugger, and two of the graphical | |
1131 | interfaces that exist for it. | |
1132 | ||
1133 | In all cases, the main window in Emacs will be split in two: in the | |
1134 | upper buffer, the source code will appear, whereas the debugger | |
1135 | input/output window is displayed at the bottom. You can enter the | |
1136 | debugger commands as usual in the command window. Every time a new | |
1137 | source file is selected by the debugger (for instance as a result of a | |
1138 | @code{frame} command), the appropriate source file is displayed in the | |
1139 | upper buffer. | |
1140 | ||
1141 | The source window is interactive: you can click on an identifier with the | |
1142 | right mouse button, and print its value in the debugger window. You can | |
1143 | also set a breakpoint simply by right-clicking on a line. | |
1144 | ||
1145 | You can easily use Emacs as the source window when you are using a | |
1146 | graphical interface for the debugger. The interesting thing is that, | |
1147 | whereas you still have the graphical nifties, you can also you the | |
2e78ad14 RS |
1148 | cross-references features that Ada mode provides to look at the |
1149 | definition for the identifiers, @enddots{} | |
00ce3714 GM |
1150 | |
1151 | Here is how you can set up gdbtk and ddd for use with Emacs (These are | |
1152 | the commands you should setup in the project file): | |
1153 | ||
1154 | @itemize @bullet | |
1155 | @item gdbtk | |
2e78ad14 | 1156 | should be used with the switch @samp{--emacs_gdbtk}. It provides a nice |
00ce3714 GM |
1157 | backtrace window, as well as a tasks window. You can click interactively |
1158 | on both of them, and Emacs will display the source file on the correct | |
1159 | line. | |
1160 | ||
1161 | @item ddd (Data Display Debugger) | |
2e78ad14 RS |
1162 | should be used with the switches @samp{--tty} and |
1163 | @samp{--fullname}. Whenever you print a variable from Emacs, it will | |
1164 | be displayed graphically in the data window. | |
00ce3714 GM |
1165 | |
1166 | @end itemize | |
1167 | ||
1168 | ||
1169 | @c --------------------------------------------------------------------- | |
1170 | @node Using non-standard file names, Working Remotely, Debugging, Top | |
1171 | @chapter Using non-standard file names | |
1172 | @c --------------------------------------------------------------------- | |
1173 | ||
1174 | By default, Emacs is configured to use the GNAT style file names, where | |
1175 | file names are the package names, and the extension for spec and bodies | |
2e78ad14 | 1176 | are respectively @samp{.ads} and @samp{.adb}. |
00ce3714 GM |
1177 | |
1178 | If you want to use other types of file names, you will need to modify | |
2e78ad14 | 1179 | your @file{.emacs} file. |
00ce3714 | 1180 | |
2e78ad14 | 1181 | Adding new possible extensions is easy. Since Ada mode needs to know |
00ce3714 | 1182 | how to go from the body to the spec (and back), you always have to |
2e78ad14 | 1183 | specify both. A function is provided with Ada mode to add new |
00ce3714 GM |
1184 | extensions. |
1185 | ||
2e78ad14 RS |
1186 | For instance, if your spec and bodies files are called |
1187 | @file{@var{unit}_s.ada} and @file{@var{unit}_b.ada}, respectively, you | |
1188 | need to add the following to your @file{.emacs} file: | |
00ce3714 GM |
1189 | |
1190 | @example | |
1191 | (ada-add-extensions "_s.ada" "_b.ada") | |
1192 | @end example | |
1193 | ||
1194 | Note that it is possible to redefine the extension, even if they already | |
1195 | exist, as in: | |
1196 | ||
1197 | @example | |
1198 | (ada-add-extensions ".ads" "_b.ada") | |
1199 | (ada-add-extensions ".ads" ".body") | |
1200 | @end example | |
1201 | ||
1202 | This simply means that whenever the ada-mode will look for the body for | |
1203 | a file whose extension is @file{.ads}, it will take the first available | |
1204 | file that ends with either @file{.adb} (standard), @file{_b.ada} or | |
1205 | @file{.body}. | |
1206 | ||
2e78ad14 RS |
1207 | If the filename is not the unit name, then things are a little more |
1208 | complicated. You then need to rewrite the function | |
1209 | @code{ada-make-filename-from-adaname} (see the file @file{ada-mode.el} | |
1210 | for an example). | |
00ce3714 GM |
1211 | |
1212 | @c --------------------------------------------------------------------- | |
de803500 | 1213 | @node Working Remotely, Index, Using non-standard file names, Top |
00ce3714 GM |
1214 | @chapter Working Remotely |
1215 | @c --------------------------------------------------------------------- | |
1216 | ||
1217 | When you work on project that involve a lot of programmers, it is | |
1218 | generally the case that you will edit the files on your own machine, but | |
1219 | you want to compile, run and debug your application in another buffer. | |
1220 | ||
1221 | Fortunately, here too Emacs provides a very convenient way to do this. | |
1222 | ||
1223 | @c --------------------------------------------------------------------- | |
1224 | @section Remote editing | |
1225 | @c --------------------------------------------------------------------- | |
1226 | ||
1227 | First of all, the files do not need to be on your machine. Emacs can | |
1228 | edit any remote file, by doing transparent FTP sessions between your | |
1229 | machine and the remote machine that stores your files. This is a special | |
1230 | Emacs mode, called @code{ange-ftp}. To use it, you just have to use a | |
1231 | slightly different syntax when you open a file. | |
1232 | ||
2e78ad14 | 1233 | For instance, if you want to open the file @file{/work/foo.adb} on the machine |
00ce3714 GM |
1234 | aleph.gnu.org, where you log in as qwe, you would simply do this: |
1235 | ||
2e78ad14 RS |
1236 | @example |
1237 | C-x C-f /qwe@@aleph.gnu.org:/work/foo.adb @key{RET} | |
00ce3714 GM |
1238 | @end example |
1239 | ||
2e78ad14 RS |
1240 | @noindent |
1241 | i.e., use your name, the name of the machine and the name of the file. | |
1242 | ||
00ce3714 GM |
1243 | The first time, Emacs will ask you for a password that it will remember |
1244 | until you close the current Emacs. Even if the ftp session times out, | |
1245 | you won't need to reenter your password. | |
1246 | ||
1247 | Every time you save the file, Emacs will upload it to the remote machine | |
1248 | transparently. No file is modified on the local machine. | |
1249 | ||
1250 | @c --------------------------------------------------------------------- | |
1251 | @section Remote compiling | |
1252 | @c --------------------------------------------------------------------- | |
1253 | ||
1254 | If the machine you want to compile on is not the one your Emacs is | |
1255 | running on, you can set the variable @code{remote_machine} in the | |
1256 | project file for your application. | |
1257 | ||
2e78ad14 | 1258 | This will force Emacs to issue a @command{rsh} command for the compilation, |
00ce3714 GM |
1259 | instead of running it on the local machine. Unfortunately, this won't |
1260 | work on Windows workstations, since this protocol is not supported. | |
1261 | ||
1262 | @example | |
1263 | If your @code{remote_machine} is aleph.gnu.org and the standard | |
1264 | compilation command is @code{cd /work/ && gnatmake foo}, then Emacs will | |
1265 | actually issue the command @code{rsh aleph.gnu.org 'cd /work/ && | |
1266 | gnatmake foo'}. | |
1267 | @end example | |
1268 | ||
1269 | The advantage of using the @code{remote_machine} variable is that it is | |
1270 | easier to change that machine without having to modify the compilation | |
1271 | command. | |
1272 | ||
1273 | Note that if you need to set up some environment variables before the | |
1274 | compilation, you need to insert a call to the appropriate initialization | |
1275 | script in the compilation command, for instance: | |
1276 | ||
1277 | @example | |
2e78ad14 | 1278 | build_cmd= initialization_script; cd /work/ && gnatmake foo |
00ce3714 GM |
1279 | @end example |
1280 | ||
1281 | @c --------------------------------------------------------------------- | |
1282 | @section Remote running and debugging | |
1283 | @c --------------------------------------------------------------------- | |
1284 | ||
1285 | This feature is not completely implemented yet. | |
1286 | ||
1287 | However, most of the time, you will be able to run your application | |
2e78ad14 RS |
1288 | remotely simply by replacing it with a @command{rsh} call. |
1289 | For instance, if your command was @code{$@{main@}}, you could replace it with | |
1290 | @code{rsh aleph.gnu.org $@{main@}}. | |
00ce3714 | 1291 | |
2e78ad14 RS |
1292 | However, this would not work on vxworks, for instance, where |
1293 | @command{rsh} is not supported. | |
00ce3714 | 1294 | |
de803500 EZ |
1295 | @node Index, , Working Remotely, Top |
1296 | @unnumbered Index | |
1297 | ||
1298 | @printindex fn | |
1299 | ||
00ce3714 GM |
1300 | @contents |
1301 | @bye |