# HG changeset patch # User Glenn Morris # Date 1189053208 0 # Node ID f500e1270d94cfed9644a17a7a814e42ae56c90e # Parent 7ca4609a5e6730752bdf01dc2f62bee0cd1a6edf Move to ../doc/emacs/, misc/ diff -r 7ca4609a5e67 -r f500e1270d94 man/ada-mode.texi --- a/man/ada-mode.texi Thu Sep 06 04:33:23 2007 +0000 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,1410 +0,0 @@ -\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