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