diff options
Diffstat (limited to 'doc/misc/ada-mode.texi')
| -rw-r--r-- | doc/misc/ada-mode.texi | 1410 |
1 files changed, 1410 insertions, 0 deletions
diff --git a/doc/misc/ada-mode.texi b/doc/misc/ada-mode.texi new file mode 100644 index 00000000000..8f78d869343 --- /dev/null +++ b/doc/misc/ada-mode.texi @@ -0,0 +1,1410 @@ +\input texinfo @c -*-texinfo-*- +@setfilename ../../info/ada-mode +@settitle Ada Mode + +@copying +Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004, +2005, 2006, 2007 Free Software Foundation, Inc. + +@quotation +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.2 or +any later version published by the Free Software Foundation; with the +Invariant Sections being ``The GNU Manifesto'', ``Distribution'' and +``GNU GENERAL PUBLIC LICENSE'', with the Front-Cover texts being ``A GNU +Manual'', and with the Back-Cover Texts as in (a) below. A copy of the +license is included in the section entitled ``GNU Free Documentation +License'' in the Emacs manual. + +(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify +this GNU Manual, like GNU software. Copies published by the Free +Software Foundation raise funds for GNU development.'' + +This document is part of a collection distributed under the GNU Free +Documentation License. If you want to distribute this document +separately from the collection, you can do so by adding a copy of the +license to the document, as described in section 6 of the license. +@end quotation +@end copying + +@dircategory Emacs +@direntry +* Ada mode: (ada-mode). Emacs mode for editing and compiling Ada code. +@end direntry + +@titlepage +@sp 10 +@title{Ada Mode} +@sp 2 +@subtitle An Emacs major mode for programming in Ada +@subtitle Ada Mode Version 3.7 +@sp 2 +@page +@vskip 0pt plus 1filll +@insertcopying +@end titlepage + +@c fixme; title page doesn't show up in ada-mode.info; why bother with +@c it? + +@node Top, Overview, (dir), (dir) + +@menu +* Overview:: +* Installation:: Installing Ada mode on your system +* Customization:: Setting up Ada mode to your taste +* Compiling Executing:: Working with your application within Emacs +* Project files:: Describing the organization of your project +* Compiling Examples:: A small tutorial +* Moving Through Ada Code:: Moving easily through Ada sources +* Identifier completion:: Finishing words automatically +* Automatic Smart Indentation:: Indenting your code automatically as you type +* Formatting Parameter Lists:: Formatting subprograms' parameter lists + automatically +* Automatic Casing:: Adjusting the case of words automatically +* Statement Templates:: Inserting code templates +* Comment Handling:: Reformatting comments easily +* GNU Free Documentation License:: The license for this documentation. +* Index:: +@end menu + + +@node Overview, Installation, Top, Top +@chapter Overview + +The Emacs mode for programming in Ada helps the user in understanding +existing code and facilitates writing new code. + +When the Gnu Ada compiler GNAT is used, the cross-reference +information output by the compiler is used to provide powerful code +navigation (jump to definition, find all uses, etc). + +When you open a file with a file extension of @file{.ads} or +@file{.adb}, Emacs will automatically load and activate Ada mode. + +Ada mode works without any customization, if you are using the GNAT +compiler (@url{https://libre2.adacore.com/}) and the GNAT default +naming convention. + +You must customize a few things if you are using a different compiler +or file naming convention; @xref{Other compiler}, @xref{Non-standard +file names}. + +In addition, you may want to customize the indentation, +capitalization, and other things; @xref{Other customization}. + +Finally, for large Ada projects, you will want to set up an Emacs +Ada mode project file for each project; @xref{Project files}. Note +that these are different from the GNAT project files used by gnatmake +and other GNAT commands. + +See the Emacs info manual, section 'Running Debuggers Under Emacs', +for general information on debugging. + +@node Installation, Customization, Overview, Top +@chapter Installation + +Ada mode is part of the standard Emacs distribution; if you use that, +no files need to be installed. + +Ada mode is also available as a separate distribution, from the Emacs +Ada mode website +@uref{http://stephe-leake.org/emacs/ada-mode/emacs-ada-mode.html}. The +separate distribution may be more recent. + +For installing the separate distribution, see the @file{README} file +in the distribution. + +To see what version of Ada mode you have installed, do @key{M-x +ada-mode-version}. + +The following files are provided with the Ada mode distribution: + +@itemize @bullet + +@item +@file{ada-mode.el}: The main file for Ada mode, providing indentation, +formatting of parameter lists, moving through code, comment handling +and automatic casing. + +@item +@file{ada-prj.el}: GUI editing of Ada mode project files, using Emacs +widgets. + +@item +@file{ada-stmt.el}: Ada statement templates. + +@item +@file{ada-xref.el}: GNAT cross-references, completion of identifiers, +and compilation. Also provides project files (which are not +GNAT-specific). + +@end itemize + +@node Customization, Compiling Executing, Installation, Top +@chapter Customizing Ada mode + +Here we assume you are familiar with setting variables in Emacs, +either thru 'customize' or in elisp (in your @file{.emacs} file). For +a basic introduction to customize, elisp, and Emacs in general, see +the tutorial in +@iftex +@cite{The GNU Emacs Manual}. +@end iftex +@ifhtml +@cite{The GNU Emacs Manual}. +@end ifhtml +@ifinfo +@ref{Top, , The GNU Emacs Manual, emacs, The GNU Emacs Manual}. +@end ifinfo + +These global Emacs settings are strongly recommended (put them in your +.emacs): + +@example +(global-font-lock-mode t) +(transient-mark-mode t) +@end example + +@samp{(global-font-lock-mode t)} turns on syntax +highlighting for all buffers (it is off by default because it may be +too slow for some machines). + +@samp{(transient-mark-mode t)} highlights selected text. + +See the Emacs help for each of these variables for more information. + +@menu +* Non-standard file names:: +* Other compiler:: +* Other customization:: +@end menu + +@node Non-standard file names, Other compiler, Customization, Customization +@section Non-standard file names + +By default, Ada mode is configured to use the GNAT file naming +convention, where file names are a simple modification of the Ada +names, and the extension for specs and bodies are +@samp{.ads} and @samp{.adb}, respectively. + +Ada mode uses the file extentions to allow moving from a package body +to the corresponding spec and back. + +Ada mode supports a list of alternative file extensions for specs and bodies. + +For instance, if your spec and bodies files are called +@file{@var{unit}_s.ada} and @file{@var{unit}_b.ada}, respectively, you +can add the following to your @file{.emacs} file: + +@example +(ada-add-extensions "_s.ada" "_b.ada") +@end example + +You can define additional extensions: + +@example +(ada-add-extensions ".ads" "_b.ada") +(ada-add-extensions ".ads" ".body") +@end example + +This means that whenever Ada mode looks for the body for a file +whose extension is @file{.ads}, it will take the first available file +that ends with either @file{.adb}, @file{_b.ada} or +@file{.body}. + +Simililarly, if Ada mode is looking for a spec, it will look for +@file{.ads} or @file{_s.ada}. + +If the filename is not derived from the Ada name following the GNAT +convention, things are a little more complicated. You then need to +rewrite the function @code{ada-make-filename-from-adaname}. Doing that +is beyond the scope of this manual; see the current definitions in +@file{ada-mode.el} and @file{ada-xref.el} for examples. + +@node Other compiler, Other customization, Non-standard file names, Customization +@section Other compiler + +By default, Ada mode is configured to use the Gnu Ada compiler GNAT. + +To use a different Ada compiler, you must specify the command lines +used to run that compiler, either in lisp variables or in Emacs +Ada mode project files. See @ref{Project file variables} for the list +of project variables, and the corresponding lisp variables. + +@node Other customization, , Other compiler, Customization +@section Other customization + +All user-settable Ada mode variables can be set via the menu +@samp{Ada | Customize}. Click on the @samp{Help} button there for help +on using customize. + +To modify a specific variable, you can directly call the function +@code{customize-variable}; just type @kbd{M-x customize-variable +@key{RET} @var{variable-name} @key{RET}}). + +Alternately, you can specify variable settings in the Emacs +configuration file, @file{.emacs}. This file is coded in Emacs lisp, +and the syntax to set a variable is the following: +@example +(setq variable-name value) +@end example + +@node Compiling Executing, Project files, Customization, Top +@chapter Compiling Executing + +Ada projects can be compiled, linked, and executed using commands on +the Ada menu. All of these commands can be customized via a project +file (@pxref{Project files}), but the defaults are sufficient for using +the GNAT compiler for simple projects (single files, or several files +in a single directory). + +Even when no project file is used, the GUI project editor (menu +@key{Ada | Project | Edit}) shows the settings of the various project +file variables referenced here. + +@menu +* Compile commands:: +* Compiler errors:: +@end menu + +@node Compile commands, Compiler errors, Compiling Executing, Compiling Executing +@section Compile commands + +Here are the commands for building and using an Ada project, as +listed in the Ada menu. + +In multi-file projects, there must be one file that is the main +program. That is given by the @code{main_unit} project file variable; +it defaults to the current file if not yet set, but is also set by the +``set main and build'' command. + +@table @code + +@item Check file +Compiles the current file in syntax check mode, by running +@code{check_cmd} defined in the current project file. This typically +runs faster than full compile mode, speeding up finding and fixing +compilation errors. + +This sets @code{main_unit} only if it has not been set yet. + +@item Compile file +Compiles the current file, by running @code{comp_cmd} from the current +project file. + +This does not set @code{main_unit}. + +@item Set main and Build +Sets @code{main_unit} to the current file, then executes the Build +command. + +@item Show main +Display @code{main_unit} in the message buffer. + +@item Build +Compiles all obsolete units of the current @code{main_unit}, and links +@code{main_unit}, by running @code{make_cmd} from the current project. + +This sets @code{main_unit} only if it has not been set yet. + +@item Run +Executes the main program in a shell, displayed in a separate Emacs +buffer. This runs @code{run_cmd} from the current project. The +execution buffer allows for interactive input/output. + +To modify the run command, in particular to provide or change the +command line arguments, type @key{C-u} before invoking the command. + +This command is not available for a cross-compilation toolchain. + +@end table +It is important when using these commands to understand how +@code{main_unit} is used and changed. + +Build runs 'gnatmake' on the main unit. During a typical edit/compile +session, this is the only command you need to invoke, which is why it +is bound to @key{C-c C-c}. It will compile all files needed by the +main unit, and display compilation errors in any of them. + +Note that Build can be invoked from any Ada buffer; typically you will +be fixing errors in files other than the main, but you don't have to +switch back to the main to invoke the compiler again. + +Novices and students typically work on single-file Ada projects. In +this case, @key{C-c C-m} will normally be the only command needed; it +will build the current file, rather than the last-built main. + +There are three ways to change @code{main_unit}: + +@enumerate +@item +Invoke @key{Ada | Set main and Build}, which sets @code{main_unit} to +the current file. + +@item +Invoke @key{Ada | Project | Edit}, edit @code{main_unit} and +@code{main}, and click @key{[save]} + +@item +Invoke @key{Ada | Project | Load}, and load a project file that specifies @code{main_unit} + +@end enumerate + +@node Compiler errors, , Compile commands, Compiling Executing +@section Compiler errors + +The @code{Check file}, @code{Compile file}, and @code{Build} commands +all place compilation errors in a separate buffer named +@code{*compilation*}. + +Each line in this buffer will become active: you can simply click on +it with the middle button of the mouse, or move point to it and press +@key{RET}. Emacs will then display the relevant source file and put +point on the line and column where the error was found. + +You can also press the @kbd{C-x `} key (@code{next-error}), and Emacs +will jump to the first error. If you press that key again, it will +move you to the second error, and so on. + +Some error messages might also include references to other files. These +references are also clickable in the same way, or put point after the +line number and press @key{RET}. + +@node Project files, Compiling Examples, Compiling Executing, Top +@chapter Project files + +An Emacs Ada mode project file specifies what directories hold sources +for your project, and allows you to customize the compilation commands +and other things on a per-project basis. + +Note that Ada mode project files @samp{*.adp} are different than GNAT +compiler project files @samp{*.gpr}. + +@menu +* Project File Overview:: +* GUI Editor:: +* Project file variables:: +@end menu + +@node Project File Overview, GUI Editor, Project files, Project files +@section Project File Overview + +Project files have a simple syntax; they may be edited directly. Each +line specifies a project variable name and its value, separated by ``='': +@example +src_dir=/Projects/my_project/src_1 +src_dir=/Projects/my_project/src_2 +@end example + +Some variables (like @code{src_dir}) are lists; multiple occurances +are concatenated. + +There must be no space between the variable name and ``='', and no +trailing spaces. + +Alternately, a GUI editor for project files is available (@pxref{GUI +Editor}). It uses Emacs widgets, similar to Emacs customize. + +The GUI editor also provides a convenient way to view current project +settings, if they have been modified using menu commands rather than +by editing the project file. + +After the first Ada mode build command is invoked, there is always a +current project file, given by the lisp variable +@code{ada-prj-default-project-file}. Currently, the only way to show +the current project file is to invoke the GUI editor. + +To find the project file the first time, Ada mode uses the following +search algorithm: + +@itemize @bullet +@item +If @code{ada-prj-default-project-file} is set, use that. + +@item +Otherwise, search for a file in the current directory with +the same base name as the Ada file, but extension given by +@code{ada-prj-file-extension} (default @code{".adp"}). + +@item +If not found, search for @file{*.adp} in the current directory; if +several are found, prompt the user to select one. + +@item +If none are found, use @file{default.adp} in the current directory (even +if it does not exist). + +@end itemize + +This algorithm always sets @code{ada-prj-default-project-file}, even +when the file does not actually exist. + +To change the project file before or after the first one is found, +invoke @key{Ada | Project | Load ...}. + +Or, in lisp, evaluate @code{ada-set-default-project-file "/path/file.adp"}. +This sets @code{ada-prj-default-project-file}, and reads the project file. + +@node GUI Editor, Project file variables, Project File Overview, Project files +@section GUI Editor + +The project file editor is invoked with the menu @samp{Ada | Projects +| Edit}. + +Once in the buffer for editing the project file, you can save your +modification using the @samp{[save]} button at the bottom of the +buffer, or the @kbd{C-x C-s} binding. To cancel your modifications, +kill the buffer or click on the @samp{[cancel]} button. + +@node Project file variables, , GUI Editor, Project files +@section Project file variables + +The following variables can be defined in a project file; some can +also be defined in lisp variables. + +To set a project variable that is a list, specify each element of the +list on a separate line in the project file. + +Any project variable can be referenced in other project variables, +using a shell-like notation. For instance, if the variable +@code{comp_cmd} contains @code{$@{comp_opt@}}, the value of the +@code{comp_opt} variable will be substituted when @code{comp_cmd} is +used. + +Most project variables have defaults that can be changed by setting +lisp variables; the table below identifies the lisp variable for each +project variable. Lisp variables corresponding to project variables +that are lists are lisp lists. + +Here is the list of variables. In the default values, the current +directory @code{"."} is the project file directory. + +@c defined in ada-xref-set-default-prj-values; same order here +@table @asis +@item @code{build_dir} [default: @code{"."}] +The compile commands will be issued in this directory. + +@item @code{src_dir} [default: @code{"."}] +A list of directories to search for source files, both for compile +commands and source navigation. + +@item @code{obj_dir} [default: @code{"."}] +A list of directories to search for library files. Ada mode searches +this list for the @samp{.ali} files generated by GNAT that contain +cross-reference information. + +The compiler commands must place the @samp{.ali} files in one of these +directories; the default commands do that. + +@item @code{casing} [default: @code{("~/.emacs_case_exceptions")} +List of files containing casing exceptions. See the help on +@code{ada-case-exception-file} for more info. +@c FIXME: section on case exceptions + +Lisp variable: @code{ada-case-exception-file}. + +@item @code{comp_opt} [default: @code{"-gnatq -gnatQ"}] +Holds user compiler options; used in the default compile commands. The +default value tells gnatmake to generate library files for +cross-referencing even when there are errors. + +If source code for the project is in multiple directories, the +appropriate compiler options must be added here. @ref{Set source +search path} for examples of this. Alternately, GNAT project files may +be used; @ref{Use GNAT project file}. + +Lisp variable: @code{ada-prj-default-comp-opt}. + +@item @code{bind_opt} [default: @code{""}] +Holds user binder options; used in the default build commands. + +Lisp variable: @code{ada-prj-default-bind-opt}. + +@item @code{link_opt} [default: @code{""}] +Holds user linker options; used in the default build commands. + +Lisp variable: @code{ada-prj-default-link-opt}. + +@item @code{gnatmake_opt} [default: @code{"-g"}] +Holds user gnatmake options; used in the default build commands. + +If a GNAT project file is used (for example @file{project.gpr}), this +option should be set to @code{-Pproject.gpr}. + +Lisp variable: @code{ada-prj-default-gnatmake-opt}. + +@item @code{gnatfind_opt} [default: @code{"-rf"}] +Holds user gnatfind options; used in the default find commands. + +Lisp variable: @code{ada-prj-gnatfind-switches}. + +@item @code{main} [default: current file] +Specifies the name of the executable file for the project; used in the +default build commands. + +@item @code{main_unit} [default: current Ada unit] +Specifies the name of the main Ada unit for the project; used in the +default build commands. + +@item @code{cross_prefix} [default: @code{""}] +Name of target machine in a cross-compilation environment. Used in +default compile and build commands. + +@item @code{remote_machine} [default: @code{""}] +Name of the machine to log into before issuing the compile and build +commands. If this variable is empty, the command will be run on the +local machine. + +@item @code{comp_cmd} [default: @code{"$@{cross_prefix@}gnatmake -u -c $@{gnatmake_opt@} $@{full_current@} -cargs $@{comp_opt@}"}] +Command used to compile a single file. +The name of the file is substituted for @code{full_current}. + +Lisp variable: @code{ada-prj-default-comp-cmd}. + +@item @code{check_cmd} [default: @code{"$@{cross_prefix@}gnatmake -u -c -gnatc $@{gnatmake_opt@} $@{full_current@} -cargs $@{comp_opt@}"}] +Command used to syntax check a single file. +The name of the file is substituted for @code{full_current}. + +Lisp variable: @code{ada-prj-default-check-cmd} + +@item @code{make_cmd} [default: @code{"$@{cross_prefix@}gnatmake -o $@{main@} $@{main_unit@} $@{gnatmake_opt@} -cargs $@{comp_opt@} -bargs $@{bind_opt@} -largs $@{link_opt@}"}] +Command used to build the application. + +Lisp variable: @code{ada-prj-default-make-cmd}. + +@item @code{run_cmd} [default: @code{"./$@{main@}"}] +Command used to run the application. + +@item @code{debug_pre_cmd} [default: @code{"cd $@{build_dir@}"}] +Command executed before @code{debug_cmd}. + +@item @code{debug_cmd} [default: @code{"$@{cross_prefix@}gdb $@{main@}"}] +Command used to debug the application + +Lisp variable: @code{ada-prj-default-debugger}. + +@item @code{debug_post_cmd} [default: @code{""}] +Command executed after @code{debug_cmd}. + +@end table + +@node Compiling Examples, Moving Through Ada Code, Project files, Top +@chapter Compiling Examples + +We present several small projects, and walk thru the process of +compiling, linking, and running them. + +The first example illustrates more Ada mode features than the others; +you should work thru that example before doing the others. + +All of these examples assume you are using GNAT. + +The source for these examples is available on the Emacs Ada mode +website mentioned in @xref{Installation}. + +@menu +* No project files:: Just menus +* Set compiler options:: A basic Ada mode project file +* Set source search path:: Source in multiple directories +* Use GNAT project file:: +@end menu + +@node No project files, Set compiler options, Compiling Examples, Compiling Examples +@section No project files +This example uses no project files. + +First, create a directory @file{Example_1}, containing: + +@file{hello.adb}: + +@example +with Ada.Text_IO; +procedure Hello +is begin + Put_Line("Hello from hello.adb"); +end Hello; +@end example + +Yes, this is missing ``use Ada.Text_IO;'' - we want to demonstrate +compiler error handling. + +@file{hello_2.adb}: + +@example +with Hello_Pkg; +procedure Hello_2 +is begin + Hello_Pkg.Say_Hello; +end Hello_2; +@end example + +@file{hello_pkg.ads}: + +@example +package Hello_Pkg is + procedure Say_Hello; +end Hello_Pkg; +@end example + +@file{hello_pkg.adb}: + +@example +with Ada.Text_IO; +package Hello_Pkg is + procedure Say_Hello + is begin + Ada.Text_IO.Put_Line ("Hello from hello_pkg.adb"); + end Say_Hello; +end Hello_Pkg; +@end example + +Yes, this is missing the keyword @code{body}; another compiler error +example. + +In buffer @file{hello.adb}, invoke @key{Ada | Check file}. You should +get a @code{*compilation*} buffer containing something like (the +directory paths will be different): + +@example +cd c:/Examples/Example_1/ +gnatmake -u -c -gnatc -g c:/Examples/Example_1/hello.adb -cargs -gnatq -gnatQ +gcc -c -Ic:/Examples/Example_1/ -gnatc -g -gnatq -gnatQ -I- c:/Examples/Example_1/hello.adb +hello.adb:4:04: "Put_Line" is not visible +hello.adb:4:04: non-visible declaration at a-textio.ads:264 +hello.adb:4:04: non-visible declaration at a-textio.ads:260 +gnatmake: "c:/Examples/Example_1/hello.adb" compilation error +@end example + +If you have enabled font-lock, the lines with actual errors (starting +with @file{hello.adb}) are highlighted, with the file name in red. + +Now type @key{C-x `} (on a PC keyboard, @key{`} is next to @key{1}). +Or you can click the middle mouse button on the first error line. The +compilation buffer scrolls to put the first error on the top line, and +point is put at the place of the error in the @file{hello.adb} buffer. + +To fix the error, change the line to be + +@example + Ada.Text_IO.Put_Line ("hello from hello.adb"): +@end example + +Now invoke @key{Ada | Show main}; this displays @file{Ada mode main_unit: hello}. + +Now (in buffer @file{hello.adb}), invoke @key{Ada | Build}. You are +prompted to save the file (if you haven't already). Then the +compilation buffer is displayed again, containing: + +@example +cd c:/Examples/Example_1/ +gnatmake -o hello hello -g -cargs -gnatq -gnatQ -bargs -largs +gcc -c -g -gnatq -gnatQ hello.adb +gnatbind -x hello.ali +gnatlink hello.ali -o hello.exe -g +@end example + +The compilation has succeeded without errors; @file{hello.exe} now +exists in the same directory as @file{hello.adb}. + +Now invoke @key{Ada | Run}. A @file{*run*} buffer is displayed, +containing + +@example +Hello from hello.adb + +Process run finished +@end example + +That completes the first part of this example. + +Now we will compile a multi-file project. Open the file +@file{hello_2.adb}, and invoke @key{Ada | Set main and Build}. This +finds an error in @file{hello_pkg.adb}: + +@example +cd c:/Examples/Example_1/ +gnatmake -o hello_2 hello_2 -g -cargs -gnatq -gnatQ -bargs -largs +gcc -c -g -gnatq -gnatQ hello_pkg.adb +hello_pkg.adb:2:08: keyword "body" expected here [see file name] +gnatmake: "hello_pkg.adb" compilation error +@end example + +This demonstrates that gnatmake finds the files needed by the main +program. However, it cannot find files in a different directory, +unless you use an Emacs Ada mode project file to specify the other directories; +@xref{Set source search path}, or a GNAT project file; @ref{Use GNAT +project file}. + +Invoke @key{Ada | Show main}; this displays @file{Ada mode main_unit: hello_2}. + +Move to the error with @key{C-x `}, and fix the error by adding @code{body}: + +@example +package body Hello_Pkg is +@end example + +Now, while still in @file{hello_pkg.adb}, invoke @key{Ada | Build}. +gnatmake successfully builds @file{hello_2}. This demonstrates that +Emacs has remembered the main file, in the project variable +@code{main_unit}, and used it for the Build command. + +Finally, again while in @file{hello_pkg.adb}, invoke @key{Ada | Run}. +The @code{*run*} buffer displays @code{Hello from hello_pkg.adb}. + +One final point. If you switch back to buffer @file{hello.adb}, and +invoke @key{Ada | Run}, @file{hello_2.exe} will be run. That is +because @code{main_unit} is still set to @code{hello_2}, as you can +see when you invoke @key{Ada | Project | Edit}. + +There are three ways to change @code{main_unit}: + +@enumerate +@item +Invoke @key{Ada | Set main and Build}, which sets @code{main_unit} to +the current file. + +@item +Invoke @key{Ada | Project | Edit}, edit @code{main_unit} and +@code{main}, and click @key{[save]} + +@item +Invoke @key{Ada | Project | Load}, and load a project file that specifies @code{main_unit} + +@end enumerate + +@node Set compiler options, Set source search path, No project files, Compiling Examples +@section Set compiler options + +This example illustrates using an Emacs Ada mode project file to set a +compiler option. + +If you have files from @file{Example_1} open in Emacs, you should +close them so you don't get confused. Use menu @key{File | Close +(current buffer)}. + +In directory @file{Example_2}, create these files: + +@file{hello.adb}: + +@example +with Ada.Text_IO; +procedure Hello +is begin + Put_Line("Hello from hello.adb"); +end Hello; +@end example + +This is the same as @file{hello.adb} from @file{Example_1}. It has two +errors; missing ``use Ada.Text_IO;'', and no space between +@code{Put_Line} and its argument list. + +@file{hello.adp}: + +@example +comp_opt=-gnatyt +@end example + +This tells the GNAT compiler to check for token spacing; in +particular, there must be a space preceding a parenthesis. + +In buffer @file{hello.adb}, invoke @key{Ada | Project | Load...}, and +select @file{Example_2/hello.adp}. + +Then, again in buffer @file{hello.adb}, invoke @key{Ada | Set main and +Build}. You should get a @code{*compilation*} buffer containing +something like (the directory paths will be different): + +@example +cd c:/Examples/Example_2/ +gnatmake -o hello hello -g -cargs -gnatyt -bargs -largs +gcc -c -g -gnatyt hello.adb +hello.adb:4:04: "Put_Line" is not visible +hello.adb:4:04: non-visible declaration at a-textio.ads:264 +hello.adb:4:04: non-visible declaration at a-textio.ads:260 +hello.adb:4:12: (style) space required +gnatmake: "hello.adb" compilation error +@end example + +Compare this to the compiler output in @ref{No project files}; the +gnatmake option @code{-cargs -gnatq -gnatQ} has been replaced by +@code{-cargs -gnaty}, and an additional error is reported in +@file{hello.adb} on line 4. This shows that @file{hello.adp} is being +used to set the compiler options. + +Fixing the error, linking and running the code proceed as in @ref{No +project files}. + +@node Set source search path, Use GNAT project file, Set compiler options, Compiling Examples +@section Set source search path + +In this example, we show how to deal with files in more than one +directory. We start with the same code as in @ref{No project files}; create those +files (with the errors present) + +Create the directory @file{Example_3}, containing: + +@file{hello_pkg.ads}: + +@example +package Hello_Pkg is + procedure Say_Hello; +end Hello_Pkg; +@end example + +@file{hello_pkg.adb}: + +@example +with Ada.Text_IO; +package Hello_Pkg is + procedure Say_Hello + is begin + Ada.Text_IO.Put_Line ("Hello from hello_pkg.adb"); + end Say_Hello; +end Hello_Pkg; +@end example + +These are the same files from example 1; @file{hello_pkg.adb} has an +error on line 2. + +In addition, create a directory @file{Example_3/Other}, containing these files: + +@file{Other/hello_3.adb}: + +@example +with Hello_Pkg; +with Ada.Text_IO; use Ada.Text_IO; +procedure Hello_3 +is begin + Hello_Pkg.Say_Hello; + Put_Line ("From hello_3"); +end Hello_3; +@end example + +There are no errors in this file. + +@file{Other/other.adp}: + +@example +src_dir=.. +comp_opt=-I.. +@end example + +Note that there must be no trailing spaces. + +In buffer @file{hello_3.adb}, invoke @key{Ada | Project | Load...}, and +select @file{Example_3/Other/other.adp}. + +Then, again in @file{hello_3.adb}, invoke @key{Ada | Set main and +Build}. You should get a @code{*compilation*} buffer containing +something like (the directory paths will be different): + +@example +cd c:/Examples/Example_3/Other/ +gnatmake -o hello_3 hello_3 -g -cargs -I.. -bargs -largs +gcc -c -g -I.. hello_3.adb +gcc -c -I./ -g -I.. -I- C:\Examples\Example_3\hello_pkg.adb +hello_pkg.adb:2:08: keyword "body" expected here [see file name] +gnatmake: "C:\Examples\Example_3\hello_pkg.adb" compilation error +@end example + +Compare the @code{-cargs} option to the compiler output in @ref{Set +compiler options}; this shows that @file{other.adp} is being used to +set the compiler options. + +Move to the error with @key{C-x `}. Ada mode searches the list of +directories given by @code{src_dir} for the file mentioned in the +compiler error message. + +Fixing the error, linking and running the code proceed as in @ref{No +project files}. + +@node Use GNAT project file, , Set source search path, Compiling Examples +@section Use GNAT project file + +In this example, we show how to use a GNAT project file. + +Create the directory @file{Example_4}, containing: + +@file{hello_pkg.ads}: + +@example +package Hello_Pkg is + procedure Say_Hello; +end Hello_Pkg; +@end example + +@file{hello_pkg.adb}: + +@example +with Ada.Text_IO; +package Hello_Pkg is + procedure Say_Hello + is begin + Ada.Text_IO.Put_Line ("Hello from hello_pkg.adb"); + end Say_Hello; +end Hello_Pkg; +@end example + +These are the same files from example 1; @file{hello_pkg.adb} has an +error on line 2. + +In addition, create a directory @file{Example_4/Gnat_Project}, +containing these files: + +@file{Other/hello_4.adb}: + +@example +with Hello_Pkg; +with Ada.Text_IO; use Ada.Text_IO; +procedure Hello_4 +is begin + Hello_Pkg.Say_Hello; + Put_Line ("From hello_4"); +end Hello_4; +@end example + +There are no errors in this file. + +@file{Gnat_Project/hello_4.adp}: + +@example +src_dir=.. +gnatmake_opt=-Phello_4.gpr +@end example + +@file{Gnat_Project/hello_4.gpr}: + +@example +Project Hello_4 is + for Source_Dirs use (".", ".."); +end Hello_4; +@end example + +In buffer @file{hello_4.adb}, invoke @key{Ada | Project | Load...}, and +select @file{Example_4/Gnat_Project/hello_4.adp}. + +Then, again in @file{hello_4.adb}, invoke @key{Ada | Set main and +Build}. You should get a @code{*compilation*} buffer containing +something like (the directory paths will be different): + +@example +cd c:/Examples/Example_4/Gnat_Project/ +gnatmake -o hello_4 hello_4 -Phello_4.gpr -cargs -gnatq -gnatQ -bargs -largs +gcc -c -g -gnatyt -gnatq -gnatQ -I- -gnatA c:\Examples\Example_4\Gnat_Project\hello_4.adb +gcc -c -g -gnatyt -gnatq -gnatQ -I- -gnatA c:\Examples\Example_4\hello_pkg.adb +hello_pkg.adb:2:08: keyword "body" expected here [see file name] +gnatmake: "c:\examples\example_4\hello_pkg.adb" compilation error +@end example + +Compare the @code{gcc} options to the compiler output in @ref{Set +compiler options}; this shows that @file{hello_4.gpr} is being used to +set the compiler options. + +Fixing the error, linking and running the code proceed as in @ref{No +project files}. + +@node Moving Through Ada Code, Identifier completion, Compiling Examples, Top +@chapter Moving Through Ada Code +@c ----------------------------------------------------------------------- + +There are several easy to use commands to navigate through Ada code. All +these functions are available through the Ada menu, and you can also +use the following key bindings or the command names. Some of these +menu entries are available only if the GNAT compiler is used, since +the implementation relies on the GNAT cross-referencing information. + +@table @kbd +@item M-C-e +@findex ada-next-procedure +Move to the next function/procedure/task, which ever comes next +(@code{ada-next-procedure}). +@item M-C-a +@findex ada-previous-procedure +Move to previous function/procedure/task +(@code{ada-previous-procedure}). +@item M-x ada-next-package +@findex ada-next-package +Move to next package. +@item M-x ada-previous-package +@findex ada-previous-package +Move to previous package. +@item C-c C-a +@findex ada-move-to-start +Move to matching start of @code{end} (@code{ada-move-to-start}). If +point is at the end of a subprogram, this command jumps to the +corresponding @code{begin} if the user option +@code{ada-move-to-declaration} is @code{nil} (default), otherwise it jumps to +the subprogram declaration. +@item C-c C-e +@findex ada-move-to-end +Move point to end of current block (@code{ada-move-to-end}). +@item C-c o +Switch between corresponding spec and body file +(@code{ff-find-other-file}). If point is in a subprogram, position +point on the corresponding declaration or body in the other file. +@item C-c c-d +@findex ada-goto-declaration +Move from any reference to its declaration, for from a declaration to +its body (for procedures, tasks, private and incomplete types). +@item C-c C-r +@findex ada-find-references +Runs the @file{gnatfind} command to search for all references to the +identifier surrounding point (@code{ada-find-references}). Use +@kbd{C-x `} (@code{next-error}) to visit each reference (as for +compilation errors). +@end table + +If the @code{ada-xref-create-ali} variable is non-@code{nil}, Emacs +will try to run GNAT for you whenever cross-reference information is +needed, and is older than the current source file. + +@node Identifier completion, Automatic Smart Indentation, Moving Through Ada Code, Top +@chapter Identifier completion + +Emacs and Ada mode provide two general ways for the completion of +identifiers. This is an easy way to type faster: you just have to type +the first few letters of an identifiers, and then loop through all the +possible completions. + +The first method is general for Emacs. It works by parsing all open +files for possible completions. + +For instance, if the words @samp{my_identifier}, @samp{my_subprogram} +are the only words starting with @samp{my} in any of the opened files, +then you will have this scenario: + +@example +You type: my@key{M-/} +Emacs inserts: @samp{my_identifier} +If you press @key{M-/} once again, Emacs replaces @samp{my_identifier} with +@samp{my_subprogram}. +Pressing @key{M-/} once more will bring you back to @samp{my_identifier}. +@end example + +This is a very fast way to do completion, and the casing of words will +also be respected. + +The second method (@key{C-TAB}) is specific to Ada mode and the GNAT +compiler. Emacs will search the cross-information for possible +completions. + +The main advantage is that this completion is more accurate: only +existing identifier will be suggested. + +On the other hand, this completion is a little bit slower and requires +that you have compiled your file at least once since you created that +identifier. + +@table @kbd +@item C-@key{TAB} +@findex ada-complete-identifier +Complete current identifier using cross-reference information. +@item M-/ +Complete identifier using buffer information (not Ada-specific). +@end table + +@node Automatic Smart Indentation, Formatting Parameter Lists, Identifier completion, Top +@chapter Automatic Smart Indentation + +Ada mode comes with a full set of rules for automatic indentation. You +can also configure the indentation, via the following variables: + +@table @asis +@item @code{ada-broken-indent} (default value: 2) +Number of columns to indent the continuation of a broken line. + +@item @code{ada-indent} (default value: 3) +Number of columns for default indentation. + +@item @code{ada-indent-record-rel-type} (default value: 3) +Indentation for @code{record} relative to @code{type} or @code{use}. + +@item @code{ada-indent-return} (default value: 0) +Indentation for @code{return} relative to @code{function} (if +@code{ada-indent-return} is greater than 0), or the open parenthesis +(if @code{ada-indent-return} is negative or 0). Note that in the second +case, when there is no open parenthesis, the indentation is done +relative to @code{function} with the value of @code{ada-broken-indent}. + +@item @code{ada-label-indent} (default value: -4) +Number of columns to indent a label. + +@item @code{ada-stmt-end-indent} (default value: 0) +Number of columns to indent a statement @code{end} keyword on a separate line. + +@item @code{ada-when-indent} (default value: 3) +Indentation for @code{when} relative to @code{exception} or @code{case}. + +@item @code{ada-indent-is-separate} (default value: t) +Non-@code{nil} means indent @code{is separate} or @code{is abstract} if on a single line. + +@item @code{ada-indent-to-open-paren} (default value: t) +Non-@code{nil} means indent according to the innermost open parenthesis. + +@item @code{ada-indent-after-return} (default value: t) +Non-@code{nil} means that the current line will also be re-indented +before inserting a newline, when you press @key{RET}. +@end table + +Most of the time, the indentation will be automatic, i.e when you +press @key{RET}, the cursor will move to the correct column on the +next line. + +You can also indent single lines, or the current region, with @key{TAB}. + +Another mode of indentation exists that helps you to set up your +indentation scheme. If you press @kbd{C-c @key{TAB}}, Ada mode will do +the following: + +@itemize @bullet +@item +Reindent the current line, as @key{TAB} would do. +@item +Temporarily move the cursor to a reference line, i.e., the line that +was used to calculate the current indentation. +@item +Display in the message window the name of the variable that provided +the offset for the indentation. +@end itemize + +The exact indentation of the current line is the same as the one for the +reference line, plus an offset given by the variable. + +@table @kbd +@item @key{TAB} +Indent the current line or the current region. +@item C-M-\ +Indent lines in the current region. +@item C-c @key{TAB} +Indent the current line and display the name of the variable used for +indentation. +@end table + +@node Formatting Parameter Lists, Automatic Casing, Automatic Smart Indentation, Top +@chapter Formatting Parameter Lists + +@table @kbd +@item C-c C-f +@findex ada-format-paramlist +Format the parameter list (@code{ada-format-paramlist}). +@end table + +This aligns the declarations on the colon (@samp{:}) separating +argument names and argument types, and aligns the @code{in}, +@code{out} and @code{in out} keywords. + +@node Automatic Casing, Statement Templates, Formatting Parameter Lists, Top +@chapter Automatic Casing + +Casing of identifiers, attributes and keywords is automatically +performed while typing when the variable @code{ada-auto-case} is set. +Every time you press a word separator, the previous word is +automatically cased. + +You can customize the automatic casing differently for keywords, +attributes and identifiers. The relevant variables are the following: +@code{ada-case-keyword}, @code{ada-case-attribute} and +@code{ada-case-identifier}. + +All these variables can have one of the following values: + +@table @code +@item downcase-word +The word will be lowercase. For instance @code{My_vARIable} is +converted to @code{my_variable}. + +@item upcase-word +The word will be uppercase. For instance @code{My_vARIable} is +converted to @code{MY_VARIABLE}. + +@item ada-capitalize-word +The first letter and each letter following an underscore (@samp{_}) +are uppercase, others are lowercase. For instance @code{My_vARIable} +is converted to @code{My_Variable}. + +@item ada-loose-case-word +Characters after an underscore @samp{_} character are uppercase, +others are not modified. For instance @code{My_vARIable} is converted +to @code{My_VARIable}. +@end table + +Ada mode allows you to define exceptions to these rules, in a file +specified by the variable variable @code{ada-case-exception-file} +(default @file{~/.emacs_case_exceptions}). Each line in this file +specifies the casing of one word or word fragment. Comments may be +included, separated from the word by a space. + +If the word starts with an asterisk (@key{*}), it defines the casing +af a word fragemnt (or ``substring''); part of a word between two +underscores or word boundary. + +For example: + +@example +DOD Department of Defense +*IO +GNAT The GNAT compiler from Ada Core Technologies +@end example + +The word fragment @code{*IO} applies to any word containing ``_io''; +@code{Text_IO}, @code{Hardware_IO}, etc. + +@findex ada-create-case-exception +There are two ways to add new items to this file: you can simply edit +it as you would edit any text file. Or you can position point on the +word you want to add, and select menu @samp{Ada | Edit | Create Case +Exception}, or press @kbd{C-c C-y} (@code{ada-create-case-exception}). +The word will automatically be added to the current list of exceptions +and to the file. + +To define a word fragment case exception, select the word fragment, +then select menu @samp{Ada | Edit | Create Case Exception Substring}. + +It is sometimes useful to have multiple exception files around (for +instance, one could be the standard Ada acronyms, the second some +company specific exceptions, and the last one some project specific +exceptions). If you set up the variable @code{ada-case-exception-file} +as a list of files, each of them will be parsed and used in your emacs +session. However, when you save a new exception through the menu, as +described above, the new exception will be added to the first file in +the list. + +@table @kbd +@item C-c C-b +@findex ada-adjust-case-buffer +Adjust case in the whole buffer (@code{ada-adjust-case-buffer}). +@item C-c C-y +Create a new entry in the exception dictionary, with the word under +the cursor (@code{ada-create-case-exception}) +@item C-c C-t +@findex ada-case-read-exceptions +Rereads the exception dictionary from the file +@code{ada-case-exception-file} (@code{ada-case-read-exceptions}). +@end table + +@node Statement Templates, Comment Handling, Automatic Casing, Top +@chapter Statement Templates + +Templates are defined for most Ada statements, using the Emacs +``skeleton'' package. They can be inserted in the buffer using the +following commands: + +@table @kbd +@item C-c t b +@findex ada-exception-block +exception Block (@code{ada-exception-block}). +@item C-c t c +@findex ada-case +case (@code{ada-case}). +@item C-c t d +@findex ada-declare-block +declare Block (@code{ada-declare-block}). +@item C-c t e +@findex ada-else +else (@code{ada-else}). +@item C-c t f +@findex ada-for-loop +for Loop (@code{ada-for-loop}). +@item C-c t h +@findex ada-header +Header (@code{ada-header}). +@item C-c t i +@findex ada-if +if (@code{ada-if}). +@item C-c t k +@findex ada-package-body +package Body (@code{ada-package-body}). +@item C-c t l +@findex ada-loop +loop (@code{ada-loop}). +@item C-c p +@findex ada-subprogram-body +subprogram body (@code{ada-subprogram-body}). +@item C-c t t +@findex ada-task-body +task Body (@code{ada-task-body}). +@item C-c t w +@findex ada-while +while Loop (@code{ada-while}). +@item C-c t u +@findex ada-use +use (@code{ada-use}). +@item C-c t x +@findex ada-exit +exit (@code{ada-exit}). +@item C-c t C-a +@findex ada-array +array (@code{ada-array}). +@item C-c t C-e +@findex ada-elsif +elsif (@code{ada-elsif}). +@item C-c t C-f +@findex ada-function-spec +function Spec (@code{ada-function-spec}). +@item C-c t C-k +@findex ada-package-spec +package Spec (@code{ada-package-spec}). +@item C-c t C-p +@findex ada-procedure-spec +procedure Spec (@code{ada-package-spec}. +@item C-c t C-r +@findex ada-record +record (@code{ada-record}). +@item C-c t C-s +@findex ada-subtype +subtype (@code{ada-subtype}). +@item C-c t C-t +@findex ada-task-spec +task Spec (@code{ada-task-spec}). +@item C-c t C-u +@findex ada-with +with (@code{ada-with}). +@item C-c t C-v +@findex ada-private +private (@code{ada-private}). +@item C-c t C-w +@findex ada-when +when (@code{ada-when}). +@item C-c t C-x +@findex ada-exception +exception (@code{ada-exception}). +@item C-c t C-y +@findex ada-type +type (@code{ada-type}). +@end table + +@node Comment Handling, GNU Free Documentation License, Statement Templates, Top +@chapter Comment Handling + +By default, comment lines get indented like Ada code. There are a few +additional functions to handle comments: + +@table @kbd +@item M-; +Start a comment in default column. +@item M-j +Continue comment on next line. +@item C-c ; +Comment the selected region (add -- at the beginning of lines). +@item C-c : +Uncomment the selected region +@item M-q +autofill the current comment. +@end table + +@node GNU Free Documentation License, Index, Comment Handling, Top +@appendix GNU Free Documentation License +@include doclicense.texi + +@node Index, , GNU Free Documentation License, Top +@unnumbered Index + +@printindex fn + +@contents +@bye + +@ignore + arch-tag: 68cf0d8a-55cc-4190-a28d-4984fa56ed1e +@end ignore |