* GNAT Project Manager::
* Tools Supporting Project Files::
* The Cross-Referencing Tools gnatxref and gnatfind::
+@ifclear FSFEDITION
* The GNAT Pretty-Printer gnatpp::
@ifclear vms
* The Ada-to-XML converter gnat2xml::
@end ifclear
* The GNAT Metrics Tool gnatmetric::
+@end ifclear
* File Name Krunching with gnatkr::
* Preprocessing with gnatprep::
* The GNAT Library Browser gnatls::
@end ifclear
* Memory Management Issues::
* Stack Related Facilities::
+@ifclear FSFEDITION
* Verifying Properties with gnatcheck::
* Creating Sample Bodies with gnatstub::
* Creating Unit Tests with gnattest::
+@end ifclear
* Performing Dimensionality Analysis in GNAT::
* Generating Ada Bindings for C and C++ headers::
* Other Utility Programs::
@item
@ref{Improving Performance}, shows various techniques for making your
-Ada program run faster or take less space.
-It discusses the effect of the compiler's optimization switch and
-also describes the @command{gnatelim} tool and unused subprogram/data
-elimination.
+Ada program run faster or take less space and describes the effect of
+the compiler's optimization switch.
+It also describes
+@ifclear FSFEDITION
+the @command{gnatelim} tool and
+@end ifclear
+unused subprogram/data elimination.
@item
@ref{Renaming Files with gnatchop}, describes
@code{gnatxref} and @code{gnatfind}, two tools that provide an easy
way to navigate through sources.
+@ifclear FSFEDITION
@item
@ref{The GNAT Pretty-Printer gnatpp}, shows how to produce a reformatted
version of an Ada source file with control over casing, indentation,
comment placement, and other elements of program presentation style.
+@end ifclear
+@ifclear FSFEDITION
@ifclear vms
@item
@ref{The Ada-to-XML converter gnat2xml}, shows how to convert Ada
source code into XML.
@end ifclear
+@end ifclear
+@ifclear FSFEDITION
@item
@ref{The GNAT Metrics Tool gnatmetric}, shows how to compute various
metrics for an Ada source file, such as the number of types and subprograms,
and assorted complexity measures.
+@end ifclear
@item
@ref{File Name Krunching with gnatkr}, describes the @code{gnatkr}
and in particular the GNAT Debug Pool facility, which helps detect incorrect
memory references.
@ifclear vms
+@ifclear FSFEDITION
It also describes @command{gnatmem}, a utility that monitors dynamic
allocation and deallocation and helps detect ``memory leaks''.
@end ifclear
+@end ifclear
@item
@ref{Stack Related Facilities}, describes some useful tools associated with
stack checking and analysis.
+@ifclear FSFEDITION
@item
@ref{Verifying Properties with gnatcheck}, discusses @code{gnatcheck},
a utility that checks Ada code against a set of rules.
@item
@ref{Creating Sample Bodies with gnatstub}, discusses @code{gnatstub},
a utility that generates empty but compilable bodies for library units.
+@end ifclear
+@ifclear FSFEDITION
@item
@ref{Creating Unit Tests with gnattest}, discusses @code{gnattest},
a utility that generates unit testing templates for library units.
+@end ifclear
@item
@ref{Performing Dimensionality Analysis in GNAT}, describes the Ada 2012
style rules we have chosen for the GNAT sources. If you are starting
a project which does not have established style standards, you may
find it useful to adopt the entire set of GNAT coding standards, or
-some subset of them. If you already have an established set of coding
-standards, then it may be that selected style checking options do
+some subset of them.
+@ifclear FSFEDITION
+If you already have an established set of coding
+standards, then the selected style checking options may
indeed correspond to choices you have made, but for general checking
of an existing set of coding rules, you should look to the gnatcheck
tool, which is designed for that purpose.
+@end ifclear
@ifset vms
@code{(option,option,@dots{})} is a sequence of keywords
This chapter presents several topics related to program performance.
It first describes some of the tradeoffs that need to be considered
and some of the techniques for making your program run faster.
-It then documents the @command{gnatelim} tool and unused subprogram/data
+It then documents
+@ifclear FSFEDITION
+the @command{gnatelim} tool and
+@end ifclear
+unused subprogram/data
elimination feature, which can reduce the size of program executables.
@ifnottex
@menu
* Performance Considerations::
* Text_IO Suggestions::
+@ifclear FSFEDITION
* Reducing Size of Ada Executables with gnatelim::
+@end ifclear
* Reducing Size of Executables with unused subprogram/data elimination::
@end menu
@end ifnottex
be buffered using @code{Interfaces.C_Streams.setvbuf}.
-
+@ifclear FSFEDITION
@node Reducing Size of Ada Executables with gnatelim
@section Reducing Size of Ada Executables with @code{gnatelim}
@findex gnatelim
@end smallexample
@end enumerate
+@end ifclear
@node Reducing Size of Executables with unused subprogram/data elimination
@section Reducing Size of Executables with Unused Subprogram/Data Elimination
A number of GNAT tools, other than @command{^gnatmake^gnatmake^}
can benefit from project files:
(@command{^gnatbind^gnatbind^},
+@ifclear FSFEDITION
@command{^gnatcheck^gnatcheck^},
+@end ifclear
@command{^gnatclean^gnatclean^},
+@ifclear FSFEDITION
@command{^gnatelim^gnatelim^},
+@end ifclear
@command{^gnatfind^gnatfind^},
@command{^gnatlink^gnatlink^},
@command{^gnatls^gnatls^},
+@ifclear FSFEDITION
@command{^gnatmetric^gnatmetric^},
@command{^gnatpp^gnatpp^},
@command{^gnatstub^gnatstub^},
+@end ifclear
and @command{^gnatxref^gnatxref^}). However, none of these tools can be invoked
directly with a project file switch (@option{^-P^/PROJECT_FILE=^}).
They must be invoked through the @command{gnat} driver.
@item CHOP to invoke @command{^gnatchop^gnatchop^}
@item CLEAN to invoke @command{^gnatclean^gnatclean^}
@item COMP or COMPILE to invoke the compiler
+@ifclear FSFEDITION
@item ELIM to invoke @command{^gnatelim^gnatelim^}
+@end ifclear
@item FIND to invoke @command{^gnatfind^gnatfind^}
@item KR or KRUNCH to invoke @command{^gnatkr^gnatkr^}
@item LINK to invoke @command{^gnatlink^gnatlink^}
@item MAKE to invoke @command{^gnatmake^gnatmake^}
@item NAME to invoke @command{^gnatname^gnatname^}
@item PREP or PREPROCESS to invoke @command{^gnatprep^gnatprep^}
+@ifclear FSFEDITION
@item PP or PRETTY to invoke @command{^gnatpp^gnatpp^}
@item METRIC to invoke @command{^gnatmetric^gnatmetric^}
@item STUB to invoke @command{^gnatstub^gnatstub^}
+@end ifclear
@item XREF to invoke @command{^gnatxref^gnatxref^}
@end itemize
@end smallexample
@noindent
-In addition, for commands BIND, COMP or COMPILE, FIND, ELIM, LS or LIST, LINK,
-METRIC, PP or PRETTY, STUB and XREF, the project file related switches
+In addition, for commands BIND, COMP or COMPILE, FIND,
+@ifclear FSFEDITION
+ELIM,
+@end ifclear
+LS or LIST, LINK,
+@ifclear FSFEDITION
+METRIC,
+PP or PRETTY,
+STUB,
+@end ifclear
+and XREF, the project file related switches
(@option{^-P^/PROJECT_FILE^},
@option{^-X^/EXTERNAL_REFERENCE^} and
@option{^-vP^/MESSAGES_PROJECT_FILE=^x}) may be used in addition to
the switches of the invoking tool.
+@ifclear FSFEDITION
When GNAT PP or GNAT PRETTY is used with a project file, but with no source
specified on the command line, it invokes @command{^gnatpp^gnatpp^} with all
the immediate sources of the specified project file.
+@end ifclear
+@ifclear FSFEDITION
When GNAT METRIC is used with a project file, but with no source
specified on the command line, it invokes @command{^gnatmetric^gnatmetric^}
with all the immediate sources of the specified project file and with
@option{^-d^/DIRECTORY^} with the parameter pointing to the object directory
of the project.
+@end ifclear
+@ifclear FSFEDITION
In addition, when GNAT PP, GNAT PRETTY or GNAT METRIC is used with
a project file, no source is specified on the command line and
switch ^-U^/ALL_PROJECTS^ is specified on the command line, then
@ifclear vms
(-U stands for Universal or Union of the project files of the project tree)
@end ifclear
+@end ifclear
For each of the following commands, there is optionally a corresponding
package in the main project.
@itemize @bullet
@item package @code{Binder} for command BIND (invoking @code{^gnatbind^gnatbind^})
+@ifclear FSFEDITION
@item package @code{Check} for command CHECK (invoking
@code{^gnatcheck^gnatcheck^})
+@end ifclear
@item package @code{Compiler} for command COMP or COMPILE (invoking the compiler)
@item package @code{Cross_Reference} for command XREF (invoking
@code{^gnatxref^gnatxref^})
+@ifclear FSFEDITION
@item package @code{Eliminate} for command ELIM (invoking
@code{^gnatelim^gnatelim^})
+@end ifclear
@item package @code{Finder} for command FIND (invoking @code{^gnatfind^gnatfind^})
@item package @code{Gnatls} for command LS or LIST (invoking @code{^gnatls^gnatls^})
+@ifclear FSFEDITION
@item package @code{Gnatstub} for command STUB
(invoking @code{^gnatstub^gnatstub^})
+@end ifclear
@item package @code{Linker} for command LINK (invoking @code{^gnatlink^gnatlink^})
+@ifclear FSFEDITION
@item package @code{Check} for command CHECK
(invoking @code{^gnatcheck^gnatcheck^})
+@end ifclear
+@ifclear FSFEDITION
@item package @code{Metrics} for command METRIC
(invoking @code{^gnatmetric^gnatmetric^})
+@end ifclear
+@ifclear FSFEDITION
@item package @code{Pretty_Printer} for command PP or PRETTY
(invoking @code{^gnatpp^gnatpp^})
+@end ifclear
@end itemize
@code{^Default_Switches^Default_Switches^ ("Ada")} for all tools,
except @code{Switches ("main.adb")}
for @code{^gnatlink^gnatlink^}.
+@ifclear FSFEDITION
It is also possible to invoke some of the tools,
(@code{^gnatcheck^gnatcheck^},
@code{^gnatmetric^gnatmetric^},
tool invoked by the @command{gnat} driver are explicitly specified
either directly or through the tool @option{-files} option, then the tool
is called only for these explicitly specified files.
+@end ifclear
@c *****************************************
@c * Cross-referencing tools
@end table
+@ifclear FSFEDITION
@c *********************************
@node The GNAT Pretty-Printer gnatpp
@chapter The GNAT Pretty-Printer @command{gnatpp}
end Test;
@end cartouche
@end smallexample
+@end ifclear
+@ifclear FSFEDITION
@ifclear vms
@c *********************************
@node The Ada-to-XML converter gnat2xml
formal_package_declaration_with_box
@end smallexample
@end ifclear
+@end ifclear
+
+@ifclear FSFEDITION
@c *********************************
@node The GNAT Metrics Tool gnatmetric
@chapter The GNAT Metrics Tool @command{gnatmetric}
obtained via the following switch:
@table @option
-@cindex @option{^-n@var{x}^/SUPPRESS^} (@command{gnatmetric})
+@cindex @option{^-nolocal^/SUPPRESS^} (@command{gnatmetric})
@item ^-nolocal^/SUPPRESS=LOCAL_DETAILS^
Do not compute detailed metrics for eligible local program units
gnat metric -Pproj -U main
@end smallexample
@end ignore
+@end ifclear
@c ***********************************
and in particular the GNAT Debug Pool facility, which can be used to detect
incorrect uses of access values (including ``dangling references'').
@ifclear vms
+@ifclear FSFEDITION
It also describes the @command{gnatmem} tool, which can be used to track down
``memory leaks''.
@end ifclear
+@end ifclear
@menu
* Some Useful Memory Pools::
* The GNAT Debug Pool Facility::
@ifclear vms
+@ifclear FSFEDITION
* The gnatmem Tool::
@end ifclear
+@end ifclear
@end menu
@node Some Useful Memory Pools
@end smallexample
@ifclear vms
+@ifclear FSFEDITION
@node The gnatmem Tool
@section The @command{gnatmem} Tool
@findex gnatmem
@noindent
The allocation root #1 of the first example has been split in 2 roots #1
and #3 thanks to the more precise associated backtrace.
-
+@end ifclear
@end ifclear
@node Stack Related Facilities
The package @code{GNAT.Task_Stack_Usage} provides facilities to get
stack usage reports at run-time. See its body for the details.
+@ifclear FSFEDITION
@c *********************************
@c * GNATCHECK *
@c *********************************
through @command{gnatcheck} switches.
For full details, refer to @cite{GNATcheck Reference Manual} document.
+@end ifclear
-
+@ifclear FSFEDITION
@c *********************************
@node Creating Sample Bodies with gnatstub
@chapter Creating Sample Bodies with @command{gnatstub}
Verbose mode: generate version information.
@end table
+@end ifclear
+@ifclear FSFEDITION
@c *********************************
@node Creating Unit Tests with gnattest
@chapter Creating Unit Tests with @command{gnattest}
@item tests for protected subprograms and entries
@end itemize
+@end ifclear
+
@c *********************************
@node Performing Dimensionality Analysis in GNAT
but there are some general options that should be defined in this
package. @xref{Main Subprograms}, and @pxref{Executable File Names} in
particular.
+@ifclear FSFEDITION
@item Check
This package specifies the options used when calling the checking tool
@command{gnatcheck} via the @command{gnat} driver. Its attribute
@code{Builder}. The first string should always be @code{-rules} to specify
that all the other options belong to the @code{-rules} section of the
parameters to @command{gnatcheck}.
+@end ifclear
@item Clean
This package specifies the options used when cleaning a project or a project
tree using the tools @command{gnatclean} or @command{gprclean}.
@command{gnatxref} via the @command{gnat} driver. Its attributes
@b{Default_Switches} and @b{^Switches^Switches^} have the same semantics as for the
package @code{Builder}.
+@ifclear FSFEDITION
@item Eliminate
This package specifies the options used when calling the tool
@command{gnatelim} via the @command{gnat} driver. Its attributes
@b{Default_Switches} and @b{^Switches^Switches^} have the same semantics as for the
package @code{Builder}.
+@end ifclear
@item Finder
This package specifies the options used when calling the search tool
@command{gnatfind} via the @command{gnat} driver. Its attributes
@item ^Gnatls^Gnatls^
This package specifies the options to use when invoking @command{gnatls}
via the @command{gnat} driver.
+@ifclear FSFEDITION
@item ^Gnatstub^Gnatstub^
This package specifies the options used when calling the tool
@command{gnatstub} via the @command{gnat} driver. Its attributes
@b{Default_Switches} and @b{^Switches^Switches^} have the same semantics as for the
package @code{Builder}.
+@end ifclear
@item IDE
This package specifies the options used when starting an integrated
development environment, for instance @command{GPS} or @command{Gnatbench}.
@item Linker
This package specifies the options used by the linker.
@xref{Main Subprograms}.
+@ifclear FSFEDITION
@item Metrics
This package specifies the options used when calling the tool
@command{gnatmetric} via the @command{gnat} driver. Its attributes
@b{Default_Switches} and @b{^Switches^Switches^} have the same semantics as for the
package @code{Builder}.
+@end ifclear
@item Naming
This package specifies the naming conventions that apply
to the source files in a project. In particular, these conventions are
used to automatically find all source files in the source directories,
or given a file name to find out its language for proper processing.
@xref{Naming Schemes}.
+@ifclear FSFEDITION
@item Pretty_Printer
This package specifies the options used when calling the formatting tool
@command{gnatpp} via the @command{gnat} driver. Its attributes
@b{Default_Switches} and @b{^Switches^Switches^} have the same semantics as for the
package @code{Builder}.
+@end ifclear
@item Remote
This package is used by @command{gprbuild} to describe how distributed
compilation should be done.
* Project Level Attributes::
* Package Binder Attributes::
* Package Builder Attributes::
+@ifclear FSFEDITION
* Package Check Attributes::
+@end ifclear
* Package Clean Attributes::
* Package Compiler Attributes::
* Package Cross_Reference Attributes::
+@ifclear FSFEDITION
* Package Eliminate Attributes::
+@end ifclear
* Package Finder Attributes::
* Package ^gnatls^gnatls^ Attributes::
+@ifclear FSFEDITION
* Package ^gnatstub^gnatstub^ Attributes::
+@end ifclear
* Package IDE Attributes::
* Package Install Attributes::
* Package Linker Attributes::
+@ifclear FSFEDITION
* Package Metrics Attribute::
+@end ifclear
* Package Naming Attributes::
+@ifclear FSFEDITION
* Package Pretty_Printer Attributes::
+@end ifclear
* Package Remote Attributes::
* Package Stack Attributes::
* Package Synchronize Attributes::
@end itemize
+@ifclear FSFEDITION
@node Package Check Attributes
@subsubsection Package Check Attributes
invoking @code{gnatcheck} for the source.
@end itemize
+@end ifclear
@node Package Clean Attributes
@subsubsection Package Clean Attributes
@end itemize
+@ifclear FSFEDITION
@node Package Eliminate Attributes
@subsubsection Package Eliminate Attributes
invoking @code{gnatelim} for the source.
@end itemize
+@end ifclear
@node Package Finder Attributes
@subsubsection Package Finder Attributes
@end itemize
+@ifclear FSFEDITION
@node Package ^gnatstub^gnatstub^ Attributes
@subsubsection Package ^gnatstub^gnatstub^ Attributes
invoking @code{gnatstub} for the source.
@end itemize
+@end ifclear
@node Package IDE Attributes
@subsubsection Package IDE Attributes
@end itemize
+@ifclear FSFEDITION
@node Package Metrics Attribute
@subsubsection Package Metrics Attribute
invoking @code{gnatmetric} for the source.
@end itemize
+@end ifclear
@node Package Naming Attributes
@subsubsection Package Naming Attributes
@end itemize
+@ifclear FSFEDITION
@node Package Pretty_Printer Attributes
@subsubsection Package Pretty_Printer Attributes
invoking @code{gnatpp} for the source.
@end itemize
+@end ifclear
@node Package Remote Attributes
@subsubsection Package Remote Attributes
projects / thirdparty / gcc.git / commitdiff
