branch: externals/ada-mode commit df6efc230967d474166b4ceb8fe6ef9b5817f8a2 Author: Stephen Leake <stephen_le...@stephe-leake.org> Commit: Stephen Leake <stephen_le...@stephe-leake.org>
First attempt to make doc cross reference work on ELPA website * ada-build.el (ada-build-require-project-file): Fix typo in doc string. * ada-mode.info: Delete; now built by the elpa server. * ada-mode.texi (Project files): Fix wisi cross reference. For html, make it work on the ELPA website. (Project file overview): Fix wisi cross reference. --- ada-build.el | 6 +- ada-mode.info | 2665 --------------------------------------------------------- ada-mode.texi | 6 +- 3 files changed, 7 insertions(+), 2670 deletions(-) diff --git a/ada-build.el b/ada-build.el index 7d12dbf..7706896 100644 --- a/ada-build.el +++ b/ada-build.el @@ -1,7 +1,7 @@ ;; ada-build.el --- Extensions to ada-mode for compiling and running -*- lexical-binding:t -*- ;; Ada projects without 'make' or similar tool ;; -;; Copyright (C) 1994, 1995, 1997 - 2017, 2019 Free Software Foundation, Inc. +;; Copyright (C) 1994, 1995, 1997 - 2017, 2019, 2021 Free Software Foundation, Inc. ;; ;; Author: Stephen Leake <stephen_le...@member.fsf.org> ;; Maintainer: Stephen Leake <stephen_le...@member.fsf.org> @@ -232,9 +232,9 @@ main. search-prompt - Search for a project file in the current directory with the same name as the main file. If not found, -prompt for a project file; thow error if user aborts +prompt for a project file; throw an error if user aborts. -prompt - Prompt for a project file; thow error if user aborts. +prompt - Prompt for a project file; throw an error if user aborts. error - Throw an error (no prompt, no default project). diff --git a/ada-mode.info b/ada-mode.info deleted file mode 100644 index e179e9f..0000000 --- a/ada-mode.info +++ /dev/null @@ -1,2665 +0,0 @@ -This is ada-mode.info, produced by makeinfo version 6.7 from -ada-mode.texi. - -Copyright (C) 1999 - 2021 Free Software Foundation, Inc. - - Permission is granted to copy, distribute and/or modify this - document under the terms of the GNU Free Documentation License, - Version 1.3 or any later version published by the Free Software - Foundation; with no Invariant Sections, 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". - - (a) The FSF's Back-Cover Text is: "You have the freedom to copy and - modify this GNU manual. Buying copies from the FSF supports it in - developing GNU and promoting software freedom." -INFO-DIR-SECTION Emacs -START-INFO-DIR-ENTRY -* Ada mode: (ada-mode). Emacs mode for editing and navigating Ada code. -END-INFO-DIR-ENTRY - - -File: ada-mode.info, Node: Top, Next: Overview, Prev: (dir), Up: (dir) - -Top -*** - -Ada Mode Version 7.1.5 - -* 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 -* Moving Through Ada Code:: Moving easily through Ada sources -* Identifier completion:: Finishing words automatically -* Indentation:: Indenting your code automatically as you type -* Statement skeletons:: Some code is written for you -* Aligning code:: Making it pretty -* Automatic casing:: Adjusting the case of words automatically -* Comment Handling:: Reformatting comments easily -* Key summary:: -* Developer overview:: -* GNU Free Documentation License:: - - -- The Detailed Node Listing -- - -Overview - -* Why not LSP?:: - -Installation - -* Ada executables:: -* Known versions:: - -Ada executables - -* Building GNATCOLL:: -* Building the executables:: - -Customizing Ada mode - -* Slow response:: -* Non-standard file names:: -* Other compiler:: -* Other cross-reference:: -* Other customization:: - -Compiling Executing - -* Compile commands:: -* Compiling Examples:: -* Compiler errors:: - -Compiling Examples - -* No project files:: Just menus -* Set compiler options:: A basic Ada mode project file -* Set source search path:: Source in multiple directories -* Use wisi project file:: -* Use multiple GNAT project files:: -* Use a Makefile:: - -Project files - -* Project file overview:: -* Project file variables:: - -Developer overview - -* Directory structure:: -* ELPA:: -* Savannah:: - - - -File: ada-mode.info, Node: Overview, Next: Installation, Prev: Top, Up: Top - -1 Overview -********** - -The Emacs mode for programming in Ada helps the user in reading existing -code and facilitates developing new code. - - 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 '.ads' or '.adb', Emacs -will automatically load and activate Ada mode. - - Ada mode works without any customization, if you are using the GNAT -compiler (<https://libre.adacore.com/>) and the GNAT default naming -convention. - - You must customize a few things if you are using a different file -naming convention or compiler; *Note Non-standard file names::, *Note -Other compiler::. - - In addition, you may want to customize the indentation, -capitalization, and other things; *Note Other customization::. - - Finally, for large Ada projects, you will want to set up an Emacs Ada -mode project file for each project; *Note Project files::. Note that -these are different from the GNAT project files used by the GNAT tools. - - *Note Debuggers: (emacs)Debuggers, for general information on -debugging. - -* Menu: - -* Why not LSP?:: - - -File: ada-mode.info, Node: Why not LSP?, Up: Overview - -1.1 Why not LSP? -================ - -The Language Server Protocol (LSP, <https://langserver.org>) supports an -external language parser, as Ada mode does, and it is supported by the -GNU ELPA package eglot. Ada mode does not use LSP mostly for historical -reasons; the Ada mode parser was first developed before LSP was started. -In addition, LSP does not support some of the navigation information -provided by the Ada mode parser (although that could be provided as a -custom command). - - We may investigate supporting an LSP parser in the future. In -particular, the AdaCore Gnat Studio editor uses an LSP parser for -several functions; Emacs Ada mode could use that as a backend if it -supports LSP. - - -File: ada-mode.info, Node: Installation, Next: Customization, Prev: Overview, Up: Top - -2 Installation -************** - -Ada mode requires Emacs 25.3 or greater. Compiling the Ada code for the -external process parser requires GNAT GPL 2017 or later; tested with -GNAT Community Edition 2021 and GNAT Pro 22.2 (*note Known versions::). - - Ada mode is distributed in the Gnu ELPA package archive; it can be -installed via 'M-x list-packages' (*note (emacs)Packages::). Note that -it requires the 'wisi' and 'uniquify-files' packages as dependencies. - - In Emacs < 27 you must first enable packages in your '~/.emacs', -_after_ customizing 'Info-default-directory-list' (if you do that): - - (package-initialize) - - To see what version of Ada mode you have installed, invoke 'M-x -ada-mode-version'. - - You must also install the associated Ada executables (for the -language parser). You may want to install the Ada Reference Manual in -info format, via the ELPA package ada-ref-man. - -* Menu: - -* Ada executables:: -* Known versions:: - - -File: ada-mode.info, Node: Ada executables, Next: Known versions, Up: Installation - -2.1 Ada executables -=================== - -Ada mode requires the external parser, which must be compiled. - - Ada mode has support for an external cross reference tool -'gpr_query', which uses compiler-generated information. In the case of -Ada, the necessary '.ali' files are automatically generated by the -standard compilation process. For other languages, e.g. C, C++, '.gli' -files can be generated using the compiler switch '-fdump-xref'. -'-fdump-xref' is an AdaCore extension, not available in FSF GCC. - - 'gpr_query' is an Ada program, which is distributed as source and -must be built. Its source code is in the 'ada-mode' Gnu ELPA package. - - 'gpr_query' is similar to the AdaCore utility 'gnatxref', but -supports additional queries. - - Both the parser and 'gpr_query' require the 'GNATCOLL' library -provided by AdaCore, distributed with GNAT GPL 2017 or later, and also -available at Github (<https://github.com/AdaCore/gnatcoll>). The parser -builds with the gnatcoll distributed with the gnat compiler. However, -that gnatcoll does not include the xref package, which is required by -'gpr_query'. So we must build gnatcoll xref from sources downloaded -from github. - - The notes below assume that the compiler is installed at '$prefix', -e.g. '/usr/local/gnat-2019', and that '$prefix/bin' is first on the -'PATH'. If you are running Windows, use mingw64 'bash' to run these -commands. - - On some operating systems, we must install gnatcoll-iconv; other -operating systems don't need it. - - On linux, some versions of the 'GNATCOLL.iconv' package (used by -'gpr_query', but not the parser) explicitly require the 'libiconv.so' -library. GNAT provides the 'libiconv.so' library in -'<gnat>/lib64/libiconv.so'. On Debian, that directory is not in the -standard load path, and iconv is provided by glibc, so 'libiconv.so' is -not found on the standard load path. So you must set LD_LIBRARY_PATH, -but only when running 'gpr-query': - - (setq gpr-query-env '("LD_LIBRARY_PATH=/Projects/gnat/pro_19.2/lib64") - - In general, 'gpr_query' should be compiled with the compiler version -that is used to generate the user project '.ali' files; the 'ali' file -format can change with each compiler version. 'gpr_query' creates a -database of cross reference information; that database must be deleted -if the compiler version changes, to force a complete rebuild. - -* Menu: - -* Building GNATCOLL:: -* Building the executables:: - - -File: ada-mode.info, Node: Building GNATCOLL, Next: Building the executables, Up: Ada executables - -2.1.1 Building GNATCOLL ------------------------ - -Download gnatcoll-db from <https://github.com/AdaCore/gnatcoll-db>; -select the latest release branch (or the one that matches your -compiler), click on the "clone or download" button, select "Download -ZIP". - - Similarly, download gnatcoll-bindings from -<https://github.com/AdaCore/gnatcoll-bindings/tree/20.2> (for -gnatcoll-iconv; not needed for GNAT Community 2020 on Windows). - - Then unpack, build, and install the required components. If you are -unsure whether you need to install iconv, skip that step; a later step -will complain if it is needed. - - unzip ~/Downloads/gnatcoll-bindings-20.2.zip - cd gnatcoll-bindings-20.2 - cd iconv - ./setup.py build - ./setup.py install - - unzip ~/Downloads/gnatcoll-db-20.2.zip - cd gnatcoll-db-20.2 - make -C sql - make -C sql install - make -C sqlite - make -C sqlite install - make -C xref - make -C xref install - - -File: ada-mode.info, Node: Building the executables, Prev: Building GNATCOLL, Up: Ada executables - -2.1.2 Building the executables ------------------------------- - -'gpr_query' requires the 'pthread' library. On Windows, this is -available in Mingw64 as package -'mingw64/mingw-w64-x86_64-winpthreads-git'. - - To build and install 'gpr_query' and the parser, assuming the -'ada-mode-6.0.xx' GNU ELPA package is installed: - - cd ~/.emacs.d/elpa/ada-mode-6.0.xx - ./build.sh - ./install.sh - - By default, 'install.sh' installs the executables in the same -directory as the GNAT executable (using 'gprinstall'). If you don't -have write privileges there, or if you want to install somewhere else, -use 'install.sh --prefix=<dir>'. - - 'ada-mode' will use 'gpr_query' and the parser if they are found in -'PATH'. - - -File: ada-mode.info, Node: Known versions, Prev: Ada executables, Up: Installation - -2.2 Known versions -================== - -Here we list GNAT compiler versions that are known to work or not work -with ada-mode. - - There are various ways to get the compiler: -'Community' - Downloaded from <https://www.adacore.com/download>. The version - number is the release year. - - This version is provided by AdaCore, but they do not support users - using it. - -'Pro' - Downloaded from AdaCore via a support subscription. The version - number is the last two digits of the release year, followed by a - patch release digit. - - This version is provided by AdaCore, and they support users using - it. - -'FSF' - Installed via a free software package manager, typically as part of - the "gcc" package. The version number is the same as the gcc - version, something like "10.3.0", possibly followed by a date. - - This version is derived from some AdaCore version, but is typically - not identical to a released version. It may be supported by the - packager. - - Sometimes compiler versions change what code they accept, -particularly in the area of access types. So some compiler versions may -require minor edits of the code; there is a "WORKAROUND" comment in the -code describing the edit required. - - Compiler versions that work: -'Community 2019' - Reports an error about a dangling reference; see WORKAROUND comment - in - '~/.emacs.d/elpa/wisi-i.j.k/sal-gen_unbounded_definite_red_black_trees.adb' - -'Community 2020' - no edits required - -'Pro 20.2' - no edits required - -'FSF 11.1.0' - - Compiler versions that fail: -'FSF gnat 10.2.1 20210110' - ada-mode uses compiler option -gnat2020; that causes bogus failures - with this version of gnat. Reported at - <https://gcc.gnu.org/bugzilla/show_bug.cgi?id=99099> - - -File: ada-mode.info, Node: Customization, Next: Compiling Executing, Prev: Installation, Up: Top - -3 Customizing Ada mode -********************** - -All user-settable Ada mode variables can be set via the menu 'Ada | -Customize'; some can also be set in wisi project files (*note Project -files::). - - To modify a specific variable, you can directly call the function -'customize-variable'; just type 'M-x customize-variable <RET> -VARIABLE-NAME <RET>'. - - Alternately, you can specify variable settings in the Emacs -configuration file, '~/.emacs'. This file is coded in Emacs lisp, and -the syntax to set a variable is the following: - - (setq variable-name value) - - ada-mode variables that you might consider changing: -'Matching end names' - By default, the option 'ada-end-name-optional' is set to 't', which - matches the Ada standard. This is useful for new Ada users. - Experienced users that follow a style guide requiring matching end - names should set this to 't', since that gives better error - correction. - - Some general (non ada-mode) Emacs settings that are useful for Ada -files: - -'context menu' - By default, the context menu is bound to <C-down-mouse-3>, i.e. - control-right-click. <down-mouse-3> is already bound in the global - map; you can override that global binding in the 'ada-mode-hook' - (see below for code). -'other-frame-window-mode' - Ada mode does not provide any 'other-frame' or 'other-window' - variants of user operations. Instead, it is recommended to use the - Gnu ELPA package 'other-frame-window'. -'delete-trailing-whitespace' - Deletes space, tab at end of line and blank lines at end of buffer. -'xref configuration' - 'xref-prompt-for-identifier' - Set to 'nil' to be prompted less when finding definitions or - references. - 'xref-show-xrefs-function' - Determine placement of the window where references are shown. - 'xref-show-definitions-function' - Determine placement of the window where definitions are shown. - 'xref--transient-buffer-mode-map' - keymap used in some xref windows; you may want to disable the - <RET> binding there. -'untabify' - Deletes tab characters that have crept into the file. -'indent-tabs-mode' - Don't insert tab characters when indenting. -'copyright-update' - Updates the copyright date in the file header comment, to the - current year. -'electric-pair-mode' - Insert a matching right paren when you type a left paren. -'hippie-expand' - Bind 'hippie-expand' to a key; it expands the word before point, - using words from current buffer, other buffers, file names, etc; - see 'hippie-expand-try-functions-list'. You can also add - 'wisi-skel-hippie-try' to that list. Note that 'wisi-skel-expand' - is bound to <C-c C-e> (*note Statement skeletons::). -'imenu' - Navigate to subprograms and types by name, from a minibuffer menu. -'speedbar' - Navigate to subprograms and types by name, from a list in a - dedicated window. -'which-func' - Display the current subprogram name in the mode bar. - - The above can all be set by the following code in your '~/.emacs'. -Note that some are functions are added to 'before-save-hook'; they run -just before a buffer is written to disk. Also, the order is important; -ada-mode does not set up the Ada-specific features of imenu and speedbar -unless imenu is loaded first. - - (setq-default indent-tabs-mode nil) - (define-key xref--transient-buffer-mode-map (kbd "RET") 'xref-goto-xref) - (setq xref-prompt-for-identifier nil) ;; only prompt on C-u - (setq xref-show-xrefs-function #'xref--show-defs-buffer-at-bottom) - (setq xref-show-definitions-function #'xref--show-defs-buffer-at-bottom) - - (electric-pair-mode 1) - (require 'imenu) ;; also enables speedbar - (require 'ada-mode) - (add-to-list 'hippie-expand-try-functions-list 'wisi-skel-hippie-try) - (define-key ada-mode-map "\C-e" 'hippie-expand) - (define-key ada-mode-map [down-mouse-3] 'ada-popup-menu) - (add-hook 'ada-mode-hook - (lambda () - (add-hook 'before-save-hook 'delete-trailing-whitespace nil t) - (add-hook 'before-save-hook 'copyright-update nil t) - (add-hook 'before-save-hook - (lambda () (untabify (point-min) (point-max))) - nil t))) - -* Menu: - -* Slow response:: -* Non-standard file names:: -* Other compiler:: -* Other cross-reference:: -* Other customization:: - - -File: ada-mode.info, Node: Slow response, Next: Non-standard file names, Up: Customization - -3.1 Slow response -================= - -In large files, parsing takes a noticable amount of time, so it gets in -the way of interactive typing due to immediate fontification triggering -a parse. - - There are three ways to deal with this: - - 1. Set 'wisi-partial-parse-threshold' In your '~./emacs': - - (setq wisi-partial-parse-threshold 100001) - - The default value (100001) may already be appropriate; it depends - on how fast your machine is, and what your tolerance for slow - response is. - - Files larger than 'wisi-partial-parse-threshold' (in characters) - will be parsed partially; only the part of the buffer needed for - the current task will be parsed. For fontification, that is the - visible part. For indent, it is approximately the current - subprogram or package. For navigation, it is always the entire - file, which will still be slow; that is the only way to ensure - useful results. - - With this setting, indentation may not be correct; the Ada menu - entry "Edit | Indent containing statement" will indent correctly. - - 2. Delay fontification by setting 'jit-lock-defer-time' in your - '~./emacs': - - (setq jit-lock-defer-time 1.5) - - This is a global setting; it affects all buffers. Fontification - will only be performed after you have stopped typing for the - indicated number of seconds. - - 3. Turn off parsing for fontification by setting 'wisi-disable-face' - in your '~./emacs' - - (setq wisi-disable-face t) - - This turns of fontification for type, package, and function names; - only Ada reserved words are fontified. - - -File: ada-mode.info, Node: Non-standard file names, Next: Other compiler, Prev: Customization, Up: Customization - -3.2 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 '.ads' and '.adb', -respectively. - - Emacs uses the file extension to enable Ada mode; Ada mode uses the -file extentions to allow moving from a package body to the corresponding -spec and back. - - Emacs and Ada mode support ways to use alternative file extensions -for specs and bodies. Note that you must also tell the compiler about -these extensions in a GNAT project file Naming package; doing that is -beyond the scope of this manual. - - For instance, if your spec and bodies files are called 'UNIT_s.ada' -and 'UNIT_b.ada', respectively, you can add the following to your -'.emacs' file: - - ;; Tell Ada mode about spec and body extensions - (ada-add-extensions "_s.ada" "_b.ada") - - ;; Tell Emacs to use Ada mode for those extensions - (add-to-list 'auto-mode-alist '("\\.ada\\'" . ada-mode)) - - You can define additional extensions: - - (ada-add-extensions ".ads" "_b.ada") - (ada-add-extensions ".ads" ".body") - - This means that whenever Ada mode looks for the body for a file whose -extension is '.ads', it will take the first available file that ends -with either '.adb', '_b.ada' or '.body'. - - Simililarly, if Ada mode is looking for a spec, it will look for -'.ads' or '_s.ada'. - - If the filename excluding the extension is not derived from the Ada -name following the GNAT convention, you need to provide an alternate -function for 'ada-file-name-from-ada-name'. Doing that is beyond the -scope of this manual; see the current definitions in 'ada-mode.el' and -'ada-gnat-xref.el' for examples. - - -File: ada-mode.info, Node: Other compiler, Next: Other cross-reference, Prev: Non-standard file names, Up: Customization - -3.3 Other compiler -================== - -The wisi project variable 'ada_compoiler' (default elisp variable -'ada-compiler') (default ''gnat') controls dispatching in -compiler-specific functions for corresponding Ada mode operations. - - To use a compiler other than GNAT, you must write Emacs lisp code -that provides the interface to the compiler, and set 'ada-compiler' and -the indirection variables. - - See 'ada-compiler-gnat.el' for an example. - - -File: ada-mode.info, Node: Other cross-reference, Next: Other customization, Prev: Other compiler, Up: Customization - -3.4 Other cross-reference -========================= - -The wisi project variable 'xref_tool' (default elisp variable -'ada-xref-tool') controls dispatching in the -cross-reference-tool-specific functions for corresponding Ada mode -operations. - - If 'gpr_query' is found in 'PATH', the default cross-reference tool -is 'gpr_query'; otherwise it is 'gnatxref'. - - To use a cross reference tool other than the above, you must write -Emacs lisp code that provides the interface to the tool, and set -'ada-xref-tool' and the indirection variables. - - See 'ada-gnat-xref.el' and 'gpr-query.el' for examples. - - -File: ada-mode.info, Node: Other customization, Prev: Other cross-reference, Up: Customization - -3.5 Other customization -======================= - - -File: ada-mode.info, Node: Compiling Executing, Next: Project files, Prev: Customization, Up: Top - -4 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 -(*note Project files::), but the defaults are sufficient for using the -GNAT compiler for simple projects (single files, or several files in a -single directory). - - For complex projects, you will want to use 'make' or some other build -tool; in that case, you may need a wisi project file to tell Emacs about -the project directory tree and other settings. - -* Menu: - -* Compile commands:: -* Compiling Examples:: -* Compiler errors:: - - -File: ada-mode.info, Node: Compile commands, Next: Compiling Examples, Prev: Compiling Executing, Up: Compiling Executing - -4.1 Compile commands -==================== - -Here are the commands for building an Ada project and running the main -program; they are all on the 'Ada | Build' menu. - - In multi-file projects, there must be one file that is the main -program. That is given by the 'main' project file variable; it defaults -to the current file if not yet set, but is also set by the "set main and -build" command. - -'Check file' - Compiles the current file in syntax check mode, by running - '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 'main' only if it has not been set yet. - -'Compile file' - Compiles the current file, by running 'comp_cmd' from the current - project file. - - This does not set 'main'. - -'Set main and Build' - Sets 'main' to the current file, then executes the Build command. - -'Show main' - Displays 'main' in the message buffer. - -'Build' - Compiles all obsolete units of the current 'main', and links - 'main', by running 'make_cmd' from the current project. - - This sets 'main' only if it has not been set yet. - -'Run' - Executes the main program in a shell, displayed in a separate Emacs - buffer. This runs '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 'C-u' before invoking the command. - - This command is not available for a cross-compilation toolchain. - - It is important when using these commands to understand how 'main' is -used and changed. - - Build runs 'gprbuild' 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 '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, '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 two ways to change 'main': - - 1. Invoke 'Ada | Set main and Build', which sets 'main' to the current - file. - - 2. Invoke 'Ada | Project | Load', and load a project file that - specifies 'main' - - -File: ada-mode.info, Node: Compiling Examples, Next: Compiler errors, Prev: Compile commands, Up: Compiling Executing - -4.2 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 *Note 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 wisi project file:: -* Use multiple GNAT project files:: -* Use a Makefile:: - - -File: ada-mode.info, Node: No project files, Next: Set compiler options, Prev: Compiling Examples, Up: Compiling Examples - -4.2.1 No project files ----------------------- - -This example uses no project files. - - First, create a directory 'Example_1', containing: - - 'hello.adb': - - with Ada.Text_Io; - procedure Hello - is begin - Put_Line("Hello from hello.adb"); - end Hello; - - Yes, this is missing "use Ada.Text_Io;" - we want to demonstrate -compiler error handling. - - 'hello_2.adb' has no errors: - - with Hello_Pkg; - procedure Hello_2 - is begin - Hello_Pkg.Say_Hello; - end Hello_2; - - 'hello_pkg.ads' has no errors: - - package Hello_Pkg is - procedure Say_Hello; - end Hello_Pkg; - - 'hello_pkg.adb': - - 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; - - Yes, this is missing the keyword 'body'; another compiler error -example. However, note that the indentation engine parser accepts this -code, making it possible to indent illegal Ada code. - - In buffer 'hello.adb', invoke the menu entry 'Ada | Build | Check -syntax'. You should get a '*compilation*' buffer containing something -like (the directory paths will be different): - - -*- mode: compilation; default-directory: "c:/Projects/org.emacs.ada-mode.stephe-1/test/Example_1/" -*- - Compilation started at Fri Oct 18 04:23:54 - - gprbuild -u -c -gnatc c:/Projects/org.emacs.ada-mode/test/Example_1/hello.adb - using project file D:\Apps\GNAT-gpl_2019\share\gpr\_default.gpr - Compile - [Ada] hello.adb - hello.adb:4:04: "Put_Line" is not visible - hello.adb:4:04: non-visible declaration at a-textio.ads:263 - hello.adb:4:04: non-visible declaration at a-textio.ads:259 - gprbuild: *** compilation phase failed - - Compilation exited abnormally with code 4 at Fri Oct 18 04:23:54 - - The lines with actual errors (starting with 'hello.adb') are -highlighted, with the file name in red. - - Now invoke 'Ada | Build | Next compilation error'. Or you can click -the middle mouse button on the first error line, or use the key binding -shown on the menu. In the compilation buffer, a triangle is placed in -the left fringe on the first error line, and point is put at the place -of the error in the 'hello.adb' buffer. - - To fix the error, invoke 'Ada | Build | Fix compilation error'; this -adds "Ada.Text_Io." to the line: - - Ada.Text_Io.Put_Line ("hello from hello.adb"); - - Now invoke 'Ada | Build | Show main'; this displays 'Ada mode main: -hello'. - - Now (in buffer 'hello.adb'), invoke 'Ada | Build | Build'. You are -prompted to save the file (if you haven't already). Then the -compilation buffer is displayed again, containing: - - -*- mode: compilation; default-directory: "c:/Projects/org.emacs.ada-mode.stephe-1/test/Example_1/" -*- - Compilation started at Fri Oct 18 20:39:33 - - gprbuild hello - using project file D:\Apps\GNAT-gpl_2019\share\gpr\_default.gpr - Compile - [Ada] hello.adb - Bind - [gprbind] hello.bexch - [Ada] hello.ali - Link - [link] hello.adb - - Compilation finished at Fri Oct 18 20:39:34 - - The compilation has succeeded without errors; 'hello.exe' now exists -in the same directory as 'hello.adb'. - - Now invoke 'Ada | Build | Run'. The '*compilation*' buffer is -displayed, containing - - -*- mode: compilation; default-directory: "c:/Projects/org.emacs.ada-mode.stephe-1/test/Example_1/" -*- - Compilation started at Fri Oct 18 20:41:53 - - ./hello - Hello from hello.adb - - Compilation finished at Fri Oct 18 20:41:53 - - That completes the first part of this example. - - Now we will compile a multi-file project. Open the file -'hello_2.adb', invoke 'Ada | Build | Set main and Build'. This finds an -error in 'hello_pkg.adb': - - hello_pkg.adb:2:08: keyword "body" expected here [see file name] - - This demonstrates that gprbuild finds the files needed by the main -program. However, it cannot find files in a different directory, unless -you use a GNAT project file to specify the other directories; *note Set -source search path::. - - Invoke 'Ada | Build | Show main'; this displays 'Ada mode main: -hello_2'. - - Move to the error with 'C-x `', and fix the error by adding 'body': - - package body Hello_Pkg is - - Now, while still in 'hello_pkg.adb', invoke 'Ada | Build | Build'. -gprbuild successfully builds 'hello_2'. This demonstrates that Emacs -has remembered the main file, in the project variable 'main', and used -it for the Build command. - - Finally, again while in 'hello_pkg.adb', invoke 'Ada | Build | Run'. -The '*compilation*' buffer displays 'Hello from hello_pkg.adb'. - - One final point. If you switch back to buffer 'hello.adb', and -invoke 'Ada | Build | Run', 'hello_2.exe' will be run. That is because -'main' is still set to 'hello_2', as you can see when you invoke 'Ada | -Build | Show main'. - - There are two ways to change 'main': - - 1. Invoke 'Ada | Build | Set main and Build', which sets 'main' to the - current file. - - 2. Invoke 'Ada | Build | Set Project ...', and select a project file - that specifies 'main'. - - -File: ada-mode.info, Node: Set compiler options, Next: Set source search path, Prev: No project files, Up: Compiling Examples - -4.2.2 Set compiler options --------------------------- - -This example illustrates using a gnat project file to set a compiler -option. - - If you have files from 'Example_1' open in Emacs, you should close -them so you don't get confused. Use menu 'File | Close (current -buffer)'. - - In directory 'Example_2', create these files: - - 'hello.adb': - - with Ada.Text_Io; - procedure Hello - is begin - Put_Line("Hello from hello.adb"); - end Hello; - - This is the same as 'hello.adb' from 'Example_1'. It has two errors; -missing "use Ada.Text_Io;", and no space between 'Put_Line' and its -argument list. - - 'hello.gpr': - - project Hello is - package Compiler is - for Default_Switches ("Ada") use ("-gnatyt"); - end Compiler; - end Hello; - - This tells the GNAT compiler to check for token spacing; in -particular, there must be a space preceding a parenthesis. - - In buffer 'hello.adb', invoke 'Ada | Build | Set main and Build'. -This finds the project file 'hello.gpr', uses it to set the compiler -options, and builds the project. You should get a '*compilation*' -buffer containing something like (the directory paths will be -different): - - gprbuild -Phello.gpr hello - Compile - [Ada] hello.adb - hello.adb:4:04: "Put_Line" is not visible - hello.adb:4:04: non-visible declaration at a-textio.ads:508 - hello.adb:4:04: non-visible declaration at a-textio.ads:498 - hello.adb:4:12: (style) space required - gprbuild: *** compilation phase failed - - Compare this to the compiler output in *note No project files::; the -compiler-provided default gpr file has been replaced by 'hello.gpr', and -an additional error is reported in 'hello.adb' on line 4. This shows -that 'hello.gpr' is being used to set the compiler options. - - Use 'C-x`', 'C-c M-`' to fix the errors, then 'Ada | Build | Build' -and 'Ada | Build | Run' to build and run. - - -File: ada-mode.info, Node: Set source search path, Next: Use wisi project file, Prev: Set compiler options, Up: Compiling Examples - -4.2.3 Set source search path ----------------------------- - -In this example, we show how to deal with files in more than one -directory, setting the source search path in the gpr file. - - Create the directory 'Example_3', containing: - - 'hello_pkg.ads': - - package Hello_Pkg is - procedure Say_Hello; - end Hello_Pkg; - - 'hello_pkg.adb': - - 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; - - These are the same files from example 1; 'hello_pkg.adb' has an error -on line 2. - - 'other.gpr': - - project Other is - for Source_Dirs use (".", "Other"); - end Other; - - In addition, create a directory 'Example_3/Other', containing this -file: - - 'Other/hello_3.adb': - - 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; - - There are no errors in this file. - - In buffer 'hello_3.adb', invoke 'Ada | Project files | Find and -select project...', and select 'Example_3/other.gpr'. This tells Emacs -Ada mode to stop using the project file from 'Example_2', and use the -one for 'Example_3'. Also note that since this project file is not -named 'hello_3.gpr', it would not be found by default. - - Then, again in 'hello_3.adb', invoke 'Ada | Set main and Build'. You -should get a '*compilation*' buffer containing something like (the -directory paths will be different): - - gprbuild -Pother.gpr hello_3 - Compile - [Ada] hello_3.adb - [Ada] hello_pkg.adb - hello_pkg.adb:2:08: keyword "body" expected here [see file name] - gprbuild: "C:\Examples\Example_3\hello_pkg.adb" compilation error - - Move to the error with 'C-x `'. Ada mode searches the list of -directories given by 'Source_Dirs' for the file mentioned in the -compiler error message. - - Use 'C-x`', 'C-c M-`' to fix the errors, then 'Ada | Build | Build' -and 'Ada | Build | Run' to build and run. - - -File: ada-mode.info, Node: Use wisi project file, Next: Use multiple GNAT project files, Prev: Set source search path, Up: Compiling Examples - -4.2.4 Use wisi project file ---------------------------- - -In this example, we show how to use a wisi project file to set some -options that cannot be set in a gpr project file. In addition, we -change a setting so you are prompted for a project file, rather than -using a default one. - - Change the setting: - - M-x set-variable ada-build-prompt-prj search-prompt - - Create the directory 'Example_4', containing: - - 'hello_pkg.ads': - - package Hello_Pkg is - procedure Say_Hello; - end Hello_Pkg; - - 'hello_pkg.adb': - - with Ada.Text_Io; - package body Hello_Pkg is - procedure Say_Hello - is begin - Put_Line ("Hello from hello_pkg.adb"); - end Say_Hello; - end Hello_Pkg; - - These two files are the similar to files from example 1; -'hello_pkg.adb' has an error on line 5 (missing "Ada.Text_IO."). - - 'example_4.prj': - - -- Wisi project file - - gpr_project_path=More - - gpr_file=example_4.gpr - - casing=example_4.casing - - 'example_4.prj' is a wisi project file; it specifies the -'gpr_project_path', telling 'gprbuild' where to search for gpr files, -and specifies the gpr file to use. Finally it specifies a casing -exception file: - - 'example_4.casing': - - Text_IO - - The default auto casing rules in ada-mode state that the Ada package -"Ada.Text_IO" should be capitalized as "Ada.Text_Io", which does not -match the Ada Reference Manual. 'example_4.casing' specifies that -instead "Text_IO" should be capitalized as shown. - - You can create a casing exception by editing the file directly, or -via the 'Ada | Casing' menu. - - 'gpr_project_path' and 'casing' are list variables; each occurence in -a wisi project file adds an entry to the list. - - In addition, create a directory 'Example_4/More', containing these -files: - - 'more/hello_4.adb': - - 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; - - There are no errors in this file, except for the casing in -"Ada.Text_Io". - - 'More/example_4.gpr': - - project Example_4 is - for Source_Dirs use (".", ".."); - - package Compiler is - for Default_Switches ("Ada") use ("-gnatyknpr"); - end Compiler; - end Example_4; - - The compiler switch checks all casing; we will get errors for -"Ada.Text_Io". - - Then, in 'hello_4.adb', invoke 'Ada | Set main and Build'. ada-mode -looks for a project file 'hello_4.prj' or 'hello_4.gpr'; since neither -is found, you are prompted to find a project file. Select -'Example_4/example_4.prj'; that is parsed and selected, and the build -continues. - - You should get a '*compilation*' buffer containing something like -(the directory paths will be different): - - gprbuild -Pexample_4.gpr hello_4 - Compile - [Ada] hello_pkg.adb - hello_pkg.adb:1:16: (style) bad casing of "Text_IO" declared at a-textio.ads:57 - hello_pkg.adb:5:07: "Put_Line" is not visible - hello_pkg.adb:5:07: non-visible declaration at a-textio.ads:508 - hello_pkg.adb:5:07: non-visible declaration at a-textio.ads:498 - gprbuild: *** compilation phase failed - - When you fix the errors, note that 'C-c M-`' inserts the correct case -for "Ada.Text_IO", and corrects the case where it is incorrect. The -case is also corrected as you type; you can type "ada.text_io." and the -case will be corrected when you type each "." or "_". - - -File: ada-mode.info, Node: Use multiple GNAT project files, Next: Use a Makefile, Prev: Use wisi project file, Up: Compiling Examples - -4.2.5 Use multiple GNAT project files -------------------------------------- - -In this example, we show how to use multiple GNAT project files, -specifying the GNAT project search path in an Ada mode project file. -This also requires explicitly setting 'project-find-functions'. - - If you haven't already, create the directory 'Example_4' as specified -in *note Use wisi project file::. If you've already created it and run -the tutorial, restore the compilation error in hello_pkg.adb; delete -'Ada.Text_IO.' in front of 'Put_Line'. - - Create the directory 'Example_5', containing: - - 'hello_5.adb': - - with Hello_Pkg; - with Ada.Text_IO; use Ada.Text_IO; - procedure Hello_5 - is begin - Hello_Pkg.Say_Hello; - Put_Line ("From hello_5"); - end Hello_5; - - There are no errors in this file. - - 'hello_5.prj': - - gpr_project_path=../Example_4/More - gpr_file=hello_5.gpr - - casing=../Example_4/example_4.casing - - 'hello_5.gpr': - - with "example_4"; - project Hello_5 is - for Source_Dirs use ("."); - package Compiler is - for Default_Switches ("Ada") use ("-g", "-gnatyknprt"); - end Compiler; - end Hello_5; - - In buffer 'hello_5.adb', invoke 'Ada | Project | Find and select -project...', and select 'Example_5/hello_5.prj'. This would also be -found by default if no previous project file had been selected. Note -that if 'example_5.gpr' were named 'hello_5.gpr', the project file -search would find more than one match, causing an error. - - Then, again in 'hello_5.adb', invoke 'Ada | Build | Set main and -Build'. You should get a '*compilation*' buffer containing something -like (the directory paths will be different): - - -*- mode: compilation; default-directory: "c:/Projects/org.emacs.ada-mode/test/Example_5/" -*- - Compilation started at Mon Oct 21 11:32:05 - - gprbuild -Pexample_5.gpr hello_5 - Compile - [Ada] hello_5.adb - [Ada] hello_pkg.adb - hello_pkg.adb:5:07: "Put_Line" is not visible - hello_pkg.adb:5:07: non-visible declaration at a-textio.ads:508 - hello_pkg.adb:5:07: non-visible declaration at a-textio.ads:498 - gprbuild: *** compilation phase failed - - Now type 'C-x `'; 'Example_4/hello_pkg.adb' is shown, demonstrating -that 'hello_5.gpr' and 'hello_4.gpr' are being used to set the -compilation search path. - - Now, in buffer 'hello_pkg.adb' invoke the menu 'Ada | Navigate | Find -file in project' (which calls 'ada-find-file') to get back to the -'hello_5.adb' buffer. If you have not selected any project files -previously in this emacs session, this gives an unexpected prompt for a -"project directory". Kill that with 'C-g'. Otherwise, enter 'hel <tab> -5 <tab>'; it will say "no match". - - The problem here the way Emacs projects work. To find the current -project, the functions in 'project-find-functions' are run; one should -return a project. The ada-mode build functions add -'wisi-prj-find-dominating-cached' to 'project-find-functions'; that -looks in the current directory tree for a project file with the same -name as one that was previously selected. - - If 'Example_5' is the only project in the current emacs session, -'wisi-prj-find-dominating-cached' finds no project file (because -'Example_4' is not a child directory of 'Example_5'), so the default -strategy of "ask the user" is used, giving the prompt for a directory. - - If 'Example_4' is also a project in the current emacs session, -'wisi-prj-find-dominating-cached' finds that; since it does not contain -'hello_5.adb', 'ada-find-file' cannot find it. - - Any time you have a main project that depends on other projects that -are not in the same directory tree, you will have this problem. - - The fix is to use a different function in 'project-find-functions'; -'wisi-prj-current-cached'. This uses a global variable to indicate what -the current project is. wisi provides four different functions for -'project-find-functions'. *Note Selecting projects: (wisi)Selecting -projects. - - To change 'project-find-functions', execute: - - M-: (remove-hook 'project-find-functions 'wisi-prj-find-dominating-cached) - M-: (add-hook 'project-find-functions 'wisi-prj-current-cached) - - Normally, you must set 'project-find-functions' in your '~/.emacs', -using the 'add-hook' function. The ada-mode Build menu functions set it -for you to make things simpler for novices, but they do not change it if -you have put one of the wisi functions on it. - - Now set the current project; invoke 'Ada | Project | Find and select -project...', and select 'Example_5/hello_5.prj'. Then in -'hello_pkg.adb', invoke 'Ada | Navigate | Find file in project'; now we -can find 'hello_5.adb'. - - -File: ada-mode.info, Node: Use a Makefile, Prev: Use multiple GNAT project files, Up: Compiling Examples - -4.2.6 Use a Makefile --------------------- - -In this example, we show how to use a Makefile to build an Ada project -with GNAT, run the result, and clean the build directories. - - Create the directories 'Example_4, Example_5' as specified in *note -Use wisi project file::, *note Use multiple GNAT project files::. - - In 'Example_5', add the file: - - 'Makefile': - - # build and run hello_5 project - - all : build run - - .PHONY : force - - build : force - gprbuild -PExample_5.gpr hello_5 - - run : - ./hello_5 - - clean : - gnatclean -r -PExample_5 - - # Local Variables: - # eval:(unless (wisi-prj-find-function-set-p)(add-hook 'project-find-functions 'wisi-prj-current-cached)) - # eval:(wisi-prj-dtrt-parse-file "hello_5.prj" (ada-prj-default "hello_5 # main") "Makefile") - # End: - - Tell Emacs to allow 'eval' in 'Local Variables': - M-: (setq enable-local-eval t) - - Close and re-open 'Makefile'; the 'Local Variables' section sets the -project file to 'hello_5.prj' when the 'Makefile' is opened. - - If you have set 'project-find-functions' in your '~/.emacs', you can -leave out the first 'eval' line. Note that 'wisi-prj-dtrt-parse-file' -does the right thing depending on which wisi function is in -'project-find-functions'. - - In 'Makefile', invoke 'Tools | Compile...', and accept the default -make command. This runs the 'all' target, which builds 'hello_5' and -runs it (you may have to fix source errors first, depending on how fresh -the Example_4 directory is). - - -File: ada-mode.info, Node: Compiler errors, Prev: Compiling Examples, Up: Compiling Executing - -4.3 Compiler errors -=================== - -The 'Check syntax' and 'Build' commands, or running 'make', place -compilation errors in a separate buffer named '*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 -<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 'C-x `' key ('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 also include references to other files. These -references are accessed via 'C-c `'. - - -File: ada-mode.info, Node: Project files, Next: Moving Through Ada Code, Prev: Compiling Executing, Up: Top - -5 Project files -*************** - -Ada mode uses wisi project files; *note Project files: (wisi)wisi. - - A wisi 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. - - The default file extension for wisi project files is '*.adp' or -'*.prj'. You can use a different extension by adding it to -'ada-prj-file-extensions', and a different syntax by adding a parser -function to 'ada-prj-parser-alist'. - - Note that wisi project files are different than GNAT compiler project -files ('*.gpr'). However, Emacs Ada mode can use a GNAT project file to -specify the project directories. If no other customization is needed, a -GNAT project file can be used without a wisi project file. - - If no wisi project file is specified, some Ada mode functions are not -available. - -* Menu: - -* Project file overview:: -* Project file variables:: - - -File: ada-mode.info, Node: Project file overview, Next: Project file variables, Prev: Project files, Up: Project files - -5.1 Project file overview -========================= - -The current project file is shown by the menu command <Ada | Project -Files | Show project>. - - To set the project file, use the menu command <Ada | Project Files | -Find and select Project ...>, or one of the elisp functions described in -*note Selecting Projects: (wisi)wisi. - - The project file may also be a GNAT project file (with file extension -is '.gpr'). - - -File: ada-mode.info, Node: Project file variables, Prev: Project file overview, Up: Project files - -5.2 Project file variables -========================== - -Some project variables have defaults that can be changed by setting -elisp variables; the table below identifies the elisp variable for each -project variable. Elisp variables corresponding to project variables -that are lists are elisp lists. - - wisi defines some project variables, Ada mode defines some, others -are defined by the compiler and the cross reference tool. - - Here is the list of variables valid defined by wisi and Ada mode. In -the default values, the current directory '"."' is the directory -containing the project file. - -'ada_compiler' [default: 'ada-compiler, gnat'] - Ada compiler for this project. - - Setting this in the project file reinitializes all options for the - xref tool, so it must occur before any compiler-specific project - variable. - -'casing' - List of files containing casing exceptions. *Note Automatic - casing: Automatic casing. - -'gnat-stub-args' - List of strings passed to 'gnat stub' when it is run. - -'gnat-stub-cargs' - List of strings passed to 'gnat stub' after '-cargs'. - -'obj_dir' - A list of directories to search for object and cross-reference - files. Only needed if you are not using GPR files. - -'src_dir' - A list of directories to search for source files. Added to the - source directories from a gpr file (if any). - -'xref_tool' [default: 'ada-xref-tool'] - Cross reference tool for this project. - - Setting this in the project file reinitializes all options for the - xref tool, so it must occur in the project file before any other - settings that affect the xref tool. - - If 'gpr_query' is found in 'PATH', 'ada-xref-tool' defaults to - ''gpr_query'. Otherwise, it defaults to ''gnat', which uses 'gnat - find'. - - The following project file variables are defined by the GNAT -compiler: - -'ada_project_path' [default: ] - Same as 'gpr_project_path'; see below. - -'gpr_file' [default: ] - The GNAT project file for the project. - - If set, the source and project directories specified in the GNAT - project file are appended to 'src_dir' and 'gpr_project_path'. - This allows specifying Ada source directories with a GNAT project - file, and other source directories with the Emacs project file. - -'gpr_project_path' [default: ] - A list of directories to search for GNAT project files. The list - is passed to tools via the 'GPR_PROJECT_PATH' process environment - variable in the process used to run the 'gnat' and 'gpr_query' - tools. - - If not set, 'GPR_PROJECT_PATH' in the child process is inherited - from the Emacs process. - -'runtime' [default: ] - If set, the name of the runtime, used as the value of the 'RTS' - command line option for tools. - -'target' [default: 'nil'] - If set, the name of the cross-compilation target, prepended to the - 'gnat' executable name. - - The following project variables are used by the 'Ada | Build' menu -commands: - -'check_cmd' [default: 'ada-build-check-cmd'] - Compiler commannd to syntax check a single file. - -'main' [default: basename of current file name] - File name of executable to build. - -'make_cmd' [default: 'ada-build-make-cmd'] - Command to compile and link the application. - -'run_cmd' [default: 'ada-build-run-cmd'] - Command to run the application. - - -File: ada-mode.info, Node: Moving Through Ada Code, Next: Identifier completion, Prev: Project files, Up: Top - -6 Moving Through Ada Code -************************* - -There are several commands to navigate through Ada code. All these -functions are available through the Ada menu and keybindings. - - Some of these commands rely on cross reference facilities provided by -the compiler; the standard Emacs Ada mode only supports the GNAT -compiler, but others can be added (*note Other cross-reference::). - -'C-c C-d' - Move from any use of an identifier to its declaration, for from a - declaration to its body (if there is one). - - This runs 'xref-find-definitions', which has a default global - binding of <M-.> - -'C-c M-d' - Move from a child type declaration to the parent type declaration; - display a list of references if there is more than one parent. - -'C-c C-n' - Move to the next keyword in the current statement. - - For example, if point is on 'if', move to 'then'. - - This runs 'forward-sexp', which has a default global binding of - 'C-M-f'. - -'C-c C-p' - Move to the previous keyword in the current statement. - - For example, if point is on 'then', move to 'if'. - - This runs 'backward-sexp', which has a default global binding of - 'C-M-b'. - -'C-c C-o' - Switch between corresponding spec and body. There are several - special cases: - - * If the region is active, it is assumed to contain an Ada - package name; position point on the corresponding package - declaration. - - * If point is in the start line of a top level child package - declaration (but not package body), or a child subprogram spec - or body, position point on the corresponding parent package - declaration. - - * If point is in the start line of a top level separate body, - position point on the corresponding separate stub declaration. - - * If point is in a subprogram declaration or body, position - point on the corresponding body or declaration in the other - file. - - * If point is on a 'with' clause, position point on the - corresponding declaration. - -'C-c C-r' - Show all references to the identifier surrounding point. Use 'C-x - `' ('next-error') to visit each reference (as for compilation - errors). - -'C-c C-x' - Show all declarations that override the primitive procedure at - point. Use 'C-x `' ('next-error') to visit each reference (as for - compilation errors). - -'C-c M-x' - Show the declaration that the declaration at point overrides. - -'C-u SPACE' - Jump back to the previous location. - -'Ada | Misc | Refresh cross reference cache' - Cross reference information is loaded from the compiler output when - the first cross reference command is issued (or when the project - file is parsed, if useing cached project files). If the code is - recompiled after that, the cross reference information is reloaded - by invoking this menu command. - - -File: ada-mode.info, Node: Identifier completion, Next: Indentation, Prev: Moving Through Ada Code, Up: Top - -7 Identifier completion -*********************** - -Emacs provides two general ways of completing identifiers while typing: -'M-/' (bound to 'dabbrev-expand'), and 'M-tab' (bound to -'complete-symbol'. - - This is an easy way to type faster: you just have to type the first -few letters of an identifier, and then loop through all the possible -completions. - - 'complete-symbol' completes on all the symbols defined in the current -project, as returned by 'gpr_query'. For a procedure declared as: - - package Package_Name is - procedure Procedure_Name (args); - - the completion string looks like: - - Procedure_Name(args)<Package_Name<line>> - - so for example you can type "iterate<wisitok" to complete on -WisiToken iterators, or "add(Data" to complete on all subprograms whose -name starts with "add" and whose first argument starts with "Data". - - If you have bound 'hippie-expand', that also uses 'dabbrev-expand'. - - 'dabbrev-expand' completes on all words in all open Ada files for -possible completions, using simple Emacs syntax-class parsing. - - For instance, if the words 'my_identifier' and 'my_subprogram' are -the only words starting with 'my' in any of the open Ada files, then you -will have this scenario: - - You type: myM-/ - Emacs inserts: 'my_identifier' - If you press M-/ once again, Emacs replaces 'my_identifier' with - 'my_subprogram'. - Pressing M-/ once more will bring you back to 'my_identifier'. - - This is a very fast way to do completion, and the casing of words -will also be respected. - - Another place where identifier completion is used in the -'xref-find-definitions' (<C-u M-.>) and 'wisi-goto-spec/body' (<C-u C-c -C-d>) commands; these complete on all symbols in the project (provided -by 'gpr_query'). With two 'C-u', the completion is limited to symbols -defined in the current file. - - Note that in Ada, for subprograms that have a specification in the -'.ads' file and a body in the '.adb' file, <C-u C-u C-c C-d> returns the -spec location only, so it will not find the function if invoked in the -'.adb' file. - - -File: ada-mode.info, Node: Indentation, Next: Statement skeletons, Prev: Identifier completion, Up: Top - -8 Indentation -************* - -Ada mode comes with a full set of rules for automatic indentation. You -can also configure the indentation, via the following variables: - -'ada-indent' (default value: 3) - Number of columns for default indentation. - -'ada-indent-after-trailing-comment' (default value t) - If t, align comment lines imediately following a comment on the - same line as code with the preceding comment. Otherwise, ignore - the preceding comment. - -'ada-indent-broken' (default value: 2) - Number of columns to indent the continuation of a broken line. - -'ada-indent-comment-col-0' (default value: nil) - If non-nil, comments currently starting in column 0 are left in - column 0. Otherwise, they are indented with previous comments or - code. - -'ada-indent-comment-gnat' (default value: nil) - If non-nil, comments are indented to meet the GNAT style check; one - of: - * multiple of 'ada-indent' - * next non-blank line - * previous non-blank line - - Otherwise, they are indented with previous comments or code. - -'ada-indent-label' (default value: -3) - Number of columns to indent a label. - -'ada-indent-record-rel-type' (default value: 3) - Indentation for 'record' relative to 'type' or 'use'. - -'ada-indent-renames' (default value: 2) - Indentation for 'renames' relative to the matching subprogram - keyword. - - If the subprogram has parameters then if 'ada-indent-renames' is - zero or less the indentation is abs 'ada-indent-renames' relative - to the open parenthesis; if 'ada-indent-renames' is one or more the - indentation is relative to the line containing the keyword. - - If the subprogram has no parameters then 'ada-indent-broken' the - indentation is relative to the indentation of the line containing - the keyword. - -'ada-indent-return' (default value: 0) - Indentation for 'return' relative to the matching 'function'. - - If the function has parameters, then if 'ada-indent-return' is zero - or less the indentation is abs 'ada-indent-return' relative to the - open parenthesis; if 'ada-indent-return' is one or more, - indentation is relative to line containing 'function'. - - If the function has no parameters, 'ada-indent-broken' is used - relative to line containing 'function'. - -'ada-indent-use' (default value: ada-indent-broken) - Indentation for the lines in a 'use' statement. - -'ada-indent-when' (default value: 3) - Indentation for 'when' relative to 'exception', 'case', or 'or' in - 'select'. - -'ada-indent-with' (default value: ada-indent-broken) - Indentation for the lines in a 'with' context clause. - - The indentation variables are buffer local; the global value may be -overridden in an elisp function on 'ada-mode-hook', or in a file local -variable section. - - The following keys indent portions of the text: - -'RET' - Insert and indent a new line. - -'TAB' - Indent the current line, or the current region. - -'C-c TAB' - Indent the current statement or declaration. - -'C-c S-TAB' - Indent the statement or declaration containing the current - statement or declaration. - - The indentation algorithm relies on a grammar parser to identify the -syntactic role for keywords and other words in the code. - - In rare cases, the parser gets confused; it can be reset by invoking -menu <Ada | Misc | Restart parser>. Please report such cases as a bug. - - -File: ada-mode.info, Node: Statement skeletons, Next: Aligning code, Prev: Indentation, Up: Top - -9 Statement skeletons -********************* - -'C-c C-e' expands the previous one or two words into a statement -skeleton. For example, 'i f C-c C-e' expands to: - - if then - elsif then - else - end if; - - For named statements (packages, loops, etc), the name is taken from -the word before point, and the name of the statement from the word -before that. - - Some expansions prompt for more information, such as whether a spec -or body is desired. For example, 'package A_Package C-c C-e' first -prompts for "body" or "spec". If "spec" is selected, the following code -is inserted: - - package A_Package is - private - end A_Package; - - Named blocks work similarly: 'declare A_Block C-c C-e' expands -(without prompting) to: - - A_Block: - declare - begin - exception - end A_Block; - - Note that the order of the keyword 'declare' and the name 'A_Block' -are reversed in the expansion; this may take some getting used to. -Alternately, if no name is present in the buffer, you are prompted for a -name: 'declare C-c C-e' first prompts for a name, then expands to the -above. - - The variable 'ada-skel-initial-string' defines what to insert in a -newly created empty buffer. It defaults to '{header}', which is a -placeholder defined by 'ada-skel-header', which inserts a typical header -with a copyright license (choice of GPL or restricted). Users will -typically want to override the definition of 'ada-skel-initial-string' -and/or 'ada-skel-header', or provide more choices of copyright license. - - -File: ada-mode.info, Node: Aligning code, Next: Automatic casing, Prev: Statement skeletons, Up: Top - -10 Aligning code -**************** - -Aligning code adds space in each line so that similar parts of -successive lines are aligned vertically. For example, a sequence of -declarations: - - A : Integer; - Another : Float := 1.0; - More : Integer := 2; - - changes to this when aligned: - - A : Integer; - Another : Float := 1.0; - More : Integer := 2; - - Alignment is invoked by 'C-c C-a', which aligns the sequence of -statements surrounding point, or within the selected region. - - Parameter lists are also aligned: - - procedure Foo - (A : in Integer; - Another : out Float := 1.0; - More : in out Integer := 2); - - is aligned to: - - procedure Foo - (A : in Integer; - Another : out Float := 1.0; - More : in out Integer := 2); - - -File: ada-mode.info, Node: Automatic casing, Next: Comment Handling, Prev: Aligning code, Up: Top - -11 Automatic casing -******************* - -Casing of identifiers, attributes and keywords is automatically -performed while typing when the variable 'ada-auto-case' is non-nil (the -default). Every time you type a word separator, the previous word is -automatically cased. - - You can customize the automatic casing with the following variables: - -'ada-case-keyword' - Value must be one of: - 'downcase-word' - Ada keywords will be lowercase. - - 'upcase-word' - Ada keywords will be uppercase. - -'ada-case-strict' - If non-nil, all identifiers are forced to 'Mixed_Case'; first - letter, and letter following "_" are uppercase; rest are lowercase. - - If nil, the mixed case characters in identifiers are forced to - upper case, but the other characters are not modified. That allows - typing all uppercase identifiers without defining a casing - exception. - - You can define exceptions to these rules, in files specified by the -'casing' project variable; *note Casing exception files: (wisi)Casing -exception files. - - There are two ways to add new items to a casing exception 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 'Ada | Casing | -Create full exception' or 'Ada | Casing | Create partial exception'. -The word will be added to the current list of exceptions and to the -file. - - It is sometimes useful to have multiple exception files. For -example, one could be the standard Ada acronyms, the second some company -specific exceptions, and the last one some project specific exceptions. -When you create a new exception, you are prompted for the file to save -it in. - - Other keys and menu entries are defined: - -'C-c C-w' - Adjust case of the word at point. With prefix arg, adjust case - even if in a comment or string. Normally, comments and strings are - not affected by case adjust. - -'Ada | Casing | Adjust case region' - Adjust case in the active region. - -'Ada | Casing | Adjust case buffer' - Adjust case in the active buffer. - - -File: ada-mode.info, Node: Comment Handling, Next: Key summary, Prev: Automatic casing, Up: Top - -12 Comment Handling -******************* - -By default, comment lines get indented like Ada code. There are a few -additional functions to handle comments: - -'M-;' - If the region is active, comment or uncomment it. - - If the current line is empty, start a comment. - - Otherwise, add a comment at the end of the line, in a column given - by 'comment-column'. - -'M-q' - Fill the current comment paragraph. - - -File: ada-mode.info, Node: Key summary, Next: Developer overview, Prev: Comment Handling, Up: Top - -13 Key summary -************** - -This table summarizes the keys described in this manual. Other keys are -bound by Ada mode; see <C-h b> for a complete list. The Ada menu also -displays keys bound to menu operations. - -'M-/' - *Note Identifier completion::. Complete the word before point; - repeat to cycle thru possible completions. - -'M-;' - *Note Comment Handling::. If the region is active, comment or - uncomment it. - -'M-q' - *Note Comment Handling::. Fill the current comment paragraph. - -'RET' - *Note Indentation::. Insert and indent a new line. - -'TAB' - *Note Indentation::. Indent the current line, or the current - region. - -'C-c TAB' - *Note Indentation::. Indent the current statement or declaration. - -'C-c S-TAB' - *Note Indentation::. Indent the containing statement or - declaration. - -'C-c `' - *Note Compiler errors::. Move to the location of the secondary - reference in the current compilation error. - -'C-c C-a' - *Note Aligning code::. Align code. - -'C-c C-c' - *Note Compile commands::. Build the current main program. - -'C-c C-d' - *Note Moving Through Ada Code::. Move from any use of an - identifier to its declaration, for from a declaration to its body. - -'C-c M-d' - *Note Moving Through Ada Code::. Move from a child type - declaration to the parent type declaration. - -'C-c C-e' - *Note Statement skeletons::. Expand previous one or two words into - a statement or declaration skeleton. - -'C-c C-c' - *Note Compile commands::. Build the current file. - -'C-c C-n' - *Note Moving Through Ada Code::. Move to the next keyword in the - current statement. - -'C-c C-o' - *Note Moving Through Ada Code::. Switch between corresponding spec - and body, or find other spec. - -'C-c C-p' - *Note Moving Through Ada Code::. Move to the previous keyword in - the current statement. - -'C-c C-r' - *Note Moving Through Ada Code::. Show all references to the - identifier surrounding point. - -'C-c C-w' - *Note Automatic casing::. Adjust case of the word at point. With - prefix arg, adjust case even if in comment or string. - -'C-c C-x' - *Note Moving Through Ada Code::. Show all declarations that - override the primitive procedure at point. - -'C-c C-y' - *Note Automatic casing::. Create case exception. - -'C-c `' - *Note Compiler errors::. Move to the location of the next - secondary compilation error. - -'C-x `' - *Note Compiler errors::. Move to the location of the next - compilation error or show result. - -'M-q' - *Note Comment Handling::. Fill the current comment paragraph. - - -File: ada-mode.info, Node: Developer overview, Next: GNU Free Documentation License, Prev: Key summary, Up: Top - -14 Developer overview -********************* - -If you'd like to contribute to Ada mode, or just understand the sources, -here's an overview. - -* Menu: - -* Directory structure:: -* ELPA:: -* Savannah:: - - -File: ada-mode.info, Node: Directory structure, Next: ELPA, Up: Developer overview - -14.1 Directory structure -======================== - -'org.emacs.ada-mode' - Main source. - - File extensions: - '*.el' - Elisp files; main code. - - '*.elc' - Byte-compiled elisp files, not in the distribution. Generated - by the Makefile target 'byte-compile', or by the Emacs package - installer. - - '*.ad?' - Ada code for the external process parser and other tools, some - generated by the WisiToken tool 'wisitoken-bnf-generate.exe'. - - '*.parse_table' - Diagnostic output from 'wisitoken-bnf-generate.exe', useful - for tracing parses while debugging a grammar issue. Not in - any distribution. - - '*.wy' - Grammar files, specifying the language to be parsed. The - syntax for these grammar files is similar to that for bison - and wisent, but not the same; see the WisiToken documentation - for more info. - - '*.texi' - Texinfo source for the user guides. - - '*.html' - Generated user guide in HTML format. - - '*.info' - Generated user guide in Emacs info format. - -'build' - Makefile for building the external process executable, gpr-query, - and the user guides; for running tests; and for publishing to the - web page or Gnu ELPA. The main targets are: - - 'elisp' - Builds ada-mode in place, runs all tests. - - 'update-elisp' - Builds ada-mode in place. - - 'install' - Installs executables in the GNAT executable directory. - - 'pub' - Builds the ELPA packages. - -'test' - All tests for Ada mode, gpr mode, parser. - - Each test is run in a separate invocation of Emacs, so it is - completely independent of all other tests. - - The tests are driven by the elisp code in - 'wisi-run-indent-test.el'. - - In general, the Ada mode tests open the file, execute test actions, - re-indent, and re-captialize the entire file. The result is diffed - with the original, and must match. - - The test actions are defined by comments with the prefix - '--EMACSCMD:'; they are elisp forms that invoke Ada mode functions. - This is used to test navigation features and other parser effects. - -'test/Example_*' - Starting files for the examples in this user guide. - -'test/gpr' - Tests for gpr mode. - -'test/subdir' - More tests; allows testing path search features. - - -File: ada-mode.info, Node: ELPA, Next: Savannah, Prev: Directory structure, Up: Developer overview - -14.2 ELPA -========= - -Ada mode is published via the Gnu ELPA archive. To test a new version -of Ada mode, we use a local Gnu ELPA archive. That requires fetching -Gnu ELPA via git: - cd /Projects - git clone git://git.savannah.gnu.org/emacs/elpa.git - - If you have an Emacs Savannah developer account, you can use: - - cd /Projects - git clone <login>@git.savannah.gnu.org/emacs/elpa.git - - 'build/Makefile' contains targets for copying Ada mode source to the -elpa workspace, and for building the elpa archive there. - - -File: ada-mode.info, Node: Savannah, Prev: ELPA, Up: Developer overview - -14.3 Savannah -============= - -The ada-mode git repository, web page, mailing list, and tarball -download are hosted on savannah.non-gnu.org, project Emacs Ada mode -(<https://savannah.nongnu.org/projects/ada-mode/>). See the project -admin page there for more information. - - To checkout all source required to build and test ada-mode, assuming -you have ssh read/write git access to savannah ada-mode: - - git clone stephen_le...@git.sv.gnu.org:/srv/git/ada-mode.git \ - -b org.emacs.ada-mode org.emacs.ada-mode - cd ada-mode - git worktree add -b org.wisitoken ../org.wisitoken origin/org.wisitoken - git worktree add -b org.stephe_leake.sal ../org.stephe_leake.sal origin/org.stephe_leake.sal - git worktree add -b org.stephe_leake.aunit_ext ../org.stephe_leake.aunit_ext origin/org.stephe_leake.aunit_ext - git worktree add -b org.stephe_leake.makerules ../org.stephe_leake.makerules origin/org.stephe_leake.makerules - - In each worktree, there is a 'build' directory containing the -Makefile and all build outputs. The target 'all' runs all tests and -build documentation for that worktree. - - -File: ada-mode.info, Node: GNU Free Documentation License, Prev: Developer overview, Up: Top - -Appendix A GNU Free Documentation License -***************************************** - - Version 1.3, 3 November 2008 - - Copyright (C) 2000, 2001, 2002, 2007, 2008, 2009 Free Software Foundation, Inc. - <http://fsf.org/> - - Everyone is permitted to copy and distribute verbatim copies - of this license document, but changing it is not allowed. - - 0. PREAMBLE - - The purpose of this License is to make a manual, textbook, or other - functional and useful document "free" in the sense of freedom: to - assure everyone the effective freedom to copy and redistribute it, - with or without modifying it, either commercially or - noncommercially. Secondarily, this License preserves for the - author and publisher a way to get credit for their work, while not - being considered responsible for modifications made by others. - - This License is a kind of "copyleft", which means that derivative - works of the document must themselves be free in the same sense. - It complements the GNU General Public License, which is a copyleft - license designed for free software. - - We have designed this License in order to use it for manuals for - free software, because free software needs free documentation: a - free program should come with manuals providing the same freedoms - that the software does. But this License is not limited to - software manuals; it can be used for any textual work, regardless - of subject matter or whether it is published as a printed book. We - recommend this License principally for works whose purpose is - instruction or reference. - - 1. APPLICABILITY AND DEFINITIONS - - This License applies to any manual or other work, in any medium, - that contains a notice placed by the copyright holder saying it can - be distributed under the terms of this License. Such a notice - grants a world-wide, royalty-free license, unlimited in duration, - to use that work under the conditions stated herein. The - "Document", below, refers to any such manual or work. Any member - of the public is a licensee, and is addressed as "you". You accept - the license if you copy, modify or distribute the work in a way - requiring permission under copyright law. - - A "Modified Version" of the Document means any work containing the - Document or a portion of it, either copied verbatim, or with - modifications and/or translated into another language. - - A "Secondary Section" is a named appendix or a front-matter section - of the Document that deals exclusively with the relationship of the - publishers or authors of the Document to the Document's overall - subject (or to related matters) and contains nothing that could - fall directly within that overall subject. (Thus, if the Document - is in part a textbook of mathematics, a Secondary Section may not - explain any mathematics.) The relationship could be a matter of - historical connection with the subject or with related matters, or - of legal, commercial, philosophical, ethical or political position - regarding them. - - The "Invariant Sections" are certain Secondary Sections whose - titles are designated, as being those of Invariant Sections, in the - notice that says that the Document is released under this License. - If a section does not fit the above definition of Secondary then it - is not allowed to be designated as Invariant. The Document may - contain zero Invariant Sections. If the Document does not identify - any Invariant Sections then there are none. - - The "Cover Texts" are certain short passages of text that are - listed, as Front-Cover Texts or Back-Cover Texts, in the notice - that says that the Document is released under this License. A - Front-Cover Text may be at most 5 words, and a Back-Cover Text may - be at most 25 words. - - A "Transparent" copy of the Document means a machine-readable copy, - represented in a format whose specification is available to the - general public, that is suitable for revising the document - straightforwardly with generic text editors or (for images composed - of pixels) generic paint programs or (for drawings) some widely - available drawing editor, and that is suitable for input to text - formatters or for automatic translation to a variety of formats - suitable for input to text formatters. A copy made in an otherwise - Transparent file format whose markup, or absence of markup, has - been arranged to thwart or discourage subsequent modification by - readers is not Transparent. An image format is not Transparent if - used for any substantial amount of text. A copy that is not - "Transparent" is called "Opaque". - - Examples of suitable formats for Transparent copies include plain - ASCII without markup, Texinfo input format, LaTeX input format, - SGML or XML using a publicly available DTD, and standard-conforming - simple HTML, PostScript or PDF designed for human modification. - Examples of transparent image formats include PNG, XCF and JPG. - Opaque formats include proprietary formats that can be read and - edited only by proprietary word processors, SGML or XML for which - the DTD and/or processing tools are not generally available, and - the machine-generated HTML, PostScript or PDF produced by some word - processors for output purposes only. - - The "Title Page" means, for a printed book, the title page itself, - plus such following pages as are needed to hold, legibly, the - material this License requires to appear in the title page. For - works in formats which do not have any title page as such, "Title - Page" means the text near the most prominent appearance of the - work's title, preceding the beginning of the body of the text. - - The "publisher" means any person or entity that distributes copies - of the Document to the public. - - A section "Entitled XYZ" means a named subunit of the Document - whose title either is precisely XYZ or contains XYZ in parentheses - following text that translates XYZ in another language. (Here XYZ - stands for a specific section name mentioned below, such as - "Acknowledgements", "Dedications", "Endorsements", or "History".) - To "Preserve the Title" of such a section when you modify the - Document means that it remains a section "Entitled XYZ" according - to this definition. - - The Document may include Warranty Disclaimers next to the notice - which states that this License applies to the Document. These - Warranty Disclaimers are considered to be included by reference in - this License, but only as regards disclaiming warranties: any other - implication that these Warranty Disclaimers may have is void and - has no effect on the meaning of this License. - - 2. VERBATIM COPYING - - You may copy and distribute the Document in any medium, either - commercially or noncommercially, provided that this License, the - copyright notices, and the license notice saying this License - applies to the Document are reproduced in all copies, and that you - add no other conditions whatsoever to those of this License. You - may not use technical measures to obstruct or control the reading - or further copying of the copies you make or distribute. However, - you may accept compensation in exchange for copies. If you - distribute a large enough number of copies you must also follow the - conditions in section 3. - - You may also lend copies, under the same conditions stated above, - and you may publicly display copies. - - 3. COPYING IN QUANTITY - - If you publish printed copies (or copies in media that commonly - have printed covers) of the Document, numbering more than 100, and - the Document's license notice requires Cover Texts, you must - enclose the copies in covers that carry, clearly and legibly, all - these Cover Texts: Front-Cover Texts on the front cover, and - Back-Cover Texts on the back cover. Both covers must also clearly - and legibly identify you as the publisher of these copies. The - front cover must present the full title with all words of the title - equally prominent and visible. You may add other material on the - covers in addition. Copying with changes limited to the covers, as - long as they preserve the title of the Document and satisfy these - conditions, can be treated as verbatim copying in other respects. - - If the required texts for either cover are too voluminous to fit - legibly, you should put the first ones listed (as many as fit - reasonably) on the actual cover, and continue the rest onto - adjacent pages. - - If you publish or distribute Opaque copies of the Document - numbering more than 100, you must either include a machine-readable - Transparent copy along with each Opaque copy, or state in or with - each Opaque copy a computer-network location from which the general - network-using public has access to download using public-standard - network protocols a complete Transparent copy of the Document, free - of added material. If you use the latter option, you must take - reasonably prudent steps, when you begin distribution of Opaque - copies in quantity, to ensure that this Transparent copy will - remain thus accessible at the stated location until at least one - year after the last time you distribute an Opaque copy (directly or - through your agents or retailers) of that edition to the public. - - It is requested, but not required, that you contact the authors of - the Document well before redistributing any large number of copies, - to give them a chance to provide you with an updated version of the - Document. - - 4. MODIFICATIONS - - You may copy and distribute a Modified Version of the Document - under the conditions of sections 2 and 3 above, provided that you - release the Modified Version under precisely this License, with the - Modified Version filling the role of the Document, thus licensing - distribution and modification of the Modified Version to whoever - possesses a copy of it. In addition, you must do these things in - the Modified Version: - - A. Use in the Title Page (and on the covers, if any) a title - distinct from that of the Document, and from those of previous - versions (which should, if there were any, be listed in the - History section of the Document). You may use the same title - as a previous version if the original publisher of that - version gives permission. - - B. List on the Title Page, as authors, one or more persons or - entities responsible for authorship of the modifications in - the Modified Version, together with at least five of the - principal authors of the Document (all of its principal - authors, if it has fewer than five), unless they release you - from this requirement. - - C. State on the Title page the name of the publisher of the - Modified Version, as the publisher. - - D. Preserve all the copyright notices of the Document. - - E. Add an appropriate copyright notice for your modifications - adjacent to the other copyright notices. - - F. Include, immediately after the copyright notices, a license - notice giving the public permission to use the Modified - Version under the terms of this License, in the form shown in - the Addendum below. - - G. Preserve in that license notice the full lists of Invariant - Sections and required Cover Texts given in the Document's - license notice. - - H. Include an unaltered copy of this License. - - I. Preserve the section Entitled "History", Preserve its Title, - and add to it an item stating at least the title, year, new - authors, and publisher of the Modified Version as given on the - Title Page. If there is no section Entitled "History" in the - Document, create one stating the title, year, authors, and - publisher of the Document as given on its Title Page, then add - an item describing the Modified Version as stated in the - previous sentence. - - J. Preserve the network location, if any, given in the Document - for public access to a Transparent copy of the Document, and - likewise the network locations given in the Document for - previous versions it was based on. These may be placed in the - "History" section. You may omit a network location for a work - that was published at least four years before the Document - itself, or if the original publisher of the version it refers - to gives permission. - - K. For any section Entitled "Acknowledgements" or "Dedications", - Preserve the Title of the section, and preserve in the section - all the substance and tone of each of the contributor - acknowledgements and/or dedications given therein. - - L. Preserve all the Invariant Sections of the Document, unaltered - in their text and in their titles. Section numbers or the - equivalent are not considered part of the section titles. - - M. Delete any section Entitled "Endorsements". Such a section - may not be included in the Modified Version. - - N. Do not retitle any existing section to be Entitled - "Endorsements" or to conflict in title with any Invariant - Section. - - O. Preserve any Warranty Disclaimers. - - If the Modified Version includes new front-matter sections or - appendices that qualify as Secondary Sections and contain no - material copied from the Document, you may at your option designate - some or all of these sections as invariant. To do this, add their - titles to the list of Invariant Sections in the Modified Version's - license notice. These titles must be distinct from any other - section titles. - - You may add a section Entitled "Endorsements", provided it contains - nothing but endorsements of your Modified Version by various - parties--for example, statements of peer review or that the text - has been approved by an organization as the authoritative - definition of a standard. - - You may add a passage of up to five words as a Front-Cover Text, - and a passage of up to 25 words as a Back-Cover Text, to the end of - the list of Cover Texts in the Modified Version. Only one passage - of Front-Cover Text and one of Back-Cover Text may be added by (or - through arrangements made by) any one entity. If the Document - already includes a cover text for the same cover, previously added - by you or by arrangement made by the same entity you are acting on - behalf of, you may not add another; but you may replace the old - one, on explicit permission from the previous publisher that added - the old one. - - The author(s) and publisher(s) of the Document do not by this - License give permission to use their names for publicity for or to - assert or imply endorsement of any Modified Version. - - 5. COMBINING DOCUMENTS - - You may combine the Document with other documents released under - this License, under the terms defined in section 4 above for - modified versions, provided that you include in the combination all - of the Invariant Sections of all of the original documents, - unmodified, and list them all as Invariant Sections of your - combined work in its license notice, and that you preserve all - their Warranty Disclaimers. - - The combined work need only contain one copy of this License, and - multiple identical Invariant Sections may be replaced with a single - copy. If there are multiple Invariant Sections with the same name - but different contents, make the title of each such section unique - by adding at the end of it, in parentheses, the name of the - original author or publisher of that section if known, or else a - unique number. Make the same adjustment to the section titles in - the list of Invariant Sections in the license notice of the - combined work. - - In the combination, you must combine any sections Entitled - "History" in the various original documents, forming one section - Entitled "History"; likewise combine any sections Entitled - "Acknowledgements", and any sections Entitled "Dedications". You - must delete all sections Entitled "Endorsements." - - 6. COLLECTIONS OF DOCUMENTS - - You may make a collection consisting of the Document and other - documents released under this License, and replace the individual - copies of this License in the various documents with a single copy - that is included in the collection, provided that you follow the - rules of this License for verbatim copying of each of the documents - in all other respects. - - You may extract a single document from such a collection, and - distribute it individually under this License, provided you insert - a copy of this License into the extracted document, and follow this - License in all other respects regarding verbatim copying of that - document. - - 7. AGGREGATION WITH INDEPENDENT WORKS - - A compilation of the Document or its derivatives with other - separate and independent documents or works, in or on a volume of a - storage or distribution medium, is called an "aggregate" if the - copyright resulting from the compilation is not used to limit the - legal rights of the compilation's users beyond what the individual - works permit. When the Document is included in an aggregate, this - License does not apply to the other works in the aggregate which - are not themselves derivative works of the Document. - - If the Cover Text requirement of section 3 is applicable to these - copies of the Document, then if the Document is less than one half - of the entire aggregate, the Document's Cover Texts may be placed - on covers that bracket the Document within the aggregate, or the - electronic equivalent of covers if the Document is in electronic - form. Otherwise they must appear on printed covers that bracket - the whole aggregate. - - 8. TRANSLATION - - Translation is considered a kind of modification, so you may - distribute translations of the Document under the terms of section - 4. Replacing Invariant Sections with translations requires special - permission from their copyright holders, but you may include - translations of some or all Invariant Sections in addition to the - original versions of these Invariant Sections. You may include a - translation of this License, and all the license notices in the - Document, and any Warranty Disclaimers, provided that you also - include the original English version of this License and the - original versions of those notices and disclaimers. In case of a - disagreement between the translation and the original version of - this License or a notice or disclaimer, the original version will - prevail. - - If a section in the Document is Entitled "Acknowledgements", - "Dedications", or "History", the requirement (section 4) to - Preserve its Title (section 1) will typically require changing the - actual title. - - 9. TERMINATION - - You may not copy, modify, sublicense, or distribute the Document - except as expressly provided under this License. Any attempt - otherwise to copy, modify, sublicense, or distribute it is void, - and will automatically terminate your rights under this License. - - However, if you cease all violation of this License, then your - license from a particular copyright holder is reinstated (a) - provisionally, unless and until the copyright holder explicitly and - finally terminates your license, and (b) permanently, if the - copyright holder fails to notify you of the violation by some - reasonable means prior to 60 days after the cessation. - - Moreover, your license from a particular copyright holder is - reinstated permanently if the copyright holder notifies you of the - violation by some reasonable means, this is the first time you have - received notice of violation of this License (for any work) from - that copyright holder, and you cure the violation prior to 30 days - after your receipt of the notice. - - Termination of your rights under this section does not terminate - the licenses of parties who have received copies or rights from you - under this License. If your rights have been terminated and not - permanently reinstated, receipt of a copy of some or all of the - same material does not give you any rights to use it. - - 10. FUTURE REVISIONS OF THIS LICENSE - - The Free Software Foundation may publish new, revised versions of - the GNU Free Documentation License from time to time. Such new - versions will be similar in spirit to the present version, but may - differ in detail to address new problems or concerns. See - <http://www.gnu.org/copyleft/>. - - Each version of the License is given a distinguishing version - number. If the Document specifies that a particular numbered - version of this License "or any later version" applies to it, you - have the option of following the terms and conditions either of - that specified version or of any later version that has been - published (not as a draft) by the Free Software Foundation. If the - Document does not specify a version number of this License, you may - choose any version ever published (not as a draft) by the Free - Software Foundation. If the Document specifies that a proxy can - decide which future versions of this License can be used, that - proxy's public statement of acceptance of a version permanently - authorizes you to choose that version for the Document. - - 11. RELICENSING - - "Massive Multiauthor Collaboration Site" (or "MMC Site") means any - World Wide Web server that publishes copyrightable works and also - provides prominent facilities for anybody to edit those works. A - public wiki that anybody can edit is an example of such a server. - A "Massive Multiauthor Collaboration" (or "MMC") contained in the - site means any set of copyrightable works thus published on the MMC - site. - - "CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0 - license published by Creative Commons Corporation, a not-for-profit - corporation with a principal place of business in San Francisco, - California, as well as future copyleft versions of that license - published by that same organization. - - "Incorporate" means to publish or republish a Document, in whole or - in part, as part of another Document. - - An MMC is "eligible for relicensing" if it is licensed under this - License, and if all works that were first published under this - License somewhere other than this MMC, and subsequently - incorporated in whole or in part into the MMC, (1) had no cover - texts or invariant sections, and (2) were thus incorporated prior - to November 1, 2008. - - The operator of an MMC Site may republish an MMC contained in the - site under CC-BY-SA on the same site at any time before August 1, - 2009, provided the MMC is eligible for relicensing. - -ADDENDUM: How to use this License for your documents -==================================================== - -To use this License in a document you have written, include a copy of -the License in the document and put the following copyright and license -notices just after the title page: - - Copyright (C) YEAR YOUR NAME. - Permission is granted to copy, distribute and/or modify this document - under the terms of the GNU Free Documentation License, Version 1.3 - or any later version published by the Free Software Foundation; - with no Invariant Sections, no Front-Cover Texts, and no Back-Cover - Texts. A copy of the license is included in the section entitled ``GNU - Free Documentation License''. - - If you have Invariant Sections, Front-Cover Texts and Back-Cover -Texts, replace the "with...Texts." line with this: - - with the Invariant Sections being LIST THEIR TITLES, with - the Front-Cover Texts being LIST, and with the Back-Cover Texts - being LIST. - - If you have Invariant Sections without Cover Texts, or some other -combination of the three, merge those two alternatives to suit the -situation. - - If your document contains nontrivial examples of program code, we -recommend releasing these examples in parallel under your choice of free -software license, such as the GNU General Public License, to permit -their use in free software. - - - -Tag Table: -Node: Top931 -Node: Overview2690 -Node: Why not LSP?3927 -Node: Installation4683 -Node: Ada executables5719 -Node: Building GNATCOLL8231 -Node: Building the executables9285 -Node: Known versions10103 -Node: Customization11977 -Node: Slow response16480 -Node: Non-standard file names18206 -Node: Other compiler20085 -Node: Other cross-reference20660 -Node: Other customization21383 -Node: Compiling Executing21533 -Node: Compile commands22256 -Node: Compiling Examples24948 -Node: No project files25780 -Node: Set compiler options31096 -Node: Set source search path33149 -Node: Use wisi project file35386 -Node: Use multiple GNAT project files38993 -Node: Use a Makefile43838 -Node: Compiler errors45489 -Node: Project files46306 -Node: Project file overview47358 -Node: Project file variables47900 -Node: Moving Through Ada Code51340 -Node: Identifier completion54372 -Node: Indentation56561 -Node: Statement skeletons60090 -Node: Aligning code61733 -Node: Automatic casing62678 -Node: Comment Handling64865 -Node: Key summary65384 -Node: Developer overview68114 -Node: Directory structure68428 -Node: ELPA70924 -Node: Savannah71560 -Node: GNU Free Documentation License72756 - -End Tag Table - - -Local Variables: -coding: utf-8 -End: diff --git a/ada-mode.texi b/ada-mode.texi index cfd617e..f46bef1 100644 --- a/ada-mode.texi +++ b/ada-mode.texi @@ -1432,7 +1432,9 @@ references are accessed via @kbd{C-c `}. @node Project files, Moving Through Ada Code, Compiling Executing, Top @chapter Project files -Ada mode uses wisi project files; @ref{wisi, Project files, Project files, wisi}. +Ada mode uses wisi project files; +@ifinfo +@ref{Project files, Project files, Project files, wisi}. A wisi project file specifies what directories hold sources for your project, and allows you to customize the compilation commands and @@ -1465,7 +1467,7 @@ The current project file is shown by the menu command To set the project file, use the menu command @key{Ada | Project Files | Find and select Project ...}, or one of the elisp functions described in -@ref{wisi, Selecting Projects, Selecting Projects, wisi}. +@ref{Selecting Projects, Selecting Projects, Selecting Projects, wisi}. The project file may also be a GNAT project file (with file extension is @code{.gpr}).