Commit | Line | Data |
---|---|---|
00ce3714 | 1 | \input texinfo @c -*-texinfo-*- |
f895bc1f | 2 | @setfilename ../info/ada-mode |
00ce3714 GM |
3 | @settitle Ada Mode |
4 | ||
18f952d5 | 5 | @copying |
b65d8176 | 6 | Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004, |
4e6835db | 7 | 2005, 2006, 2007 Free Software Foundation, Inc. |
00ce3714 | 8 | |
18f952d5 | 9 | @quotation |
8ba00a55 | 10 | Permission is granted to copy, distribute and/or modify this document |
678e7c71 | 11 | under the terms of the GNU Free Documentation License, Version 1.2 or |
8ba00a55 GM |
12 | any later version published by the Free Software Foundation; with the |
13 | Invariant Sections being ``The GNU Manifesto'', ``Distribution'' and | |
14 | ``GNU GENERAL PUBLIC LICENSE'', with the Front-Cover texts being ``A GNU | |
15 | Manual'', and with the Back-Cover Texts as in (a) below. A copy of the | |
16 | license is included in the section entitled ``GNU Free Documentation | |
17 | License'' in the Emacs manual. | |
00ce3714 | 18 | |
8ba00a55 GM |
19 | (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify |
20 | this GNU Manual, like GNU software. Copies published by the Free | |
21 | Software Foundation raise funds for GNU development.'' | |
00ce3714 | 22 | |
8ba00a55 GM |
23 | This document is part of a collection distributed under the GNU Free |
24 | Documentation License. If you want to distribute this document | |
25 | separately from the collection, you can do so by adding a copy of the | |
26 | license to the document, as described in section 6 of the license. | |
18f952d5 KB |
27 | @end quotation |
28 | @end copying | |
8ba00a55 | 29 | |
18f952d5 KB |
30 | @dircategory Emacs |
31 | @direntry | |
11e52000 | 32 | * Ada mode: (ada-mode). Emacs mode for editing and compiling Ada code. |
18f952d5 | 33 | @end direntry |
00ce3714 GM |
34 | |
35 | @titlepage | |
36 | @sp 10 | |
37 | @title{Ada Mode} | |
38 | @sp 2 | |
11e52000 JB |
39 | @subtitle An Emacs major mode for programming in Ada |
40 | @subtitle Ada Mode Version 3.7 | |
00ce3714 | 41 | @sp 2 |
00ce3714 GM |
42 | @page |
43 | @vskip 0pt plus 1filll | |
18f952d5 | 44 | @insertcopying |
00ce3714 GM |
45 | @end titlepage |
46 | ||
11e52000 JB |
47 | @c fixme; title page doesn't show up in ada-mode.info; why bother with |
48 | @c it? | |
8ba00a55 | 49 | |
00ce3714 GM |
50 | @node Top, Overview, (dir), (dir) |
51 | ||
52 | @menu | |
53 | * Overview:: | |
11e52000 JB |
54 | * Installation:: Installing Ada mode on your system |
55 | * Customization:: Setting up Ada mode to your taste | |
56 | * Compiling Executing:: Working with your application within Emacs | |
57 | * Project files:: Describing the organization of your project | |
58 | * Compiling Examples:: A small tutorial | |
59 | * Moving Through Ada Code:: Moving easily through Ada sources | |
60 | * Identifier completion:: Finishing words automatically | |
61 | * Automatic Smart Indentation:: Indenting your code automatically as you type | |
62 | * Formatting Parameter Lists:: Formatting subprograms' parameter lists | |
00ce3714 | 63 | automatically |
11e52000 JB |
64 | * Automatic Casing:: Adjusting the case of words automatically |
65 | * Statement Templates:: Inserting code templates | |
66 | * Comment Handling:: Reformatting comments easily | |
84247bb5 | 67 | * GNU Free Documentation License:: The license for this documentation. |
de803500 | 68 | * Index:: |
00ce3714 GM |
69 | @end menu |
70 | ||
71 | ||
00ce3714 GM |
72 | @node Overview, Installation, Top, Top |
73 | @chapter Overview | |
00ce3714 | 74 | |
11e52000 JB |
75 | The Emacs mode for programming in Ada helps the user in understanding |
76 | existing code and facilitates writing new code. | |
00ce3714 | 77 | |
11e52000 JB |
78 | When the Gnu Ada compiler GNAT is used, the cross-reference |
79 | information output by the compiler is used to provide powerful code | |
80 | navigation (jump to definition, find all uses, etc). | |
00ce3714 | 81 | |
11e52000 JB |
82 | When you open a file with a file extension of @file{.ads} or |
83 | @file{.adb}, Emacs will automatically load and activate Ada mode. | |
00ce3714 | 84 | |
11e52000 JB |
85 | Ada mode works without any customization, if you are using the GNAT |
86 | compiler (@url{https://libre2.adacore.com/}) and the GNAT default | |
87 | naming convention. | |
00ce3714 | 88 | |
11e52000 JB |
89 | You must customize a few things if you are using a different compiler |
90 | or file naming convention; @xref{Other compiler}, @xref{Non-standard | |
91 | file names}. | |
92 | ||
93 | In addition, you may want to customize the indentation, | |
94 | capitalization, and other things; @xref{Other customization}. | |
95 | ||
96 | Finally, for large Ada projects, you will want to set up an Emacs | |
97 | Ada mode project file for each project; @xref{Project files}. Note | |
98 | that these are different from the GNAT project files used by gnatmake | |
99 | and other GNAT commands. | |
100 | ||
101 | See the Emacs info manual, section 'Running Debuggers Under Emacs', | |
102 | for general information on debugging. | |
00ce3714 | 103 | |
11e52000 JB |
104 | @node Installation, Customization, Overview, Top |
105 | @chapter Installation | |
106 | ||
107 | Ada mode is part of the standard Emacs distribution; if you use that, | |
108 | no files need to be installed. | |
109 | ||
110 | Ada mode is also available as a separate distribution, from the Emacs | |
111 | Ada mode website | |
112 | @uref{http://stephe-leake.org/emacs/ada-mode/emacs-ada-mode.html}. The | |
113 | separate distribution may be more recent. | |
114 | ||
115 | For installing the separate distribution, see the @file{README} file | |
116 | in the distribution. | |
117 | ||
118 | To see what version of Ada mode you have installed, do @key{M-x | |
119 | ada-mode-version}. | |
120 | ||
121 | The following files are provided with the Ada mode distribution: | |
00ce3714 GM |
122 | |
123 | @itemize @bullet | |
11e52000 | 124 | |
2e78ad14 | 125 | @item |
11e52000 JB |
126 | @file{ada-mode.el}: The main file for Ada mode, providing indentation, |
127 | formatting of parameter lists, moving through code, comment handling | |
128 | and automatic casing. | |
129 | ||
2e78ad14 | 130 | @item |
11e52000 JB |
131 | @file{ada-prj.el}: GUI editing of Ada mode project files, using Emacs |
132 | widgets. | |
00ce3714 | 133 | |
11e52000 JB |
134 | @item |
135 | @file{ada-stmt.el}: Ada statement templates. | |
00ce3714 | 136 | |
11e52000 JB |
137 | @item |
138 | @file{ada-xref.el}: GNAT cross-references, completion of identifiers, | |
139 | and compilation. Also provides project files (which are not | |
140 | GNAT-specific). | |
00ce3714 | 141 | |
11e52000 | 142 | @end itemize |
00ce3714 | 143 | |
11e52000 JB |
144 | @node Customization, Compiling Executing, Installation, Top |
145 | @chapter Customizing Ada mode | |
00ce3714 | 146 | |
11e52000 JB |
147 | Here we assume you are familiar with setting variables in Emacs, |
148 | either thru 'customize' or in elisp (in your @file{.emacs} file). For | |
149 | a basic introduction to customize, elisp, and Emacs in general, see | |
150 | the tutorial in | |
744e59f6 RC |
151 | @iftex |
152 | @cite{The GNU Emacs Manual}. | |
153 | @end iftex | |
154 | @ifhtml | |
155 | @cite{The GNU Emacs Manual}. | |
156 | @end ifhtml | |
157 | @ifinfo | |
158 | @ref{Top, , The GNU Emacs Manual, emacs, The GNU Emacs Manual}. | |
159 | @end ifinfo | |
00ce3714 | 160 | |
11e52000 JB |
161 | These global Emacs settings are strongly recommended (put them in your |
162 | .emacs): | |
00ce3714 | 163 | |
11e52000 JB |
164 | @example |
165 | (global-font-lock-mode t) | |
166 | (transient-mark-mode t) | |
167 | @end example | |
00ce3714 | 168 | |
11e52000 JB |
169 | @samp{(global-font-lock-mode t)} turns on syntax |
170 | highlighting for all buffers (it is off by default because it may be | |
171 | too slow for some machines). | |
00ce3714 | 172 | |
11e52000 | 173 | @samp{(transient-mark-mode t)} highlights selected text. |
00ce3714 | 174 | |
11e52000 | 175 | See the Emacs help for each of these variables for more information. |
00ce3714 | 176 | |
11e52000 JB |
177 | @menu |
178 | * Non-standard file names:: | |
179 | * Other compiler:: | |
180 | * Other customization:: | |
181 | @end menu | |
00ce3714 | 182 | |
11e52000 JB |
183 | @node Non-standard file names, Other compiler, Customization, Customization |
184 | @section Non-standard file names | |
00ce3714 | 185 | |
11e52000 JB |
186 | By default, Ada mode is configured to use the GNAT file naming |
187 | convention, where file names are a simple modification of the Ada | |
188 | names, and the extension for specs and bodies are | |
189 | @samp{.ads} and @samp{.adb}, respectively. | |
00ce3714 | 190 | |
11e52000 JB |
191 | Ada mode uses the file extentions to allow moving from a package body |
192 | to the corresponding spec and back. | |
00ce3714 | 193 | |
11e52000 JB |
194 | Ada mode supports a list of alternative file extensions for specs and bodies. |
195 | ||
196 | For instance, if your spec and bodies files are called | |
197 | @file{@var{unit}_s.ada} and @file{@var{unit}_b.ada}, respectively, you | |
198 | can add the following to your @file{.emacs} file: | |
00ce3714 | 199 | |
00ce3714 | 200 | @example |
11e52000 | 201 | (ada-add-extensions "_s.ada" "_b.ada") |
00ce3714 | 202 | @end example |
00ce3714 | 203 | |
11e52000 JB |
204 | You can define additional extensions: |
205 | ||
206 | @example | |
207 | (ada-add-extensions ".ads" "_b.ada") | |
208 | (ada-add-extensions ".ads" ".body") | |
209 | @end example | |
210 | ||
211 | This means that whenever Ada mode looks for the body for a file | |
212 | whose extension is @file{.ads}, it will take the first available file | |
213 | that ends with either @file{.adb}, @file{_b.ada} or | |
214 | @file{.body}. | |
215 | ||
216 | Simililarly, if Ada mode is looking for a spec, it will look for | |
217 | @file{.ads} or @file{_s.ada}. | |
218 | ||
219 | If the filename is not derived from the Ada name following the GNAT | |
220 | convention, things are a little more complicated. You then need to | |
221 | rewrite the function @code{ada-make-filename-from-adaname}. Doing that | |
222 | is beyond the scope of this manual; see the current definitions in | |
223 | @file{ada-mode.el} and @file{ada-xref.el} for examples. | |
224 | ||
225 | @node Other compiler, Other customization, Non-standard file names, Customization | |
226 | @section Other compiler | |
227 | ||
228 | By default, Ada mode is configured to use the Gnu Ada compiler GNAT. | |
229 | ||
230 | To use a different Ada compiler, you must specify the command lines | |
231 | used to run that compiler, either in lisp variables or in Emacs | |
232 | Ada mode project files. See @ref{Project file variables} for the list | |
233 | of project variables, and the corresponding lisp variables. | |
234 | ||
235 | @node Other customization, , Other compiler, Customization | |
236 | @section Other customization | |
237 | ||
238 | All user-settable Ada mode variables can be set via the menu | |
239 | @samp{Ada | Customize}. Click on the @samp{Help} button there for help | |
240 | on using customize. | |
00ce3714 GM |
241 | |
242 | To modify a specific variable, you can directly call the function | |
11e52000 JB |
243 | @code{customize-variable}; just type @kbd{M-x customize-variable |
244 | @key{RET} @var{variable-name} @key{RET}}). | |
00ce3714 | 245 | |
11e52000 JB |
246 | Alternately, you can specify variable settings in the Emacs |
247 | configuration file, @file{.emacs}. This file is coded in Emacs lisp, | |
248 | and the syntax to set a variable is the following: | |
00ce3714 GM |
249 | @example |
250 | (setq variable-name value) | |
251 | @end example | |
252 | ||
11e52000 JB |
253 | @node Compiling Executing, Project files, Customization, Top |
254 | @chapter Compiling Executing | |
00ce3714 | 255 | |
11e52000 JB |
256 | Ada projects can be compiled, linked, and executed using commands on |
257 | the Ada menu. All of these commands can be customized via a project | |
258 | file (@pxref{Project files}), but the defaults are sufficient for using | |
259 | the GNAT compiler for simple projects (single files, or several files | |
260 | in a single directory). | |
00ce3714 | 261 | |
11e52000 JB |
262 | Even when no project file is used, the GUI project editor (menu |
263 | @key{Ada | Project | Edit}) shows the settings of the various project | |
264 | file variables referenced here. | |
2e78ad14 | 265 | |
11e52000 JB |
266 | @menu |
267 | * Compile commands:: | |
268 | * Compiler errors:: | |
269 | @end menu | |
00ce3714 | 270 | |
11e52000 JB |
271 | @node Compile commands, Compiler errors, Compiling Executing, Compiling Executing |
272 | @section Compile commands | |
2e78ad14 | 273 | |
11e52000 JB |
274 | Here are the commands for building and using an Ada project, as |
275 | listed in the Ada menu. | |
2e78ad14 | 276 | |
11e52000 JB |
277 | In multi-file projects, there must be one file that is the main |
278 | program. That is given by the @code{main_unit} project file variable; | |
279 | it defaults to the current file if not yet set, but is also set by the | |
280 | ``set main and build'' command. | |
00ce3714 | 281 | |
11e52000 | 282 | @table @code |
00ce3714 | 283 | |
11e52000 JB |
284 | @item Check file |
285 | Compiles the current file in syntax check mode, by running | |
286 | @code{check_cmd} defined in the current project file. This typically | |
287 | runs faster than full compile mode, speeding up finding and fixing | |
288 | compilation errors. | |
00ce3714 | 289 | |
11e52000 | 290 | This sets @code{main_unit} only if it has not been set yet. |
00ce3714 | 291 | |
11e52000 JB |
292 | @item Compile file |
293 | Compiles the current file, by running @code{comp_cmd} from the current | |
294 | project file. | |
00ce3714 | 295 | |
11e52000 | 296 | This does not set @code{main_unit}. |
00ce3714 | 297 | |
11e52000 JB |
298 | @item Set main and Build |
299 | Sets @code{main_unit} to the current file, then executes the Build | |
300 | command. | |
00ce3714 | 301 | |
11e52000 JB |
302 | @item Show main |
303 | Display @code{main_unit} in the message buffer. | |
304 | ||
305 | @item Build | |
306 | Compiles all obsolete units of the current @code{main_unit}, and links | |
307 | @code{main_unit}, by running @code{make_cmd} from the current project. | |
308 | ||
309 | This sets @code{main_unit} only if it has not been set yet. | |
310 | ||
311 | @item Run | |
312 | Executes the main program in a shell, displayed in a separate Emacs | |
313 | buffer. This runs @code{run_cmd} from the current project. The | |
314 | execution buffer allows for interactive input/output. | |
315 | ||
316 | To modify the run command, in particular to provide or change the | |
317 | command line arguments, type @key{C-u} before invoking the command. | |
318 | ||
319 | This command is not available for a cross-compilation toolchain. | |
00ce3714 GM |
320 | |
321 | @end table | |
11e52000 JB |
322 | It is important when using these commands to understand how |
323 | @code{main_unit} is used and changed. | |
00ce3714 | 324 | |
11e52000 JB |
325 | Build runs 'gnatmake' on the main unit. During a typical edit/compile |
326 | session, this is the only command you need to invoke, which is why it | |
327 | is bound to @key{C-c C-c}. It will compile all files needed by the | |
328 | main unit, and display compilation errors in any of them. | |
00ce3714 | 329 | |
11e52000 JB |
330 | Note that Build can be invoked from any Ada buffer; typically you will |
331 | be fixing errors in files other than the main, but you don't have to | |
332 | switch back to the main to invoke the compiler again. | |
00ce3714 | 333 | |
11e52000 JB |
334 | Novices and students typically work on single-file Ada projects. In |
335 | this case, @key{C-c C-m} will normally be the only command needed; it | |
336 | will build the current file, rather than the last-built main. | |
00ce3714 | 337 | |
11e52000 JB |
338 | There are three ways to change @code{main_unit}: |
339 | ||
340 | @enumerate | |
2e78ad14 | 341 | @item |
11e52000 JB |
342 | Invoke @key{Ada | Set main and Build}, which sets @code{main_unit} to |
343 | the current file. | |
00ce3714 | 344 | |
2e78ad14 | 345 | @item |
11e52000 JB |
346 | Invoke @key{Ada | Project | Edit}, edit @code{main_unit} and |
347 | @code{main}, and click @key{[save]} | |
348 | ||
2e78ad14 | 349 | @item |
11e52000 JB |
350 | Invoke @key{Ada | Project | Load}, and load a project file that specifies @code{main_unit} |
351 | ||
352 | @end enumerate | |
353 | ||
354 | @node Compiler errors, , Compile commands, Compiling Executing | |
355 | @section Compiler errors | |
356 | ||
357 | The @code{Check file}, @code{Compile file}, and @code{Build} commands | |
358 | all place compilation errors in a separate buffer named | |
359 | @code{*compilation*}. | |
360 | ||
361 | Each line in this buffer will become active: you can simply click on | |
362 | it with the middle button of the mouse, or move point to it and press | |
363 | @key{RET}. Emacs will then display the relevant source file and put | |
364 | point on the line and column where the error was found. | |
365 | ||
366 | You can also press the @kbd{C-x `} key (@code{next-error}), and Emacs | |
367 | will jump to the first error. If you press that key again, it will | |
368 | move you to the second error, and so on. | |
369 | ||
370 | Some error messages might also include references to other files. These | |
371 | references are also clickable in the same way, or put point after the | |
372 | line number and press @key{RET}. | |
373 | ||
374 | @node Project files, Compiling Examples, Compiling Executing, Top | |
375 | @chapter Project files | |
376 | ||
377 | An Emacs Ada mode project file specifies what directories hold sources | |
378 | for your project, and allows you to customize the compilation commands | |
379 | and other things on a per-project basis. | |
380 | ||
381 | Note that Ada mode project files @samp{*.adp} are different than GNAT | |
382 | compiler project files @samp{*.gpr}. | |
383 | ||
384 | @menu | |
385 | * Project File Overview:: | |
386 | * GUI Editor:: | |
387 | * Project file variables:: | |
388 | @end menu | |
389 | ||
390 | @node Project File Overview, GUI Editor, Project files, Project files | |
391 | @section Project File Overview | |
392 | ||
393 | Project files have a simple syntax; they may be edited directly. Each | |
394 | line specifies a project variable name and its value, separated by ``='': | |
395 | @example | |
396 | src_dir=/Projects/my_project/src_1 | |
397 | src_dir=/Projects/my_project/src_2 | |
398 | @end example | |
399 | ||
400 | Some variables (like @code{src_dir}) are lists; multiple occurances | |
401 | are concatenated. | |
402 | ||
403 | There must be no space between the variable name and ``='', and no | |
404 | trailing spaces. | |
405 | ||
406 | Alternately, a GUI editor for project files is available (@pxref{GUI | |
407 | Editor}). It uses Emacs widgets, similar to Emacs customize. | |
408 | ||
409 | The GUI editor also provides a convenient way to view current project | |
410 | settings, if they have been modified using menu commands rather than | |
411 | by editing the project file. | |
412 | ||
413 | After the first Ada mode build command is invoked, there is always a | |
414 | current project file, given by the lisp variable | |
415 | @code{ada-prj-default-project-file}. Currently, the only way to show | |
416 | the current project file is to invoke the GUI editor. | |
417 | ||
418 | To find the project file the first time, Ada mode uses the following | |
419 | search algorithm: | |
420 | ||
421 | @itemize @bullet | |
2e78ad14 | 422 | @item |
11e52000 JB |
423 | If @code{ada-prj-default-project-file} is set, use that. |
424 | ||
2e78ad14 | 425 | @item |
11e52000 JB |
426 | Otherwise, search for a file in the current directory with |
427 | the same base name as the Ada file, but extension given by | |
428 | @code{ada-prj-file-extension} (default @code{".adp"}). | |
429 | ||
2e78ad14 | 430 | @item |
11e52000 JB |
431 | If not found, search for @file{*.adp} in the current directory; if |
432 | several are found, prompt the user to select one. | |
433 | ||
2e78ad14 | 434 | @item |
11e52000 JB |
435 | If none are found, use @file{default.adp} in the current directory (even |
436 | if it does not exist). | |
437 | ||
00ce3714 GM |
438 | @end itemize |
439 | ||
11e52000 JB |
440 | This algorithm always sets @code{ada-prj-default-project-file}, even |
441 | when the file does not actually exist. | |
442 | ||
443 | To change the project file before or after the first one is found, | |
444 | invoke @key{Ada | Project | Load ...}. | |
445 | ||
446 | Or, in lisp, evaluate @code{ada-set-default-project-file "/path/file.adp"}. | |
447 | This sets @code{ada-prj-default-project-file}, and reads the project file. | |
448 | ||
449 | @node GUI Editor, Project file variables, Project File Overview, Project files | |
450 | @section GUI Editor | |
451 | ||
452 | The project file editor is invoked with the menu @samp{Ada | Projects | |
453 | | Edit}. | |
454 | ||
455 | Once in the buffer for editing the project file, you can save your | |
456 | modification using the @samp{[save]} button at the bottom of the | |
457 | buffer, or the @kbd{C-x C-s} binding. To cancel your modifications, | |
458 | kill the buffer or click on the @samp{[cancel]} button. | |
459 | ||
460 | @node Project file variables, , GUI Editor, Project files | |
461 | @section Project file variables | |
462 | ||
463 | The following variables can be defined in a project file; some can | |
464 | also be defined in lisp variables. | |
465 | ||
466 | To set a project variable that is a list, specify each element of the | |
467 | list on a separate line in the project file. | |
468 | ||
469 | Any project variable can be referenced in other project variables, | |
470 | using a shell-like notation. For instance, if the variable | |
471 | @code{comp_cmd} contains @code{$@{comp_opt@}}, the value of the | |
472 | @code{comp_opt} variable will be substituted when @code{comp_cmd} is | |
473 | used. | |
474 | ||
475 | Most project variables have defaults that can be changed by setting | |
476 | lisp variables; the table below identifies the lisp variable for each | |
477 | project variable. Lisp variables corresponding to project variables | |
478 | that are lists are lisp lists. | |
479 | ||
480 | Here is the list of variables. In the default values, the current | |
481 | directory @code{"."} is the project file directory. | |
482 | ||
483 | @c defined in ada-xref-set-default-prj-values; same order here | |
484 | @table @asis | |
485 | @item @code{build_dir} [default: @code{"."}] | |
486 | The compile commands will be issued in this directory. | |
487 | ||
488 | @item @code{src_dir} [default: @code{"."}] | |
489 | A list of directories to search for source files, both for compile | |
490 | commands and source navigation. | |
491 | ||
492 | @item @code{obj_dir} [default: @code{"."}] | |
493 | A list of directories to search for library files. Ada mode searches | |
494 | this list for the @samp{.ali} files generated by GNAT that contain | |
495 | cross-reference information. | |
496 | ||
497 | The compiler commands must place the @samp{.ali} files in one of these | |
498 | directories; the default commands do that. | |
499 | ||
500 | @item @code{casing} [default: @code{("~/.emacs_case_exceptions")} | |
501 | List of files containing casing exceptions. See the help on | |
502 | @code{ada-case-exception-file} for more info. | |
503 | @c FIXME: section on case exceptions | |
504 | ||
505 | Lisp variable: @code{ada-case-exception-file}. | |
506 | ||
507 | @item @code{comp_opt} [default: @code{"-gnatq -gnatQ"}] | |
508 | Holds user compiler options; used in the default compile commands. The | |
509 | default value tells gnatmake to generate library files for | |
510 | cross-referencing even when there are errors. | |
511 | ||
512 | If source code for the project is in multiple directories, the | |
513 | appropriate compiler options must be added here. @ref{Set source | |
514 | search path} for examples of this. Alternately, GNAT project files may | |
515 | be used; @ref{Use GNAT project file}. | |
516 | ||
517 | Lisp variable: @code{ada-prj-default-comp-opt}. | |
518 | ||
519 | @item @code{bind_opt} [default: @code{""}] | |
520 | Holds user binder options; used in the default build commands. | |
521 | ||
522 | Lisp variable: @code{ada-prj-default-bind-opt}. | |
523 | ||
524 | @item @code{link_opt} [default: @code{""}] | |
525 | Holds user linker options; used in the default build commands. | |
526 | ||
527 | Lisp variable: @code{ada-prj-default-link-opt}. | |
528 | ||
529 | @item @code{gnatmake_opt} [default: @code{"-g"}] | |
530 | Holds user gnatmake options; used in the default build commands. | |
531 | ||
532 | If a GNAT project file is used (for example @file{project.gpr}), this | |
533 | option should be set to @code{-Pproject.gpr}. | |
534 | ||
535 | Lisp variable: @code{ada-prj-default-gnatmake-opt}. | |
536 | ||
537 | @item @code{gnatfind_opt} [default: @code{"-rf"}] | |
538 | Holds user gnatfind options; used in the default find commands. | |
539 | ||
540 | Lisp variable: @code{ada-prj-gnatfind-switches}. | |
541 | ||
542 | @item @code{main} [default: current file] | |
543 | Specifies the name of the executable file for the project; used in the | |
544 | default build commands. | |
545 | ||
546 | @item @code{main_unit} [default: current Ada unit] | |
547 | Specifies the name of the main Ada unit for the project; used in the | |
548 | default build commands. | |
549 | ||
550 | @item @code{cross_prefix} [default: @code{""}] | |
551 | Name of target machine in a cross-compilation environment. Used in | |
552 | default compile and build commands. | |
553 | ||
554 | @item @code{remote_machine} [default: @code{""}] | |
555 | Name of the machine to log into before issuing the compile and build | |
556 | commands. If this variable is empty, the command will be run on the | |
557 | local machine. | |
558 | ||
559 | @item @code{comp_cmd} [default: @code{"$@{cross_prefix@}gnatmake -u -c $@{gnatmake_opt@} $@{full_current@} -cargs $@{comp_opt@}"}] | |
560 | Command used to compile a single file. | |
561 | The name of the file is substituted for @code{full_current}. | |
562 | ||
563 | Lisp variable: @code{ada-prj-default-comp-cmd}. | |
564 | ||
565 | @item @code{check_cmd} [default: @code{"$@{cross_prefix@}gnatmake -u -c -gnatc $@{gnatmake_opt@} $@{full_current@} -cargs $@{comp_opt@}"}] | |
566 | Command used to syntax check a single file. | |
567 | The name of the file is substituted for @code{full_current}. | |
568 | ||
569 | Lisp variable: @code{ada-prj-default-check-cmd} | |
00ce3714 | 570 | |
11e52000 JB |
571 | @item @code{make_cmd} [default: @code{"$@{cross_prefix@}gnatmake -o $@{main@} $@{main_unit@} $@{gnatmake_opt@} -cargs $@{comp_opt@} -bargs $@{bind_opt@} -largs $@{link_opt@}"}] |
572 | Command used to build the application. | |
573 | ||
574 | Lisp variable: @code{ada-prj-default-make-cmd}. | |
575 | ||
576 | @item @code{run_cmd} [default: @code{"./$@{main@}"}] | |
577 | Command used to run the application. | |
578 | ||
579 | @item @code{debug_pre_cmd} [default: @code{"cd $@{build_dir@}"}] | |
580 | Command executed before @code{debug_cmd}. | |
581 | ||
582 | @item @code{debug_cmd} [default: @code{"$@{cross_prefix@}gdb $@{main@}"}] | |
583 | Command used to debug the application | |
584 | ||
585 | Lisp variable: @code{ada-prj-default-debugger}. | |
586 | ||
587 | @item @code{debug_post_cmd} [default: @code{""}] | |
588 | Command executed after @code{debug_cmd}. | |
589 | ||
590 | @end table | |
591 | ||
592 | @node Compiling Examples, Moving Through Ada Code, Project files, Top | |
593 | @chapter Compiling Examples | |
594 | ||
595 | We present several small projects, and walk thru the process of | |
596 | compiling, linking, and running them. | |
597 | ||
598 | The first example illustrates more Ada mode features than the others; | |
599 | you should work thru that example before doing the others. | |
600 | ||
601 | All of these examples assume you are using GNAT. | |
602 | ||
603 | The source for these examples is available on the Emacs Ada mode | |
604 | website mentioned in @xref{Installation}. | |
605 | ||
606 | @menu | |
607 | * No project files:: Just menus | |
608 | * Set compiler options:: A basic Ada mode project file | |
609 | * Set source search path:: Source in multiple directories | |
610 | * Use GNAT project file:: | |
611 | @end menu | |
612 | ||
613 | @node No project files, Set compiler options, Compiling Examples, Compiling Examples | |
614 | @section No project files | |
615 | This example uses no project files. | |
616 | ||
617 | First, create a directory @file{Example_1}, containing: | |
618 | ||
619 | @file{hello.adb}: | |
620 | ||
621 | @example | |
622 | with Ada.Text_IO; | |
623 | procedure Hello | |
624 | is begin | |
625 | Put_Line("Hello from hello.adb"); | |
626 | end Hello; | |
627 | @end example | |
628 | ||
629 | Yes, this is missing ``use Ada.Text_IO;'' - we want to demonstrate | |
630 | compiler error handling. | |
631 | ||
632 | @file{hello_2.adb}: | |
633 | ||
634 | @example | |
635 | with Hello_Pkg; | |
636 | procedure Hello_2 | |
637 | is begin | |
638 | Hello_Pkg.Say_Hello; | |
639 | end Hello_2; | |
640 | @end example | |
641 | ||
642 | @file{hello_pkg.ads}: | |
643 | ||
644 | @example | |
645 | package Hello_Pkg is | |
646 | procedure Say_Hello; | |
647 | end Hello_Pkg; | |
648 | @end example | |
649 | ||
650 | @file{hello_pkg.adb}: | |
651 | ||
652 | @example | |
653 | with Ada.Text_IO; | |
654 | package Hello_Pkg is | |
655 | procedure Say_Hello | |
656 | is begin | |
657 | Ada.Text_IO.Put_Line ("Hello from hello_pkg.adb"); | |
658 | end Say_Hello; | |
659 | end Hello_Pkg; | |
660 | @end example | |
661 | ||
662 | Yes, this is missing the keyword @code{body}; another compiler error | |
663 | example. | |
664 | ||
665 | In buffer @file{hello.adb}, invoke @key{Ada | Check file}. You should | |
666 | get a @code{*compilation*} buffer containing something like (the | |
667 | directory paths will be different): | |
668 | ||
669 | @example | |
670 | cd c:/Examples/Example_1/ | |
671 | gnatmake -u -c -gnatc -g c:/Examples/Example_1/hello.adb -cargs -gnatq -gnatQ | |
672 | gcc -c -Ic:/Examples/Example_1/ -gnatc -g -gnatq -gnatQ -I- c:/Examples/Example_1/hello.adb | |
673 | hello.adb:4:04: "Put_Line" is not visible | |
674 | hello.adb:4:04: non-visible declaration at a-textio.ads:264 | |
675 | hello.adb:4:04: non-visible declaration at a-textio.ads:260 | |
676 | gnatmake: "c:/Examples/Example_1/hello.adb" compilation error | |
677 | @end example | |
678 | ||
679 | If you have enabled font-lock, the lines with actual errors (starting | |
680 | with @file{hello.adb}) are highlighted, with the file name in red. | |
681 | ||
682 | Now type @key{C-x `} (on a PC keyboard, @key{`} is next to @key{1}). | |
683 | Or you can click the middle mouse button on the first error line. The | |
684 | compilation buffer scrolls to put the first error on the top line, and | |
685 | point is put at the place of the error in the @file{hello.adb} buffer. | |
686 | ||
687 | To fix the error, change the line to be | |
688 | ||
689 | @example | |
690 | Ada.Text_IO.Put_Line ("hello from hello.adb"): | |
691 | @end example | |
692 | ||
693 | Now invoke @key{Ada | Show main}; this displays @file{Ada mode main_unit: hello}. | |
694 | ||
695 | Now (in buffer @file{hello.adb}), invoke @key{Ada | Build}. You are | |
696 | prompted to save the file (if you haven't already). Then the | |
697 | compilation buffer is displayed again, containing: | |
698 | ||
699 | @example | |
700 | cd c:/Examples/Example_1/ | |
701 | gnatmake -o hello hello -g -cargs -gnatq -gnatQ -bargs -largs | |
702 | gcc -c -g -gnatq -gnatQ hello.adb | |
703 | gnatbind -x hello.ali | |
704 | gnatlink hello.ali -o hello.exe -g | |
705 | @end example | |
706 | ||
707 | The compilation has succeeded without errors; @file{hello.exe} now | |
708 | exists in the same directory as @file{hello.adb}. | |
709 | ||
710 | Now invoke @key{Ada | Run}. A @file{*run*} buffer is displayed, | |
711 | containing | |
712 | ||
713 | @example | |
714 | Hello from hello.adb | |
715 | ||
716 | Process run finished | |
717 | @end example | |
718 | ||
719 | That completes the first part of this example. | |
720 | ||
721 | Now we will compile a multi-file project. Open the file | |
722 | @file{hello_2.adb}, and invoke @key{Ada | Set main and Build}. This | |
723 | finds an error in @file{hello_pkg.adb}: | |
724 | ||
725 | @example | |
726 | cd c:/Examples/Example_1/ | |
727 | gnatmake -o hello_2 hello_2 -g -cargs -gnatq -gnatQ -bargs -largs | |
728 | gcc -c -g -gnatq -gnatQ hello_pkg.adb | |
729 | hello_pkg.adb:2:08: keyword "body" expected here [see file name] | |
730 | gnatmake: "hello_pkg.adb" compilation error | |
731 | @end example | |
732 | ||
733 | This demonstrates that gnatmake finds the files needed by the main | |
734 | program. However, it cannot find files in a different directory, | |
735 | unless you use an Emacs Ada mode project file to specify the other directories; | |
736 | @xref{Set source search path}, or a GNAT project file; @ref{Use GNAT | |
737 | project file}. | |
738 | ||
739 | Invoke @key{Ada | Show main}; this displays @file{Ada mode main_unit: hello_2}. | |
740 | ||
741 | Move to the error with @key{C-x `}, and fix the error by adding @code{body}: | |
742 | ||
743 | @example | |
744 | package body Hello_Pkg is | |
745 | @end example | |
746 | ||
747 | Now, while still in @file{hello_pkg.adb}, invoke @key{Ada | Build}. | |
748 | gnatmake successfully builds @file{hello_2}. This demonstrates that | |
749 | Emacs has remembered the main file, in the project variable | |
750 | @code{main_unit}, and used it for the Build command. | |
751 | ||
752 | Finally, again while in @file{hello_pkg.adb}, invoke @key{Ada | Run}. | |
753 | The @code{*run*} buffer displays @code{Hello from hello_pkg.adb}. | |
754 | ||
755 | One final point. If you switch back to buffer @file{hello.adb}, and | |
756 | invoke @key{Ada | Run}, @file{hello_2.exe} will be run. That is | |
757 | because @code{main_unit} is still set to @code{hello_2}, as you can | |
758 | see when you invoke @key{Ada | Project | Edit}. | |
759 | ||
760 | There are three ways to change @code{main_unit}: | |
761 | ||
762 | @enumerate | |
2e78ad14 | 763 | @item |
11e52000 JB |
764 | Invoke @key{Ada | Set main and Build}, which sets @code{main_unit} to |
765 | the current file. | |
00ce3714 | 766 | |
2e78ad14 | 767 | @item |
11e52000 JB |
768 | Invoke @key{Ada | Project | Edit}, edit @code{main_unit} and |
769 | @code{main}, and click @key{[save]} | |
00ce3714 | 770 | |
2e78ad14 | 771 | @item |
11e52000 | 772 | Invoke @key{Ada | Project | Load}, and load a project file that specifies @code{main_unit} |
00ce3714 | 773 | |
11e52000 | 774 | @end enumerate |
00ce3714 | 775 | |
11e52000 JB |
776 | @node Set compiler options, Set source search path, No project files, Compiling Examples |
777 | @section Set compiler options | |
00ce3714 | 778 | |
11e52000 JB |
779 | This example illustrates using an Emacs Ada mode project file to set a |
780 | compiler option. | |
00ce3714 | 781 | |
11e52000 JB |
782 | If you have files from @file{Example_1} open in Emacs, you should |
783 | close them so you don't get confused. Use menu @key{File | Close | |
784 | (current buffer)}. | |
785 | ||
786 | In directory @file{Example_2}, create these files: | |
00ce3714 | 787 | |
11e52000 | 788 | @file{hello.adb}: |
00ce3714 GM |
789 | |
790 | @example | |
11e52000 JB |
791 | with Ada.Text_IO; |
792 | procedure Hello | |
793 | is begin | |
794 | Put_Line("Hello from hello.adb"); | |
795 | end Hello; | |
00ce3714 GM |
796 | @end example |
797 | ||
11e52000 JB |
798 | This is the same as @file{hello.adb} from @file{Example_1}. It has two |
799 | errors; missing ``use Ada.Text_IO;'', and no space between | |
800 | @code{Put_Line} and its argument list. | |
00ce3714 | 801 | |
11e52000 | 802 | @file{hello.adp}: |
00ce3714 | 803 | |
11e52000 JB |
804 | @example |
805 | comp_opt=-gnatyt | |
806 | @end example | |
807 | ||
808 | This tells the GNAT compiler to check for token spacing; in | |
809 | particular, there must be a space preceding a parenthesis. | |
810 | ||
811 | In buffer @file{hello.adb}, invoke @key{Ada | Project | Load...}, and | |
812 | select @file{Example_2/hello.adp}. | |
813 | ||
814 | Then, again in buffer @file{hello.adb}, invoke @key{Ada | Set main and | |
815 | Build}. You should get a @code{*compilation*} buffer containing | |
816 | something like (the directory paths will be different): | |
817 | ||
818 | @example | |
819 | cd c:/Examples/Example_2/ | |
820 | gnatmake -o hello hello -g -cargs -gnatyt -bargs -largs | |
821 | gcc -c -g -gnatyt hello.adb | |
822 | hello.adb:4:04: "Put_Line" is not visible | |
823 | hello.adb:4:04: non-visible declaration at a-textio.ads:264 | |
824 | hello.adb:4:04: non-visible declaration at a-textio.ads:260 | |
825 | hello.adb:4:12: (style) space required | |
826 | gnatmake: "hello.adb" compilation error | |
827 | @end example | |
828 | ||
829 | Compare this to the compiler output in @ref{No project files}; the | |
830 | gnatmake option @code{-cargs -gnatq -gnatQ} has been replaced by | |
831 | @code{-cargs -gnaty}, and an additional error is reported in | |
832 | @file{hello.adb} on line 4. This shows that @file{hello.adp} is being | |
833 | used to set the compiler options. | |
834 | ||
835 | Fixing the error, linking and running the code proceed as in @ref{No | |
836 | project files}. | |
837 | ||
838 | @node Set source search path, Use GNAT project file, Set compiler options, Compiling Examples | |
839 | @section Set source search path | |
840 | ||
841 | In this example, we show how to deal with files in more than one | |
842 | directory. We start with the same code as in @ref{No project files}; create those | |
843 | files (with the errors present) | |
844 | ||
845 | Create the directory @file{Example_3}, containing: | |
846 | ||
847 | @file{hello_pkg.ads}: | |
848 | ||
849 | @example | |
850 | package Hello_Pkg is | |
851 | procedure Say_Hello; | |
852 | end Hello_Pkg; | |
853 | @end example | |
854 | ||
855 | @file{hello_pkg.adb}: | |
856 | ||
857 | @example | |
858 | with Ada.Text_IO; | |
859 | package Hello_Pkg is | |
860 | procedure Say_Hello | |
861 | is begin | |
862 | Ada.Text_IO.Put_Line ("Hello from hello_pkg.adb"); | |
863 | end Say_Hello; | |
864 | end Hello_Pkg; | |
865 | @end example | |
866 | ||
867 | These are the same files from example 1; @file{hello_pkg.adb} has an | |
868 | error on line 2. | |
869 | ||
870 | In addition, create a directory @file{Example_3/Other}, containing these files: | |
871 | ||
872 | @file{Other/hello_3.adb}: | |
873 | ||
874 | @example | |
875 | with Hello_Pkg; | |
876 | with Ada.Text_IO; use Ada.Text_IO; | |
877 | procedure Hello_3 | |
878 | is begin | |
879 | Hello_Pkg.Say_Hello; | |
880 | Put_Line ("From hello_3"); | |
881 | end Hello_3; | |
882 | @end example | |
883 | ||
884 | There are no errors in this file. | |
885 | ||
886 | @file{Other/other.adp}: | |
887 | ||
888 | @example | |
889 | src_dir=.. | |
890 | comp_opt=-I.. | |
891 | @end example | |
892 | ||
893 | Note that there must be no trailing spaces. | |
894 | ||
895 | In buffer @file{hello_3.adb}, invoke @key{Ada | Project | Load...}, and | |
896 | select @file{Example_3/Other/other.adp}. | |
897 | ||
898 | Then, again in @file{hello_3.adb}, invoke @key{Ada | Set main and | |
899 | Build}. You should get a @code{*compilation*} buffer containing | |
900 | something like (the directory paths will be different): | |
901 | ||
902 | @example | |
903 | cd c:/Examples/Example_3/Other/ | |
904 | gnatmake -o hello_3 hello_3 -g -cargs -I.. -bargs -largs | |
905 | gcc -c -g -I.. hello_3.adb | |
906 | gcc -c -I./ -g -I.. -I- C:\Examples\Example_3\hello_pkg.adb | |
907 | hello_pkg.adb:2:08: keyword "body" expected here [see file name] | |
908 | gnatmake: "C:\Examples\Example_3\hello_pkg.adb" compilation error | |
909 | @end example | |
910 | ||
911 | Compare the @code{-cargs} option to the compiler output in @ref{Set | |
912 | compiler options}; this shows that @file{other.adp} is being used to | |
913 | set the compiler options. | |
914 | ||
915 | Move to the error with @key{C-x `}. Ada mode searches the list of | |
916 | directories given by @code{src_dir} for the file mentioned in the | |
917 | compiler error message. | |
918 | ||
919 | Fixing the error, linking and running the code proceed as in @ref{No | |
920 | project files}. | |
921 | ||
922 | @node Use GNAT project file, , Set source search path, Compiling Examples | |
923 | @section Use GNAT project file | |
924 | ||
925 | In this example, we show how to use a GNAT project file. | |
926 | ||
927 | Create the directory @file{Example_4}, containing: | |
928 | ||
929 | @file{hello_pkg.ads}: | |
930 | ||
931 | @example | |
932 | package Hello_Pkg is | |
933 | procedure Say_Hello; | |
934 | end Hello_Pkg; | |
935 | @end example | |
936 | ||
937 | @file{hello_pkg.adb}: | |
938 | ||
939 | @example | |
940 | with Ada.Text_IO; | |
941 | package Hello_Pkg is | |
942 | procedure Say_Hello | |
943 | is begin | |
944 | Ada.Text_IO.Put_Line ("Hello from hello_pkg.adb"); | |
945 | end Say_Hello; | |
946 | end Hello_Pkg; | |
947 | @end example | |
948 | ||
949 | These are the same files from example 1; @file{hello_pkg.adb} has an | |
950 | error on line 2. | |
951 | ||
952 | In addition, create a directory @file{Example_4/Gnat_Project}, | |
953 | containing these files: | |
954 | ||
955 | @file{Other/hello_4.adb}: | |
956 | ||
957 | @example | |
958 | with Hello_Pkg; | |
959 | with Ada.Text_IO; use Ada.Text_IO; | |
960 | procedure Hello_4 | |
961 | is begin | |
962 | Hello_Pkg.Say_Hello; | |
963 | Put_Line ("From hello_4"); | |
964 | end Hello_4; | |
965 | @end example | |
966 | ||
967 | There are no errors in this file. | |
968 | ||
969 | @file{Gnat_Project/hello_4.adp}: | |
970 | ||
971 | @example | |
972 | src_dir=.. | |
973 | gnatmake_opt=-Phello_4.gpr | |
974 | @end example | |
975 | ||
976 | @file{Gnat_Project/hello_4.gpr}: | |
977 | ||
978 | @example | |
979 | Project Hello_4 is | |
980 | for Source_Dirs use (".", ".."); | |
981 | end Hello_4; | |
982 | @end example | |
983 | ||
984 | In buffer @file{hello_4.adb}, invoke @key{Ada | Project | Load...}, and | |
985 | select @file{Example_4/Gnat_Project/hello_4.adp}. | |
986 | ||
987 | Then, again in @file{hello_4.adb}, invoke @key{Ada | Set main and | |
988 | Build}. You should get a @code{*compilation*} buffer containing | |
989 | something like (the directory paths will be different): | |
990 | ||
991 | @example | |
992 | cd c:/Examples/Example_4/Gnat_Project/ | |
993 | gnatmake -o hello_4 hello_4 -Phello_4.gpr -cargs -gnatq -gnatQ -bargs -largs | |
994 | gcc -c -g -gnatyt -gnatq -gnatQ -I- -gnatA c:\Examples\Example_4\Gnat_Project\hello_4.adb | |
995 | gcc -c -g -gnatyt -gnatq -gnatQ -I- -gnatA c:\Examples\Example_4\hello_pkg.adb | |
996 | hello_pkg.adb:2:08: keyword "body" expected here [see file name] | |
997 | gnatmake: "c:\examples\example_4\hello_pkg.adb" compilation error | |
998 | @end example | |
999 | ||
1000 | Compare the @code{gcc} options to the compiler output in @ref{Set | |
1001 | compiler options}; this shows that @file{hello_4.gpr} is being used to | |
1002 | set the compiler options. | |
1003 | ||
1004 | Fixing the error, linking and running the code proceed as in @ref{No | |
1005 | project files}. | |
1006 | ||
1007 | @node Moving Through Ada Code, Identifier completion, Compiling Examples, Top | |
00ce3714 GM |
1008 | @chapter Moving Through Ada Code |
1009 | @c ----------------------------------------------------------------------- | |
1010 | ||
11e52000 JB |
1011 | There are several easy to use commands to navigate through Ada code. All |
1012 | these functions are available through the Ada menu, and you can also | |
1013 | use the following key bindings or the command names. Some of these | |
1014 | menu entries are available only if the GNAT compiler is used, since | |
1015 | the implementation relies on the GNAT cross-referencing information. | |
00ce3714 GM |
1016 | |
1017 | @table @kbd | |
11e52000 | 1018 | @item M-C-e |
de803500 | 1019 | @findex ada-next-procedure |
2e78ad14 RS |
1020 | Move to the next function/procedure/task, which ever comes next |
1021 | (@code{ada-next-procedure}). | |
11e52000 | 1022 | @item M-C-a |
de803500 | 1023 | @findex ada-previous-procedure |
2e78ad14 RS |
1024 | Move to previous function/procedure/task |
1025 | (@code{ada-previous-procedure}). | |
1026 | @item M-x ada-next-package | |
de803500 | 1027 | @findex ada-next-package |
00ce3714 | 1028 | Move to next package. |
11e52000 JB |
1029 | @item M-x ada-previous-package |
1030 | @findex ada-previous-package | |
00ce3714 | 1031 | Move to previous package. |
2e78ad14 | 1032 | @item C-c C-a |
de803500 | 1033 | @findex ada-move-to-start |
2e78ad14 RS |
1034 | Move to matching start of @code{end} (@code{ada-move-to-start}). If |
1035 | point is at the end of a subprogram, this command jumps to the | |
1036 | corresponding @code{begin} if the user option | |
11e52000 JB |
1037 | @code{ada-move-to-declaration} is @code{nil} (default), otherwise it jumps to |
1038 | the subprogram declaration. | |
2e78ad14 | 1039 | @item C-c C-e |
de803500 | 1040 | @findex ada-move-to-end |
2e78ad14 RS |
1041 | Move point to end of current block (@code{ada-move-to-end}). |
1042 | @item C-c o | |
1043 | Switch between corresponding spec and body file | |
11e52000 JB |
1044 | (@code{ff-find-other-file}). If point is in a subprogram, position |
1045 | point on the corresponding declaration or body in the other file. | |
00ce3714 | 1046 | @item C-c c-d |
de803500 | 1047 | @findex ada-goto-declaration |
11e52000 JB |
1048 | Move from any reference to its declaration, for from a declaration to |
1049 | its body (for procedures, tasks, private and incomplete types). | |
2e78ad14 | 1050 | @item C-c C-r |
de803500 | 1051 | @findex ada-find-references |
11e52000 JB |
1052 | Runs the @file{gnatfind} command to search for all references to the |
1053 | identifier surrounding point (@code{ada-find-references}). Use | |
2e78ad14 RS |
1054 | @kbd{C-x `} (@code{next-error}) to visit each reference (as for |
1055 | compilation errors). | |
00ce3714 GM |
1056 | @end table |
1057 | ||
11e52000 JB |
1058 | If the @code{ada-xref-create-ali} variable is non-@code{nil}, Emacs |
1059 | will try to run GNAT for you whenever cross-reference information is | |
1060 | needed, and is older than the current source file. | |
00ce3714 | 1061 | |
11e52000 | 1062 | @node Identifier completion, Automatic Smart Indentation, Moving Through Ada Code, Top |
00ce3714 | 1063 | @chapter Identifier completion |
00ce3714 | 1064 | |
11e52000 JB |
1065 | Emacs and Ada mode provide two general ways for the completion of |
1066 | identifiers. This is an easy way to type faster: you just have to type | |
1067 | the first few letters of an identifiers, and then loop through all the | |
00ce3714 GM |
1068 | possible completions. |
1069 | ||
11e52000 JB |
1070 | The first method is general for Emacs. It works by parsing all open |
1071 | files for possible completions. | |
00ce3714 | 1072 | |
2e78ad14 RS |
1073 | For instance, if the words @samp{my_identifier}, @samp{my_subprogram} |
1074 | are the only words starting with @samp{my} in any of the opened files, | |
1075 | then you will have this scenario: | |
1076 | ||
11e52000 | 1077 | @example |
00ce3714 | 1078 | You type: my@key{M-/} |
2e78ad14 RS |
1079 | Emacs inserts: @samp{my_identifier} |
1080 | If you press @key{M-/} once again, Emacs replaces @samp{my_identifier} with | |
1081 | @samp{my_subprogram}. | |
1082 | Pressing @key{M-/} once more will bring you back to @samp{my_identifier}. | |
11e52000 | 1083 | @end example |
00ce3714 | 1084 | |
11e52000 | 1085 | This is a very fast way to do completion, and the casing of words will |
00ce3714 GM |
1086 | also be respected. |
1087 | ||
11e52000 JB |
1088 | The second method (@key{C-TAB}) is specific to Ada mode and the GNAT |
1089 | compiler. Emacs will search the cross-information for possible | |
1090 | completions. | |
00ce3714 | 1091 | |
11e52000 JB |
1092 | The main advantage is that this completion is more accurate: only |
1093 | existing identifier will be suggested. | |
00ce3714 | 1094 | |
11e52000 JB |
1095 | On the other hand, this completion is a little bit slower and requires |
1096 | that you have compiled your file at least once since you created that | |
00ce3714 GM |
1097 | identifier. |
1098 | ||
00ce3714 | 1099 | @table @kbd |
2e78ad14 | 1100 | @item C-@key{TAB} |
de803500 | 1101 | @findex ada-complete-identifier |
11e52000 | 1102 | Complete current identifier using cross-reference information. |
00ce3714 | 1103 | @item M-/ |
2e78ad14 | 1104 | Complete identifier using buffer information (not Ada-specific). |
00ce3714 GM |
1105 | @end table |
1106 | ||
11e52000 | 1107 | @node Automatic Smart Indentation, Formatting Parameter Lists, Identifier completion, Top |
00ce3714 | 1108 | @chapter Automatic Smart Indentation |
00ce3714 | 1109 | |
11e52000 JB |
1110 | Ada mode comes with a full set of rules for automatic indentation. You |
1111 | can also configure the indentation, via the following variables: | |
00ce3714 | 1112 | |
2e78ad14 RS |
1113 | @table @asis |
1114 | @item @code{ada-broken-indent} (default value: 2) | |
1115 | Number of columns to indent the continuation of a broken line. | |
00ce3714 | 1116 | |
2e78ad14 | 1117 | @item @code{ada-indent} (default value: 3) |
11e52000 | 1118 | Number of columns for default indentation. |
00ce3714 | 1119 | |
2e78ad14 RS |
1120 | @item @code{ada-indent-record-rel-type} (default value: 3) |
1121 | Indentation for @code{record} relative to @code{type} or @code{use}. | |
00ce3714 | 1122 | |
2e78ad14 RS |
1123 | @item @code{ada-indent-return} (default value: 0) |
1124 | Indentation for @code{return} relative to @code{function} (if | |
1125 | @code{ada-indent-return} is greater than 0), or the open parenthesis | |
11e52000 | 1126 | (if @code{ada-indent-return} is negative or 0). Note that in the second |
2e78ad14 RS |
1127 | case, when there is no open parenthesis, the indentation is done |
1128 | relative to @code{function} with the value of @code{ada-broken-indent}. | |
00ce3714 | 1129 | |
2e78ad14 RS |
1130 | @item @code{ada-label-indent} (default value: -4) |
1131 | Number of columns to indent a label. | |
00ce3714 | 1132 | |
2e78ad14 RS |
1133 | @item @code{ada-stmt-end-indent} (default value: 0) |
1134 | Number of columns to indent a statement @code{end} keyword on a separate line. | |
00ce3714 | 1135 | |
2e78ad14 RS |
1136 | @item @code{ada-when-indent} (default value: 3) |
1137 | Indentation for @code{when} relative to @code{exception} or @code{case}. | |
00ce3714 | 1138 | |
2e78ad14 RS |
1139 | @item @code{ada-indent-is-separate} (default value: t) |
1140 | Non-@code{nil} means indent @code{is separate} or @code{is abstract} if on a single line. | |
00ce3714 | 1141 | |
2e78ad14 RS |
1142 | @item @code{ada-indent-to-open-paren} (default value: t) |
1143 | Non-@code{nil} means indent according to the innermost open parenthesis. | |
00ce3714 | 1144 | |
11e52000 JB |
1145 | @item @code{ada-indent-after-return} (default value: t) |
1146 | Non-@code{nil} means that the current line will also be re-indented | |
1147 | before inserting a newline, when you press @key{RET}. | |
00ce3714 GM |
1148 | @end table |
1149 | ||
11e52000 JB |
1150 | Most of the time, the indentation will be automatic, i.e when you |
1151 | press @key{RET}, the cursor will move to the correct column on the | |
00ce3714 GM |
1152 | next line. |
1153 | ||
11e52000 | 1154 | You can also indent single lines, or the current region, with @key{TAB}. |
00ce3714 | 1155 | |
2e78ad14 RS |
1156 | Another mode of indentation exists that helps you to set up your |
1157 | indentation scheme. If you press @kbd{C-c @key{TAB}}, Ada mode will do | |
1158 | the following: | |
1159 | ||
00ce3714 | 1160 | @itemize @bullet |
2e78ad14 RS |
1161 | @item |
1162 | Reindent the current line, as @key{TAB} would do. | |
1163 | @item | |
1164 | Temporarily move the cursor to a reference line, i.e., the line that | |
1165 | was used to calculate the current indentation. | |
1166 | @item | |
11e52000 JB |
1167 | Display in the message window the name of the variable that provided |
1168 | the offset for the indentation. | |
00ce3714 GM |
1169 | @end itemize |
1170 | ||
1171 | The exact indentation of the current line is the same as the one for the | |
1172 | reference line, plus an offset given by the variable. | |
1173 | ||
00ce3714 | 1174 | @table @kbd |
2e78ad14 RS |
1175 | @item @key{TAB} |
1176 | Indent the current line or the current region. | |
718fb8a1 | 1177 | @item C-M-\ |
11e52000 | 1178 | Indent lines in the current region. |
2e78ad14 | 1179 | @item C-c @key{TAB} |
11e52000 | 1180 | Indent the current line and display the name of the variable used for |
00ce3714 GM |
1181 | indentation. |
1182 | @end table | |
1183 | ||
00ce3714 GM |
1184 | @node Formatting Parameter Lists, Automatic Casing, Automatic Smart Indentation, Top |
1185 | @chapter Formatting Parameter Lists | |
00ce3714 GM |
1186 | |
1187 | @table @kbd | |
2e78ad14 | 1188 | @item C-c C-f |
de803500 | 1189 | @findex ada-format-paramlist |
2e78ad14 | 1190 | Format the parameter list (@code{ada-format-paramlist}). |
00ce3714 GM |
1191 | @end table |
1192 | ||
11e52000 JB |
1193 | This aligns the declarations on the colon (@samp{:}) separating |
1194 | argument names and argument types, and aligns the @code{in}, | |
1195 | @code{out} and @code{in out} keywords. | |
1196 | ||
00ce3714 GM |
1197 | @node Automatic Casing, Statement Templates, Formatting Parameter Lists, Top |
1198 | @chapter Automatic Casing | |
00ce3714 | 1199 | |
11e52000 JB |
1200 | Casing of identifiers, attributes and keywords is automatically |
1201 | performed while typing when the variable @code{ada-auto-case} is set. | |
1202 | Every time you press a word separator, the previous word is | |
00ce3714 GM |
1203 | automatically cased. |
1204 | ||
11e52000 JB |
1205 | You can customize the automatic casing differently for keywords, |
1206 | attributes and identifiers. The relevant variables are the following: | |
1207 | @code{ada-case-keyword}, @code{ada-case-attribute} and | |
00ce3714 GM |
1208 | @code{ada-case-identifier}. |
1209 | ||
1210 | All these variables can have one of the following values: | |
1211 | ||
2e78ad14 | 1212 | @table @code |
00ce3714 | 1213 | @item downcase-word |
11e52000 JB |
1214 | The word will be lowercase. For instance @code{My_vARIable} is |
1215 | converted to @code{my_variable}. | |
00ce3714 GM |
1216 | |
1217 | @item upcase-word | |
11e52000 JB |
1218 | The word will be uppercase. For instance @code{My_vARIable} is |
1219 | converted to @code{MY_VARIABLE}. | |
00ce3714 GM |
1220 | |
1221 | @item ada-capitalize-word | |
11e52000 JB |
1222 | The first letter and each letter following an underscore (@samp{_}) |
1223 | are uppercase, others are lowercase. For instance @code{My_vARIable} | |
1224 | is converted to @code{My_Variable}. | |
00ce3714 GM |
1225 | |
1226 | @item ada-loose-case-word | |
11e52000 JB |
1227 | Characters after an underscore @samp{_} character are uppercase, |
1228 | others are not modified. For instance @code{My_vARIable} is converted | |
1229 | to @code{My_VARIable}. | |
00ce3714 GM |
1230 | @end table |
1231 | ||
11e52000 JB |
1232 | Ada mode allows you to define exceptions to these rules, in a file |
1233 | specified by the variable variable @code{ada-case-exception-file} | |
1234 | (default @file{~/.emacs_case_exceptions}). Each line in this file | |
1235 | specifies the casing of one word or word fragment. Comments may be | |
1236 | included, separated from the word by a space. | |
00ce3714 | 1237 | |
11e52000 JB |
1238 | If the word starts with an asterisk (@key{*}), it defines the casing |
1239 | af a word fragemnt (or ``substring''); part of a word between two | |
1240 | underscores or word boundary. | |
00ce3714 | 1241 | |
11e52000 | 1242 | For example: |
00ce3714 GM |
1243 | |
1244 | @example | |
1245 | DOD Department of Defense | |
11e52000 | 1246 | *IO |
00ce3714 GM |
1247 | GNAT The GNAT compiler from Ada Core Technologies |
1248 | @end example | |
1249 | ||
11e52000 JB |
1250 | The word fragment @code{*IO} applies to any word containing ``_io''; |
1251 | @code{Text_IO}, @code{Hardware_IO}, etc. | |
00ce3714 | 1252 | |
de803500 | 1253 | @findex ada-create-case-exception |
11e52000 JB |
1254 | There are two ways to add new items to this file: you can simply edit |
1255 | it as you would edit any text file. Or you can position point on the | |
1256 | word you want to add, and select menu @samp{Ada | Edit | Create Case | |
1257 | Exception}, or press @kbd{C-c C-y} (@code{ada-create-case-exception}). | |
1258 | The word will automatically be added to the current list of exceptions | |
1259 | and to the file. | |
1260 | ||
1261 | To define a word fragment case exception, select the word fragment, | |
1262 | then select menu @samp{Ada | Edit | Create Case Exception Substring}. | |
1263 | ||
1264 | It is sometimes useful to have multiple exception files around (for | |
1265 | instance, one could be the standard Ada acronyms, the second some | |
1266 | company specific exceptions, and the last one some project specific | |
1267 | exceptions). If you set up the variable @code{ada-case-exception-file} | |
1268 | as a list of files, each of them will be parsed and used in your emacs | |
1269 | session. However, when you save a new exception through the menu, as | |
1270 | described above, the new exception will be added to the first file in | |
1271 | the list. | |
2e78ad14 | 1272 | |
00ce3714 GM |
1273 | @table @kbd |
1274 | @item C-c C-b | |
de803500 EZ |
1275 | @findex ada-adjust-case-buffer |
1276 | Adjust case in the whole buffer (@code{ada-adjust-case-buffer}). | |
00ce3714 GM |
1277 | @item C-c C-y |
1278 | Create a new entry in the exception dictionary, with the word under | |
de803500 | 1279 | the cursor (@code{ada-create-case-exception}) |
00ce3714 | 1280 | @item C-c C-t |
de803500 | 1281 | @findex ada-case-read-exceptions |
00ce3714 | 1282 | Rereads the exception dictionary from the file |
de803500 | 1283 | @code{ada-case-exception-file} (@code{ada-case-read-exceptions}). |
00ce3714 GM |
1284 | @end table |
1285 | ||
00ce3714 GM |
1286 | @node Statement Templates, Comment Handling, Automatic Casing, Top |
1287 | @chapter Statement Templates | |
00ce3714 | 1288 | |
11e52000 JB |
1289 | Templates are defined for most Ada statements, using the Emacs |
1290 | ``skeleton'' package. They can be inserted in the buffer using the | |
1291 | following commands: | |
00ce3714 GM |
1292 | |
1293 | @table @kbd | |
1294 | @item C-c t b | |
de803500 EZ |
1295 | @findex ada-exception-block |
1296 | exception Block (@code{ada-exception-block}). | |
00ce3714 | 1297 | @item C-c t c |
de803500 EZ |
1298 | @findex ada-case |
1299 | case (@code{ada-case}). | |
00ce3714 | 1300 | @item C-c t d |
de803500 EZ |
1301 | @findex ada-declare-block |
1302 | declare Block (@code{ada-declare-block}). | |
00ce3714 | 1303 | @item C-c t e |
de803500 EZ |
1304 | @findex ada-else |
1305 | else (@code{ada-else}). | |
00ce3714 | 1306 | @item C-c t f |
de803500 EZ |
1307 | @findex ada-for-loop |
1308 | for Loop (@code{ada-for-loop}). | |
00ce3714 | 1309 | @item C-c t h |
de803500 EZ |
1310 | @findex ada-header |
1311 | Header (@code{ada-header}). | |
00ce3714 | 1312 | @item C-c t i |
de803500 EZ |
1313 | @findex ada-if |
1314 | if (@code{ada-if}). | |
00ce3714 | 1315 | @item C-c t k |
de803500 EZ |
1316 | @findex ada-package-body |
1317 | package Body (@code{ada-package-body}). | |
00ce3714 | 1318 | @item C-c t l |
de803500 EZ |
1319 | @findex ada-loop |
1320 | loop (@code{ada-loop}). | |
1321 | @item C-c p | |
1322 | @findex ada-subprogram-body | |
1323 | subprogram body (@code{ada-subprogram-body}). | |
00ce3714 | 1324 | @item C-c t t |
de803500 EZ |
1325 | @findex ada-task-body |
1326 | task Body (@code{ada-task-body}). | |
00ce3714 | 1327 | @item C-c t w |
de803500 EZ |
1328 | @findex ada-while |
1329 | while Loop (@code{ada-while}). | |
00ce3714 | 1330 | @item C-c t u |
de803500 EZ |
1331 | @findex ada-use |
1332 | use (@code{ada-use}). | |
00ce3714 | 1333 | @item C-c t x |
de803500 EZ |
1334 | @findex ada-exit |
1335 | exit (@code{ada-exit}). | |
00ce3714 | 1336 | @item C-c t C-a |
de803500 EZ |
1337 | @findex ada-array |
1338 | array (@code{ada-array}). | |
00ce3714 | 1339 | @item C-c t C-e |
de803500 EZ |
1340 | @findex ada-elsif |
1341 | elsif (@code{ada-elsif}). | |
00ce3714 | 1342 | @item C-c t C-f |
de803500 EZ |
1343 | @findex ada-function-spec |
1344 | function Spec (@code{ada-function-spec}). | |
00ce3714 | 1345 | @item C-c t C-k |
de803500 EZ |
1346 | @findex ada-package-spec |
1347 | package Spec (@code{ada-package-spec}). | |
00ce3714 | 1348 | @item C-c t C-p |
de803500 EZ |
1349 | @findex ada-procedure-spec |
1350 | procedure Spec (@code{ada-package-spec}. | |
00ce3714 | 1351 | @item C-c t C-r |
de803500 EZ |
1352 | @findex ada-record |
1353 | record (@code{ada-record}). | |
00ce3714 | 1354 | @item C-c t C-s |
de803500 EZ |
1355 | @findex ada-subtype |
1356 | subtype (@code{ada-subtype}). | |
00ce3714 | 1357 | @item C-c t C-t |
de803500 EZ |
1358 | @findex ada-task-spec |
1359 | task Spec (@code{ada-task-spec}). | |
00ce3714 | 1360 | @item C-c t C-u |
de803500 EZ |
1361 | @findex ada-with |
1362 | with (@code{ada-with}). | |
00ce3714 | 1363 | @item C-c t C-v |
de803500 EZ |
1364 | @findex ada-private |
1365 | private (@code{ada-private}). | |
00ce3714 | 1366 | @item C-c t C-w |
de803500 EZ |
1367 | @findex ada-when |
1368 | when (@code{ada-when}). | |
00ce3714 | 1369 | @item C-c t C-x |
de803500 EZ |
1370 | @findex ada-exception |
1371 | exception (@code{ada-exception}). | |
00ce3714 | 1372 | @item C-c t C-y |
de803500 EZ |
1373 | @findex ada-type |
1374 | type (@code{ada-type}). | |
00ce3714 GM |
1375 | @end table |
1376 | ||
84247bb5 | 1377 | @node Comment Handling, GNU Free Documentation License, Statement Templates, Top |
00ce3714 | 1378 | @chapter Comment Handling |
00ce3714 GM |
1379 | |
1380 | By default, comment lines get indented like Ada code. There are a few | |
1381 | additional functions to handle comments: | |
1382 | ||
00ce3714 GM |
1383 | @table @kbd |
1384 | @item M-; | |
1385 | Start a comment in default column. | |
1386 | @item M-j | |
1387 | Continue comment on next line. | |
2e78ad14 | 1388 | @item C-c ; |
00ce3714 GM |
1389 | Comment the selected region (add -- at the beginning of lines). |
1390 | @item C-c : | |
1391 | Uncomment the selected region | |
1392 | @item M-q | |
1393 | autofill the current comment. | |
1394 | @end table | |
1395 | ||
84247bb5 CY |
1396 | @node GNU Free Documentation License, Index, Comment Handling, Top |
1397 | @appendix GNU Free Documentation License | |
1398 | @include doclicense.texi | |
1399 | ||
1400 | @node Index, , GNU Free Documentation License, Top | |
de803500 EZ |
1401 | @unnumbered Index |
1402 | ||
1403 | @printindex fn | |
1404 | ||
00ce3714 GM |
1405 | @contents |
1406 | @bye | |
ab5796a9 MB |
1407 | |
1408 | @ignore | |
1409 | arch-tag: 68cf0d8a-55cc-4190-a28d-4984fa56ed1e | |
1410 | @end ignore |