[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] Changes to emacs/doc/misc/ada-mode.texi,v
From: |
Juanma Barranquero |
Subject: |
[Emacs-diffs] Changes to emacs/doc/misc/ada-mode.texi,v |
Date: |
Mon, 28 Jul 2008 11:03:44 +0000 |
CVSROOT: /sources/emacs
Module name: emacs
Changes by: Juanma Barranquero <lektu> 08/07/28 11:03:42
Index: doc/misc/ada-mode.texi
===================================================================
RCS file: /sources/emacs/emacs/doc/misc/ada-mode.texi,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -b -r1.5 -r1.6
--- doc/misc/ada-mode.texi 15 Jun 2008 02:28:56 -0000 1.5
+++ doc/misc/ada-mode.texi 28 Jul 2008 11:03:39 -0000 1.6
@@ -30,7 +30,7 @@
@title{Ada Mode}
@sp 2
@subtitle An Emacs major mode for programming in Ada
address@hidden Ada Mode Version 3.7
address@hidden Ada Mode Version 4.00
@sp 2
@page
@vskip 0pt plus 1filll
@@ -268,7 +268,7 @@
listed in the Ada menu.
In multi-file projects, there must be one file that is the main
-program. That is given by the @code{main_unit} project file variable;
+program. That is given by the @code{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.
@@ -280,26 +280,26 @@
runs faster than full compile mode, speeding up finding and fixing
compilation errors.
-This sets @code{main_unit} only if it has not been set yet.
+This sets @code{main} only if it has not been set yet.
@item Compile file
Compiles the current file, by running @code{comp_cmd} from the current
project file.
-This does not set @code{main_unit}.
+This does not set @code{main}.
@item Set main and Build
-Sets @code{main_unit} to the current file, then executes the Build
+Sets @code{main} to the current file, then executes the Build
command.
@item Show main
-Display @code{main_unit} in the message buffer.
+Display @code{main} in the message buffer.
@item Build
-Compiles all obsolete units of the current @code{main_unit}, and links
address@hidden, by running @code{make_cmd} from the current project.
+Compiles all obsolete units of the current @code{main}, and links
address@hidden, by running @code{make_cmd} from the current project.
-This sets @code{main_unit} only if it has not been set yet.
+This sets @code{main} only if it has not been set yet.
@item Run
Executes the main program in a shell, displayed in a separate Emacs
@@ -313,7 +313,7 @@
@end table
It is important when using these commands to understand how
address@hidden is used and changed.
address@hidden is used and changed.
Build runs 'gnatmake' on the main unit. During a typical edit/compile
session, this is the only command you need to invoke, which is why it
@@ -328,19 +328,19 @@
this case, @key{C-c C-m} will normally be the only command needed; it
will build the current file, rather than the last-built main.
-There are three ways to change @code{main_unit}:
+There are three ways to change @code{main}:
@enumerate
@item
-Invoke @key{Ada | Set main and Build}, which sets @code{main_unit} to
+Invoke @key{Ada | Set main and Build}, which sets @code{main} to
the current file.
@item
-Invoke @key{Ada | Project | Edit}, edit @code{main_unit} and
+Invoke @key{Ada | Project | Edit}, edit @code{main} and
@code{main}, and click @key{[save]}
@item
-Invoke @key{Ada | Project | Load}, and load a project file that specifies
@code{main_unit}
+Invoke @key{Ada | Project | Load}, and load a project file that specifies
@code{main}
@end enumerate
@@ -372,7 +372,10 @@
and other things on a per-project basis.
Note that Ada mode project files @samp{*.adp} are different than GNAT
-compiler project files @samp{*.gpr}.
+compiler project files @samp{*.gpr}. However, Emacs Ada mode can use a
+GNAT project project file to specify the project directories. If no
+other customization is needed, a GNAT project file can be used without
+an Emacs Ada mode project file.
@menu
* Project File Overview::
@@ -436,9 +439,15 @@
To change the project file before or after the first one is found,
invoke @key{Ada | Project | Load ...}.
-Or, in lisp, evaluate @code{ada-set-default-project-file "/path/file.adp"}.
+Or, in lisp, evaluate @code{(ada-set-default-project-file "/path/file.adp")}.
This sets @code{ada-prj-default-project-file}, and reads the project file.
+You can also specify a GNAT project file to @key{Ada | Project | Load
+...} or @code{ada-set-default-project-file}. Emacs Ada mode checks the
+file extension; if it is @code{.gpr}, the file is treated as a GNAT
+project file. Any other extension is treated as an Emacs Ada mode
+project file.
+
@node GUI Editor, Project file variables, Project File Overview, Project files
@section GUI Editor
@@ -465,30 +474,68 @@
@code{comp_opt} variable will be substituted when @code{comp_cmd} is
used.
+In addition, process environment variables can be referenced using the
+same syntax, or the normal @code{$var} syntax.
+
Most project variables have defaults that can be changed by setting
lisp variables; the table below identifies the lisp variable for each
project variable. Lisp variables corresponding to project variables
that are lists are lisp lists.
+In general, project variables are evaluated when referenced in
+Emacs Ada mode commands. Relative file paths are expanded to
+absolute relative to @address@hidden@}}.
+
Here is the list of variables. In the default values, the current
directory @code{"."} is the project file directory.
address@hidden defined in ada-xref-set-default-prj-values; same order here
@table @asis
address@hidden @code{build_dir} [default: @code{"."}]
-The compile commands will be issued in this directory.
address@hidden defined in ada-default-prj-properties; alphabetical order
address@hidden @code{src_dir} [default: @code{"."}]
-A list of directories to search for source files, both for compile
-commands and source navigation.
address@hidden @code{ada_project_path_sep} [default: @code{":" or ";"}]
+Path separator for @code{ADA_PROJECT_PATH}. It defaults to the correct
+value for a native implementation of GNAT for the current operating
+system. The user must override this when using Windows native GNAT
+with Cygwin Emacs, and perhaps in other cases.
address@hidden @code{obj_dir} [default: @code{"."}]
-A list of directories to search for library files. Ada mode searches
-this list for the @samp{.ali} files generated by GNAT that contain
-cross-reference information.
+Lisp variable: @code{ada-prj-ada-project-path-sep}.
-The compiler commands must place the @samp{.ali} files in one of these
-directories; the default commands do that.
address@hidden @code{ada_project_path} [default: @code{""}]
+A list of directories to search for GNAT project files.
+
+If set, the @code{ADA_PROJECT_PATH} process environment variable is
+set to this value in the Emacs process when the Emacs Ada mode project
+is selected via menu @samp{Ada | Project | Load}.
+
+For @code{ada_project_path}, relative file paths are expanded to
+absolute when the Emacs Ada project file is read, rather than when the
+project file is selected.
+
+For example if the project file is in the directory
address@hidden/home/myproject}, the environment variable @code{GDS_ROOT} is
+set to @code{/home/shared}, and the project file contains:
address@hidden
+ada_project_path_sep=:
+ada_project_path=$GDS_ROOT/makerules
+ada_project_path=../opentoken
address@hidden example
+the environment variable @code{ADA_PROJECT_PATH} will be set to
address@hidden"/home/shared/makerules:/home/opentoken/"}.
+
+The default value is not the current value of this environment
+variable, because that will typically have been set by another
+project, and will therefore be incorrect for this project.
+
+If you have the environment variable set correctly for all of your
+projects, you do not need to set this project variable.
+
address@hidden @code{bind_opt} [default: @code{""}]
+Holds user binder options; used in the default build commands.
+
+Lisp variable: @code{ada-prj-default-bind-opt}.
+
address@hidden @code{build_dir} [default: @code{"."}]
+The compile commands will be issued in this directory.
@item @code{casing} [default: @code{("~/.emacs_case_exceptions")}
List of files containing casing exceptions. See the help on
@@ -497,6 +544,18 @@
Lisp variable: @code{ada-case-exception-file}.
address@hidden @code{check_cmd} [default: @code{"address@hidden@}gnatmake
-u -c -gnatc address@hidden@} address@hidden@} -cargs address@hidden@}"}]
+Command used to syntax check a single file.
+The name of the file is substituted for @code{full_current}.
+
+Lisp variable: @code{ada-prj-default-check-cmd}
+
address@hidden @code{comp_cmd} [default: @code{"address@hidden@}gnatmake
-u -c address@hidden@} address@hidden@} -cargs address@hidden@}"}]
+Command used to compile a single file.
+The name of the file is substituted for @code{full_current}.
+
+Lisp variable: @code{ada-prj-default-comp-cmd}.
+
@item @code{comp_opt} [default: @code{"-gnatq -gnatQ"}]
Holds user compiler options; used in the default compile commands. The
default value tells gnatmake to generate library files for
@@ -509,76 +568,81 @@
Lisp variable: @code{ada-prj-default-comp-opt}.
address@hidden @code{bind_opt} [default: @code{""}]
-Holds user binder options; used in the default build commands.
-
-Lisp variable: @code{ada-prj-default-bind-opt}.
-
address@hidden @code{link_opt} [default: @code{""}]
-Holds user linker options; used in the default build commands.
address@hidden @code{cross_prefix} [default: @code{""}]
+Name of target machine in a cross-compilation environment. Used in
+default compile and build commands.
-Lisp variable: @code{ada-prj-default-link-opt}.
address@hidden @code{debug_cmd} [default: @code{"address@hidden@}gdb
address@hidden@}"}]
+Command used to debug the application
address@hidden @code{gnatmake_opt} [default: @code{"-g"}]
-Holds user gnatmake options; used in the default build commands.
+Lisp variable: @code{ada-prj-default-debugger}.
-If a GNAT project file is used (for example @file{project.gpr}), this
-option should be set to @code{-Pproject.gpr}.
address@hidden @code{debug_post_cmd} [default: @code{""}]
+Command executed after @code{debug_cmd}.
-Lisp variable: @code{ada-prj-default-gnatmake-opt}.
address@hidden @code{debug_pre_cmd} [default: @code{"cd address@hidden@}"}]
+Command executed before @code{debug_cmd}.
@item @code{gnatfind_opt} [default: @code{"-rf"}]
Holds user gnatfind options; used in the default find commands.
Lisp variable: @code{ada-prj-gnatfind-switches}.
address@hidden @code{main} [default: current file]
-Specifies the name of the executable file for the project; used in the
-default build commands.
address@hidden @code{gnatmake_opt} [default: @code{"-g"}]
+Holds user gnatmake options; used in the default build commands.
address@hidden @code{main_unit} [default: current Ada unit]
-Specifies the name of the main Ada unit for the project; used in the
-default build commands.
+Lisp variable: @code{ada-prj-default-gnatmake-opt}.
address@hidden @code{cross_prefix} [default: @code{""}]
-Name of target machine in a cross-compilation environment. Used in
-default compile and build commands.
address@hidden @code{gpr_file} [default: @code{""}]
+Specify GNAT project file.
address@hidden @code{remote_machine} [default: @code{""}]
-Name of the machine to log into before issuing the compile and build
-commands. If this variable is empty, the command will be run on the
-local machine.
+If set, the source and object directories specified in the GNAT
+project file are appended to @code{src_dir} and @code{obj_dir}. This
+allows specifying Ada source directories with a GNAT project file, and
+other source directories with the Emacs project file.
+
+In addition, @address@hidden@}} is added to the project variable
address@hidden whenever it is referenced. With the default
+project variables, this passes the project file to all gnatmake
+commands.
address@hidden @code{comp_cmd} [default: @code{"address@hidden@}gnatmake
-u -c address@hidden@} address@hidden@} -cargs address@hidden@}"}]
-Command used to compile a single file.
-The name of the file is substituted for @code{full_current}.
+Lisp variable: @code{ada-prj-default-gpr-file}.
-Lisp variable: @code{ada-prj-default-comp-cmd}.
address@hidden FIXME: add gnatstub-opts
address@hidden @code{check_cmd} [default: @code{"address@hidden@}gnatmake
-u -c -gnatc address@hidden@} address@hidden@} -cargs address@hidden@}"}]
-Command used to syntax check a single file.
-The name of the file is substituted for @code{full_current}.
address@hidden @code{link_opt} [default: @code{""}]
+Holds user linker options; used in the default build commands.
-Lisp variable: @code{ada-prj-default-check-cmd}
+Lisp variable: @code{ada-prj-default-link-opt}.
address@hidden @code{make_cmd} [default: @code{"address@hidden@}gnatmake
-o address@hidden@} address@hidden@} address@hidden@} -cargs address@hidden@}
-bargs address@hidden@} -largs address@hidden@}"}]
address@hidden @code{main} [default: current file]
+Specifies the name of the executable file for the project; used in the
+default build commands.
+
address@hidden @code{make_cmd} [default: @code{"address@hidden@}gnatmake
-o address@hidden@} address@hidden@} address@hidden@} -cargs address@hidden@}
-bargs address@hidden@} -largs address@hidden@}"}]
Command used to build the application.
Lisp variable: @code{ada-prj-default-make-cmd}.
address@hidden @code{run_cmd} [default: @code{"./address@hidden@}"}]
-Command used to run the application.
address@hidden @code{obj_dir} [default: @code{"."}]
+A list of directories to search for library files. Ada mode searches
+this list for the @samp{.ali} files generated by GNAT that contain
+cross-reference information.
address@hidden @code{debug_pre_cmd} [default: @code{"cd address@hidden@}"}]
-Command executed before @code{debug_cmd}.
+The compiler commands must place the @samp{.ali} files in one of these
+directories; the default commands do that.
address@hidden @code{debug_cmd} [default: @code{"address@hidden@}gdb
address@hidden@}"}]
-Command used to debug the application
address@hidden @code{remote_machine} [default: @code{""}]
+Name of the machine to log into before issuing the compile and build
+commands. If this variable is empty, the command will be run on the
+local machine.
-Lisp variable: @code{ada-prj-default-debugger}.
address@hidden @code{run_cmd} [default: @code{"./address@hidden@}"}]
+Command used to run the application.
address@hidden @code{debug_post_cmd} [default: @code{""}]
-Command executed after @code{debug_cmd}.
address@hidden @code{src_dir} [default: @code{"."}]
+A list of directories to search for source files, both for compile
+commands and source navigation.
@end table
@@ -601,6 +665,7 @@
* Set compiler options:: A basic Ada mode project file
* Set source search path:: Source in multiple directories
* Use GNAT project file::
+* Use multiple GNAT project files::
@end menu
@node No project files, Set compiler options, Compiling Examples, Compiling
Examples
@@ -632,6 +697,8 @@
end Hello_2;
@end example
+This file has no errors.
+
@file{hello_pkg.ads}:
@example
@@ -640,6 +707,8 @@
end Hello_Pkg;
@end example
+This file has no errors.
+
@file{hello_pkg.adb}:
@example
@@ -683,7 +752,7 @@
Ada.Text_IO.Put_Line ("hello from hello.adb"):
@end example
-Now invoke @key{Ada | Show main}; this displays @file{Ada mode main_unit:
hello}.
+Now invoke @key{Ada | Show main}; this displays @file{Ada mode main: hello}.
Now (in buffer @file{hello.adb}), invoke @key{Ada | Build}. You are
prompted to save the file (if you haven't already). Then the
@@ -729,7 +798,7 @@
@xref{Set source search path}, or a GNAT project file; @ref{Use GNAT
project file}.
-Invoke @key{Ada | Show main}; this displays @file{Ada mode main_unit: hello_2}.
+Invoke @key{Ada | Show main}; this displays @file{Ada mode main: hello_2}.
Move to the error with @key{C-x `}, and fix the error by adding @code{body}:
@@ -740,29 +809,29 @@
Now, while still in @file{hello_pkg.adb}, invoke @key{Ada | Build}.
gnatmake successfully builds @file{hello_2}. This demonstrates that
Emacs has remembered the main file, in the project variable
address@hidden, and used it for the Build command.
address@hidden, and used it for the Build command.
Finally, again while in @file{hello_pkg.adb}, invoke @key{Ada | Run}.
The @code{*run*} buffer displays @code{Hello from hello_pkg.adb}.
One final point. If you switch back to buffer @file{hello.adb}, and
invoke @key{Ada | Run}, @file{hello_2.exe} will be run. That is
-because @code{main_unit} is still set to @code{hello_2}, as you can
+because @code{main} is still set to @code{hello_2}, as you can
see when you invoke @key{Ada | Project | Edit}.
-There are three ways to change @code{main_unit}:
+There are three ways to change @code{main}:
@enumerate
@item
-Invoke @key{Ada | Set main and Build}, which sets @code{main_unit} to
+Invoke @key{Ada | Set main and Build}, which sets @code{main} to
the current file.
@item
-Invoke @key{Ada | Project | Edit}, edit @code{main_unit} and
+Invoke @key{Ada | Project | Edit}, edit @code{main} and
@code{main}, and click @key{[save]}
@item
-Invoke @key{Ada | Project | Load}, and load a project file that specifies
@code{main_unit}
+Invoke @key{Ada | Project | Load}, and load a project file that specifies
@code{main}
@end enumerate
@@ -832,8 +901,8 @@
@section Set source search path
In this example, we show how to deal with files in more than one
-directory. We start with the same code as in @ref{No project files}; create
those
-files (with the errors present)
+directory. We start with the same code as in @ref{No project files};
+create those files (with the errors present)
Create the directory @file{Example_3}, containing:
@@ -912,10 +981,11 @@
Fixing the error, linking and running the code proceed as in @ref{No
project files}.
address@hidden Use GNAT project file, , Set source search path, Compiling
Examples
address@hidden Use GNAT project file, Use multiple GNAT project files, Set
source search path, Compiling Examples
@section Use GNAT project file
-In this example, we show how to use a GNAT project file.
+In this example, we show how to use a GNAT project file, with no Ada
+mode project file.
Create the directory @file{Example_4}, containing:
@@ -945,7 +1015,7 @@
In addition, create a directory @file{Example_4/Gnat_Project},
containing these files:
address@hidden/hello_4.adb}:
address@hidden/hello_4.adb}:
@example
with Hello_Pkg;
@@ -959,13 +1029,6 @@
There are no errors in this file.
address@hidden/hello_4.adp}:
-
address@hidden
-src_dir=..
-gnatmake_opt=-Phello_4.gpr
address@hidden example
-
@file{Gnat_Project/hello_4.gpr}:
@example
@@ -975,7 +1038,7 @@
@end example
In buffer @file{hello_4.adb}, invoke @key{Ada | Project | Load...}, and
-select @file{Example_4/Gnat_Project/hello_4.adp}.
+select @file{Example_4/Gnat_Project/hello_4.gpr}.
Then, again in @file{hello_4.adb}, invoke @key{Ada | Set main and
Build}. You should get a @code{*compilation*} buffer containing
@@ -997,9 +1060,72 @@
Fixing the error, linking and running the code proceed as in @ref{No
project files}.
address@hidden Use multiple GNAT project files, , Use GNAT project file,
Compiling Examples
address@hidden 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.
+
+Create the directory @file{Example_4} as specified in @ref{Use GNAT
+project file}.
+
+Create the directory @file{Example_5}, containing:
+
address@hidden:
+
address@hidden
+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;
address@hidden example
+
+There are no errors in this file.
+
address@hidden:
+
address@hidden
+ada_project_path=../Example_4/Gnat_Project
+gpr_file=hello_5.gpr
address@hidden example
+
address@hidden:
+
address@hidden
+with "hello_4";
+Project Hello_5 is
+ for Source_Dirs use (".");
+ package Compiler is
+ for Default_Switches ("Ada") use ("-g", "-gnatyt");
+ end Compiler;
+end Hello_5;
address@hidden example
+
+In buffer @file{hello_5.adb}, invoke @key{Ada | Project | Load...}, and
+select @file{Example_5/hello_5.adp}.
+
+Then, again in @file{hello_5.adb}, invoke @key{Ada | Set main and
+Build}. You should get a @code{*compilation*} buffer containing
+something like (the directory paths will be different):
+
address@hidden
+cd c:/Examples/Example_5/
+gnatmake -o hello_5 hello_5 -Phello_5.gpr -g -cargs -gnatq -gnatQ -bargs
-largs
+gcc -c -g -gnatyt -g -gnatq -gnatQ -I- -gnatA c:\Examples\Example_5\hello_5.adb
+gcc -c -g -gnatyt -g -gnatq -gnatQ -I- -gnatA
c:\Examples\Example_4\hello_pkg.adb
+hello_pkg.adb:2:08: keyword "body" expected here [see file name]
+gnatmake: "c:\examples\example_4\hello_pkg.adb" compilation error
address@hidden example
+
+Now type @key{C-x `}. @file{Example_4/hello_pkg.adb} is shown,
+demonstrating that @file{hello_5.gpr} and @file{hello_4.gpr} are being
+used to set the compilation search path.
+
@node Moving Through Ada Code, Identifier completion, Compiling Examples, Top
@chapter Moving Through Ada Code
address@hidden
-----------------------------------------------------------------------
There are several easy to use commands to navigate through Ada code. All
these functions are available through the Ada menu, and you can also
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [Emacs-diffs] Changes to emacs/doc/misc/ada-mode.texi,v,
Juanma Barranquero <=