Mercurial > emacs
view man/ada-mode.texi @ 75247:cebac0d73dd0
Remove Perry copyright based on copyright.list:
EMACS William M. Perry USA 1971 1998-12-23
Assigns past and future changes.
author | Glenn Morris <rgm@gnu.org> |
---|---|
date | Tue, 16 Jan 2007 02:21:24 +0000 |
parents | ad6a503ca867 |
children | 3d45362f1d38 dbe3f29e61d6 |
line wrap: on
line source
\input texinfo @c -*-texinfo-*- @setfilename ../info/ada-mode @settitle Ada Mode @copying Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006 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 * 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, Index, 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 Index, , Comment Handling, Top @unnumbered Index @printindex fn @contents @bye @ignore arch-tag: 68cf0d8a-55cc-4190-a28d-4984fa56ed1e @end ignore