\input texinfo @c -*-texinfo-*-@setfilename ../info/ada-mode@settitle Ada Mode@copyingCopyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004,2005, 2006, 2007 Free Software Foundation, Inc.@quotationPermission is granted to copy, distribute and/or modify this documentunder the terms of the GNU Free Documentation License, Version 1.2 orany later version published by the Free Software Foundation; with theInvariant Sections being ``The GNU Manifesto'', ``Distribution'' and``GNU GENERAL PUBLIC LICENSE'', with the Front-Cover texts being ``A GNUManual'', and with the Back-Cover Texts as in (a) below. A copy of thelicense is included in the section entitled ``GNU Free DocumentationLicense'' in the Emacs manual.(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modifythis GNU Manual, like GNU software. Copies published by the FreeSoftware Foundation raise funds for GNU development.''This document is part of a collection distributed under the GNU FreeDocumentation License. If you want to distribute this documentseparately from the collection, you can do so by adding a copy of thelicense 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 OverviewThe Emacs mode for programming in Ada helps the user in understandingexisting code and facilitates writing new code.When the Gnu Ada compiler GNAT is used, the cross-referenceinformation output by the compiler is used to provide powerful codenavigation (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 GNATcompiler (@url{https://libre2.adacore.com/}) and the GNAT defaultnaming convention.You must customize a few things if you are using a different compileror file naming convention; @xref{Other compiler}, @xref{Non-standardfile 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 EmacsAda mode project file for each project; @xref{Project files}. Notethat these are different from the GNAT project files used by gnatmakeand other GNAT commands.See the Emacs info manual, section 'Running Debuggers Under Emacs',for general information on debugging.@node Installation, Customization, Overview, Top@chapter InstallationAda 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 EmacsAda mode website@uref{http://stephe-leake.org/emacs/ada-mode/emacs-ada-mode.html}. Theseparate distribution may be more recent.For installing the separate distribution, see the @file{README} filein the distribution.To see what version of Ada mode you have installed, do @key{M-xada-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 handlingand automatic casing.@item@file{ada-prj.el}: GUI editing of Ada mode project files, using Emacswidgets.@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 notGNAT-specific).@end itemize@node Customization, Compiling Executing, Installation, Top@chapter Customizing Ada modeHere we assume you are familiar with setting variables in Emacs,either thru 'customize' or in elisp (in your @file{.emacs} file). Fora basic introduction to customize, elisp, and Emacs in general, seethe 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 ifinfoThese 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 syntaxhighlighting for all buffers (it is off by default because it may betoo 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 namesBy default, Ada mode is configured to use the GNAT file namingconvention, where file names are a simple modification of the Adanames, 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 bodyto 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, youcan add the following to your @file{.emacs} file:@example(ada-add-extensions "_s.ada" "_b.ada")@end exampleYou can define additional extensions:@example(ada-add-extensions ".ads" "_b.ada")(ada-add-extensions ".ads" ".body")@end exampleThis means that whenever Ada mode looks for the body for a filewhose extension is @file{.ads}, it will take the first available filethat 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 GNATconvention, things are a little more complicated. You then need torewrite the function @code{ada-make-filename-from-adaname}. Doing thatis 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 compilerBy default, Ada mode is configured to use the Gnu Ada compiler GNAT.To use a different Ada compiler, you must specify the command linesused to run that compiler, either in lisp variables or in EmacsAda mode project files. See @ref{Project file variables} for the listof project variables, and the corresponding lisp variables.@node Other customization, , Other compiler, Customization@section Other customizationAll user-settable Ada mode variables can be set via the menu@samp{Ada | Customize}. Click on the @samp{Help} button there for helpon 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 Emacsconfiguration 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 ExecutingAda projects can be compiled, linked, and executed using commands onthe Ada menu. All of these commands can be customized via a projectfile (@pxref{Project files}), but the defaults are sufficient for usingthe GNAT compiler for simple projects (single files, or several filesin 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 projectfile variables referenced here.@menu* Compile commands::* Compiler errors::@end menu@node Compile commands, Compiler errors, Compiling Executing, Compiling Executing@section Compile commandsHere are the commands for building and using an Ada project, aslisted in the Ada menu.In multi-file projects, there must be one file that is the mainprogram. 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 fileCompiles the current file in syntax check mode, by running@code{check_cmd} defined in the current project file. This typicallyruns faster than full compile mode, speeding up finding and fixingcompilation errors.This sets @code{main_unit} only if it has not been set yet.@item Compile fileCompiles the current file, by running @code{comp_cmd} from the currentproject file.This does not set @code{main_unit}.@item Set main and BuildSets @code{main_unit} to the current file, then executes the Buildcommand.@item Show mainDisplay @code{main_unit} in the message buffer.@item BuildCompiles 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 RunExecutes the main program in a shell, displayed in a separate Emacsbuffer. This runs @code{run_cmd} from the current project. Theexecution buffer allows for interactive input/output.To modify the run command, in particular to provide or change thecommand line arguments, type @key{C-u} before invoking the command.This command is not available for a cross-compilation toolchain.@end tableIt 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/compilesession, this is the only command you need to invoke, which is why itis bound to @key{C-c C-c}. It will compile all files needed by themain unit, and display compilation errors in any of them.Note that Build can be invoked from any Ada buffer; typically you willbe fixing errors in files other than the main, but you don't have toswitch back to the main to invoke the compiler again.Novices and students typically work on single-file Ada projects. Inthis case, @key{C-c C-m} will normally be the only command needed; itwill build the current file, rather than the last-built main.There are three ways to change @code{main_unit}:@enumerate@itemInvoke @key{Ada | Set main and Build}, which sets @code{main_unit} tothe current file.@itemInvoke @key{Ada | Project | Edit}, edit @code{main_unit} and@code{main}, and click @key{[save]}@itemInvoke @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 errorsThe @code{Check file}, @code{Compile file}, and @code{Build} commandsall place compilation errors in a separate buffer named@code{*compilation*}.Each line in this buffer will become active: you can simply click onit 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 putpoint on the line and column where the error was found.You can also press the @kbd{C-x `} key (@code{next-error}), and Emacswill jump to the first error. If you press that key again, it willmove you to the second error, and so on.Some error messages might also include references to other files. Thesereferences are also clickable in the same way, or put point after theline number and press @key{RET}.@node Project files, Compiling Examples, Compiling Executing, Top@chapter Project filesAn Emacs Ada mode project file specifies what directories hold sourcesfor your project, and allows you to customize the compilation commandsand other things on a per-project basis.Note that Ada mode project files @samp{*.adp} are different than GNATcompiler 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 OverviewProject files have a simple syntax; they may be edited directly. Eachline specifies a project variable name and its value, separated by ``='':@examplesrc_dir=/Projects/my_project/src_1src_dir=/Projects/my_project/src_2@end exampleSome variables (like @code{src_dir}) are lists; multiple occurancesare concatenated.There must be no space between the variable name and ``='', and notrailing spaces.Alternately, a GUI editor for project files is available (@pxref{GUIEditor}). It uses Emacs widgets, similar to Emacs customize.The GUI editor also provides a convenient way to view current projectsettings, if they have been modified using menu commands rather thanby editing the project file.After the first Ada mode build command is invoked, there is always acurrent project file, given by the lisp variable@code{ada-prj-default-project-file}. Currently, the only way to showthe current project file is to invoke the GUI editor.To find the project file the first time, Ada mode uses the followingsearch algorithm:@itemize @bullet@itemIf @code{ada-prj-default-project-file} is set, use that.@itemOtherwise, search for a file in the current directory withthe same base name as the Ada file, but extension given by@code{ada-prj-file-extension} (default @code{".adp"}).@itemIf not found, search for @file{*.adp} in the current directory; ifseveral are found, prompt the user to select one.@itemIf none are found, use @file{default.adp} in the current directory (evenif it does not exist).@end itemizeThis algorithm always sets @code{ada-prj-default-project-file}, evenwhen 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 EditorThe project file editor is invoked with the menu @samp{Ada | Projects| Edit}.Once in the buffer for editing the project file, you can save yourmodification using the @samp{[save]} button at the bottom of thebuffer, 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 variablesThe following variables can be defined in a project file; some canalso be defined in lisp variables.To set a project variable that is a list, specify each element of thelist 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} isused.Most project variables have defaults that can be changed by settinglisp variables; the table below identifies the lisp variable for eachproject variable. Lisp variables corresponding to project variablesthat are lists are lisp lists.Here is the list of variables. In the default values, the currentdirectory @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 compilecommands and source navigation.@item @code{obj_dir} [default: @code{"."}]A list of directories to search for library files. Ada mode searchesthis list for the @samp{.ali} files generated by GNAT that containcross-reference information.The compiler commands must place the @samp{.ali} files in one of thesedirectories; 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 exceptionsLisp variable: @code{ada-case-exception-file}.@item @code{comp_opt} [default: @code{"-gnatq -gnatQ"}]Holds user compiler options; used in the default compile commands. Thedefault value tells gnatmake to generate library files forcross-referencing even when there are errors.If source code for the project is in multiple directories, theappropriate compiler options must be added here. @ref{Set sourcesearch path} for examples of this. Alternately, GNAT project files maybe 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}), thisoption 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 thedefault build commands.@item @code{main_unit} [default: current Ada unit]Specifies the name of the main Ada unit for the project; used in thedefault build commands.@item @code{cross_prefix} [default: @code{""}]Name of target machine in a cross-compilation environment. Used indefault compile and build commands.@item @code{remote_machine} [default: @code{""}]Name of the machine to log into before issuing the compile and buildcommands. If this variable is empty, the command will be run on thelocal 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 applicationLisp 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 ExamplesWe present several small projects, and walk thru the process ofcompiling, 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 modewebsite 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 filesThis example uses no project files.First, create a directory @file{Example_1}, containing:@file{hello.adb}:@examplewith Ada.Text_IO;procedure Hellois begin Put_Line("Hello from hello.adb");end Hello;@end exampleYes, this is missing ``use Ada.Text_IO;'' - we want to demonstratecompiler error handling.@file{hello_2.adb}:@examplewith Hello_Pkg;procedure Hello_2is begin Hello_Pkg.Say_Hello;end Hello_2;@end example@file{hello_pkg.ads}:@examplepackage Hello_Pkg is procedure Say_Hello;end Hello_Pkg;@end example@file{hello_pkg.adb}:@examplewith 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 exampleYes, this is missing the keyword @code{body}; another compiler errorexample.In buffer @file{hello.adb}, invoke @key{Ada | Check file}. You shouldget a @code{*compilation*} buffer containing something like (thedirectory paths will be different):@examplecd c:/Examples/Example_1/gnatmake -u -c -gnatc -g c:/Examples/Example_1/hello.adb -cargs -gnatq -gnatQgcc -c -Ic:/Examples/Example_1/ -gnatc -g -gnatq -gnatQ -I- c:/Examples/Example_1/hello.adbhello.adb:4:04: "Put_Line" is not visiblehello.adb:4:04: non-visible declaration at a-textio.ads:264hello.adb:4:04: non-visible declaration at a-textio.ads:260gnatmake: "c:/Examples/Example_1/hello.adb" compilation error@end exampleIf you have enabled font-lock, the lines with actual errors (startingwith @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. Thecompilation buffer scrolls to put the first error on the top line, andpoint 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 exampleNow invoke @key{Ada | Show main}; this displays @file{Ada mode main_unit: hello}.Now (in buffer @file{hello.adb}), invoke @key{Ada | Build}. You areprompted to save the file (if you haven't already). Then thecompilation buffer is displayed again, containing:@examplecd c:/Examples/Example_1/gnatmake -o hello hello -g -cargs -gnatq -gnatQ -bargs -largsgcc -c -g -gnatq -gnatQ hello.adbgnatbind -x hello.alignatlink hello.ali -o hello.exe -g@end exampleThe compilation has succeeded without errors; @file{hello.exe} nowexists in the same directory as @file{hello.adb}.Now invoke @key{Ada | Run}. A @file{*run*} buffer is displayed,containing@exampleHello from hello.adbProcess run finished@end exampleThat 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}. Thisfinds an error in @file{hello_pkg.adb}:@examplecd c:/Examples/Example_1/gnatmake -o hello_2 hello_2 -g -cargs -gnatq -gnatQ -bargs -largsgcc -c -g -gnatq -gnatQ hello_pkg.adbhello_pkg.adb:2:08: keyword "body" expected here [see file name]gnatmake: "hello_pkg.adb" compilation error@end exampleThis demonstrates that gnatmake finds the files needed by the mainprogram. 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 GNATproject 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}:@examplepackage body Hello_Pkg is@end exampleNow, while still in @file{hello_pkg.adb}, invoke @key{Ada | Build}.gnatmake successfully builds @file{hello_2}. This demonstrates thatEmacs 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}, andinvoke @key{Ada | Run}, @file{hello_2.exe} will be run. That isbecause @code{main_unit} is still set to @code{hello_2}, as you cansee when you invoke @key{Ada | Project | Edit}.There are three ways to change @code{main_unit}:@enumerate@itemInvoke @key{Ada | Set main and Build}, which sets @code{main_unit} tothe current file.@itemInvoke @key{Ada | Project | Edit}, edit @code{main_unit} and@code{main}, and click @key{[save]}@itemInvoke @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 optionsThis example illustrates using an Emacs Ada mode project file to set acompiler option.If you have files from @file{Example_1} open in Emacs, you shouldclose 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}:@examplewith Ada.Text_IO;procedure Hellois begin Put_Line("Hello from hello.adb");end Hello;@end exampleThis is the same as @file{hello.adb} from @file{Example_1}. It has twoerrors; missing ``use Ada.Text_IO;'', and no space between@code{Put_Line} and its argument list.@file{hello.adp}:@examplecomp_opt=-gnatyt@end exampleThis tells the GNAT compiler to check for token spacing; inparticular, there must be a space preceding a parenthesis.In buffer @file{hello.adb}, invoke @key{Ada | Project | Load...}, andselect @file{Example_2/hello.adp}.Then, again in buffer @file{hello.adb}, invoke @key{Ada | Set main andBuild}. You should get a @code{*compilation*} buffer containingsomething like (the directory paths will be different):@examplecd c:/Examples/Example_2/gnatmake -o hello hello -g -cargs -gnatyt -bargs -largsgcc -c -g -gnatyt hello.adbhello.adb:4:04: "Put_Line" is not visiblehello.adb:4:04: non-visible declaration at a-textio.ads:264hello.adb:4:04: non-visible declaration at a-textio.ads:260hello.adb:4:12: (style) space requiredgnatmake: "hello.adb" compilation error@end exampleCompare this to the compiler output in @ref{No project files}; thegnatmake 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 beingused to set the compiler options.Fixing the error, linking and running the code proceed as in @ref{Noproject files}.@node Set source search path, Use GNAT project file, Set compiler options, Compiling Examples@section Set source search pathIn this example, we show how to deal with files in more than onedirectory. We start with the same code as in @ref{No project files}; create thosefiles (with the errors present)Create the directory @file{Example_3}, containing:@file{hello_pkg.ads}:@examplepackage Hello_Pkg is procedure Say_Hello;end Hello_Pkg;@end example@file{hello_pkg.adb}:@examplewith 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 exampleThese are the same files from example 1; @file{hello_pkg.adb} has anerror on line 2.In addition, create a directory @file{Example_3/Other}, containing these files:@file{Other/hello_3.adb}:@examplewith Hello_Pkg;with Ada.Text_IO; use Ada.Text_IO;procedure Hello_3is begin Hello_Pkg.Say_Hello; Put_Line ("From hello_3");end Hello_3;@end exampleThere are no errors in this file.@file{Other/other.adp}:@examplesrc_dir=..comp_opt=-I..@end exampleNote that there must be no trailing spaces.In buffer @file{hello_3.adb}, invoke @key{Ada | Project | Load...}, andselect @file{Example_3/Other/other.adp}.Then, again in @file{hello_3.adb}, invoke @key{Ada | Set main andBuild}. You should get a @code{*compilation*} buffer containingsomething like (the directory paths will be different):@examplecd c:/Examples/Example_3/Other/gnatmake -o hello_3 hello_3 -g -cargs -I.. -bargs -largsgcc -c -g -I.. hello_3.adbgcc -c -I./ -g -I.. -I- C:\Examples\Example_3\hello_pkg.adbhello_pkg.adb:2:08: keyword "body" expected here [see file name]gnatmake: "C:\Examples\Example_3\hello_pkg.adb" compilation error@end exampleCompare the @code{-cargs} option to the compiler output in @ref{Setcompiler options}; this shows that @file{other.adp} is being used toset the compiler options.Move to the error with @key{C-x `}. Ada mode searches the list ofdirectories given by @code{src_dir} for the file mentioned in thecompiler error message.Fixing the error, linking and running the code proceed as in @ref{Noproject files}.@node Use GNAT project file, , Set source search path, Compiling Examples@section Use GNAT project fileIn this example, we show how to use a GNAT project file.Create the directory @file{Example_4}, containing:@file{hello_pkg.ads}:@examplepackage Hello_Pkg is procedure Say_Hello;end Hello_Pkg;@end example@file{hello_pkg.adb}:@examplewith 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 exampleThese are the same files from example 1; @file{hello_pkg.adb} has anerror on line 2.In addition, create a directory @file{Example_4/Gnat_Project},containing these files:@file{Other/hello_4.adb}:@examplewith Hello_Pkg;with Ada.Text_IO; use Ada.Text_IO;procedure Hello_4is begin Hello_Pkg.Say_Hello; Put_Line ("From hello_4");end Hello_4;@end exampleThere are no errors in this file.@file{Gnat_Project/hello_4.adp}:@examplesrc_dir=..gnatmake_opt=-Phello_4.gpr@end example@file{Gnat_Project/hello_4.gpr}:@exampleProject Hello_4 is for Source_Dirs use (".", "..");end Hello_4;@end exampleIn buffer @file{hello_4.adb}, invoke @key{Ada | Project | Load...}, andselect @file{Example_4/Gnat_Project/hello_4.adp}.Then, again in @file{hello_4.adb}, invoke @key{Ada | Set main andBuild}. You should get a @code{*compilation*} buffer containingsomething like (the directory paths will be different):@examplecd c:/Examples/Example_4/Gnat_Project/gnatmake -o hello_4 hello_4 -Phello_4.gpr -cargs -gnatq -gnatQ -bargs -largsgcc -c -g -gnatyt -gnatq -gnatQ -I- -gnatA c:\Examples\Example_4\Gnat_Project\hello_4.adbgcc -c -g -gnatyt -gnatq -gnatQ -I- -gnatA c:\Examples\Example_4\hello_pkg.adbhello_pkg.adb:2:08: keyword "body" expected here [see file name]gnatmake: "c:\examples\example_4\hello_pkg.adb" compilation error@end exampleCompare the @code{gcc} options to the compiler output in @ref{Setcompiler options}; this shows that @file{hello_4.gpr} is being used toset the compiler options.Fixing the error, linking and running the code proceed as in @ref{Noproject 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. Allthese functions are available through the Ada menu, and you can alsouse the following key bindings or the command names. Some of thesemenu entries are available only if the GNAT compiler is used, sincethe implementation relies on the GNAT cross-referencing information.@table @kbd@item M-C-e@findex ada-next-procedureMove to the next function/procedure/task, which ever comes next(@code{ada-next-procedure}).@item M-C-a@findex ada-previous-procedureMove to previous function/procedure/task(@code{ada-previous-procedure}).@item M-x ada-next-package@findex ada-next-packageMove to next package.@item M-x ada-previous-package@findex ada-previous-packageMove to previous package.@item C-c C-a@findex ada-move-to-startMove to matching start of @code{end} (@code{ada-move-to-start}). Ifpoint is at the end of a subprogram, this command jumps to thecorresponding @code{begin} if the user option@code{ada-move-to-declaration} is @code{nil} (default), otherwise it jumps tothe subprogram declaration.@item C-c C-e@findex ada-move-to-endMove point to end of current block (@code{ada-move-to-end}).@item C-c oSwitch between corresponding spec and body file(@code{ff-find-other-file}). If point is in a subprogram, positionpoint on the corresponding declaration or body in the other file.@item C-c c-d@findex ada-goto-declarationMove from any reference to its declaration, for from a declaration toits body (for procedures, tasks, private and incomplete types).@item C-c C-r@findex ada-find-referencesRuns the @file{gnatfind} command to search for all references to theidentifier surrounding point (@code{ada-find-references}). Use@kbd{C-x `} (@code{next-error}) to visit each reference (as forcompilation errors).@end tableIf the @code{ada-xref-create-ali} variable is non-@code{nil}, Emacswill try to run GNAT for you whenever cross-reference information isneeded, and is older than the current source file.@node Identifier completion, Automatic Smart Indentation, Moving Through Ada Code, Top@chapter Identifier completionEmacs and Ada mode provide two general ways for the completion ofidentifiers. This is an easy way to type faster: you just have to typethe first few letters of an identifiers, and then loop through all thepossible completions.The first method is general for Emacs. It works by parsing all openfiles 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:@exampleYou 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 exampleThis is a very fast way to do completion, and the casing of words willalso be respected.The second method (@key{C-TAB}) is specific to Ada mode and the GNATcompiler. Emacs will search the cross-information for possiblecompletions.The main advantage is that this completion is more accurate: onlyexisting identifier will be suggested.On the other hand, this completion is a little bit slower and requiresthat you have compiled your file at least once since you created thatidentifier.@table @kbd@item C-@key{TAB}@findex ada-complete-identifierComplete 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 IndentationAda mode comes with a full set of rules for automatic indentation. Youcan 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 secondcase, when there is no open parenthesis, the indentation is donerelative 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-indentedbefore inserting a newline, when you press @key{RET}.@end tableMost of the time, the indentation will be automatic, i.e when youpress @key{RET}, the cursor will move to the correct column on thenext 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 yourindentation scheme. If you press @kbd{C-c @key{TAB}}, Ada mode will dothe following:@itemize @bullet@itemReindent the current line, as @key{TAB} would do.@itemTemporarily move the cursor to a reference line, i.e., the line thatwas used to calculate the current indentation.@itemDisplay in the message window the name of the variable that providedthe offset for the indentation.@end itemizeThe exact indentation of the current line is the same as the one for thereference 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 forindentation.@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-paramlistFormat the parameter list (@code{ada-format-paramlist}).@end tableThis aligns the declarations on the colon (@samp{:}) separatingargument 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 CasingCasing of identifiers, attributes and keywords is automaticallyperformed while typing when the variable @code{ada-auto-case} is set.Every time you press a word separator, the previous word isautomatically 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-wordThe word will be lowercase. For instance @code{My_vARIable} isconverted to @code{my_variable}.@item upcase-wordThe word will be uppercase. For instance @code{My_vARIable} isconverted to @code{MY_VARIABLE}.@item ada-capitalize-wordThe 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-wordCharacters after an underscore @samp{_} character are uppercase,others are not modified. For instance @code{My_vARIable} is convertedto @code{My_VARIable}.@end tableAda mode allows you to define exceptions to these rules, in a filespecified by the variable variable @code{ada-case-exception-file}(default @file{~/.emacs_case_exceptions}). Each line in this filespecifies the casing of one word or word fragment. Comments may beincluded, separated from the word by a space.If the word starts with an asterisk (@key{*}), it defines the casingaf a word fragemnt (or ``substring''); part of a word between twounderscores or word boundary.For example:@exampleDOD Department of Defense*IOGNAT The GNAT compiler from Ada Core Technologies@end exampleThe word fragment @code{*IO} applies to any word containing ``_io'';@code{Text_IO}, @code{Hardware_IO}, etc.@findex ada-create-case-exceptionThere are two ways to add new items to this file: you can simply editit as you would edit any text file. Or you can position point on theword you want to add, and select menu @samp{Ada | Edit | Create CaseException}, or press @kbd{C-c C-y} (@code{ada-create-case-exception}).The word will automatically be added to the current list of exceptionsand 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 (forinstance, one could be the standard Ada acronyms, the second somecompany specific exceptions, and the last one some project specificexceptions). 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 emacssession. However, when you save a new exception through the menu, asdescribed above, the new exception will be added to the first file inthe list.@table @kbd@item C-c C-b@findex ada-adjust-case-bufferAdjust case in the whole buffer (@code{ada-adjust-case-buffer}).@item C-c C-yCreate a new entry in the exception dictionary, with the word underthe cursor (@code{ada-create-case-exception})@item C-c C-t@findex ada-case-read-exceptionsRereads 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 TemplatesTemplates are defined for most Ada statements, using the Emacs``skeleton'' package. They can be inserted in the buffer using thefollowing commands:@table @kbd@item C-c t b@findex ada-exception-blockexception Block (@code{ada-exception-block}).@item C-c t c@findex ada-casecase (@code{ada-case}).@item C-c t d@findex ada-declare-blockdeclare Block (@code{ada-declare-block}).@item C-c t e@findex ada-elseelse (@code{ada-else}).@item C-c t f@findex ada-for-loopfor Loop (@code{ada-for-loop}).@item C-c t h@findex ada-headerHeader (@code{ada-header}).@item C-c t i@findex ada-ifif (@code{ada-if}).@item C-c t k@findex ada-package-bodypackage Body (@code{ada-package-body}).@item C-c t l@findex ada-looploop (@code{ada-loop}).@item C-c p@findex ada-subprogram-bodysubprogram body (@code{ada-subprogram-body}).@item C-c t t@findex ada-task-bodytask Body (@code{ada-task-body}).@item C-c t w@findex ada-whilewhile Loop (@code{ada-while}).@item C-c t u@findex ada-useuse (@code{ada-use}).@item C-c t x@findex ada-exitexit (@code{ada-exit}).@item C-c t C-a@findex ada-arrayarray (@code{ada-array}).@item C-c t C-e@findex ada-elsifelsif (@code{ada-elsif}).@item C-c t C-f@findex ada-function-specfunction Spec (@code{ada-function-spec}).@item C-c t C-k@findex ada-package-specpackage Spec (@code{ada-package-spec}).@item C-c t C-p@findex ada-procedure-specprocedure Spec (@code{ada-package-spec}.@item C-c t C-r@findex ada-recordrecord (@code{ada-record}).@item C-c t C-s@findex ada-subtypesubtype (@code{ada-subtype}).@item C-c t C-t@findex ada-task-spectask Spec (@code{ada-task-spec}).@item C-c t C-u@findex ada-withwith (@code{ada-with}).@item C-c t C-v@findex ada-privateprivate (@code{ada-private}).@item C-c t C-w@findex ada-whenwhen (@code{ada-when}).@item C-c t C-x@findex ada-exceptionexception (@code{ada-exception}).@item C-c t C-y@findex ada-typetype (@code{ada-type}).@end table@node Comment Handling, GNU Free Documentation License, Statement Templates, Top@chapter Comment HandlingBy default, comment lines get indented like Ada code. There are a fewadditional functions to handle comments:@table @kbd@item M-;Start a comment in default column.@item M-jContinue 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-qautofill 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