Debian policy for Ada
*********************

Third Edition for Debian 5.0 Lenny (2008-11-01)

   Copyright (C) 2004, 2006, 2008 Ludovic Brenta
<ludovic@ludovic-brenta.org>

   This document is free; you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free
Software Foundation; either version 2 of the License or (at your
option) any later version.

   This program is distributed in the hope that it will be useful but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
General Public License for more details.

   You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software Foundation,
Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA

1 Introduction
**************

This document describes all there is to know about Ada in Debian.  Most
of it contains my personal thoughts and opinions, although I try to get
the facts straight.  I would appreciate it if you could send me
corrections or additions at ludovic@ludovic-brenta.org.

   After posting the first draft, I received numerous comments to
improve this document.  In particular, I would like to thank Dan Eilers
of Irvine Compiler Corporation for providing me with details about GCC.
Other contributors include Simon Wright, Ed Falis, Georg Bauhaus, and
Bob Rogers.

   Each chapter and appendix in this Policy is either informative or
normative.  Normative chapters contain binding rules that all packages
compiled from Ada sources must follow; informative chapters only
contain useful information.

2 Background information
************************

(This chapter is informative)

2.1 History of GNAT
===================

GNAT started as the GNU New-York University Ada Translator in 1994.
Under a contract with the US Department of Defense, a team at NYU
started writing GNAT as a reference implementation of the upcoming Ada
95 ISO standard.  The contract mandated the use of the GNU General
Public Licence for the compiler.

   After the Ada 95 standard was published, various corporations and DoD
services started using GNAT in mission-critical projects, and asked for
support.  The authors of GNAT formed AdaCore to meet these needs and
further develop GNAT.  Today, AdaCore has offices in New York
(`http://www.adacore.com') and Paris (`http://www.adacore.fr').  GNAT
is still free software under the GPL.  AdaCore offers commercial
support for it and continues development.

   Over the years, several institutions contributed software to
complement GNAT.  For example, the Ecole Nationale Superieure de
Telecommunications in Paris contributed GLADE, an implementation of
Annex E (Distributed Systems) for GNAT.  AdaCore commercially supports
most of these contributions, and distributes them together with GNAT to
supported customers.  As a result, at one point, the GNAT acronym stood
for GNU Ada Technology.  Nowadays it is no longer considered an acronym.

2.2 The variants of GNAT
========================

There are several places to get GNAT from, and different GNATs which,
for lack of a better word, I call "variants".  Each has a different
binary interface from the others; it is therefore not possible to link
object files produced by different variants into an executable; nor is
it possible to link an executable produced by one variant with
libraries produced by another.  The variants of GNAT are:

   * GNAT Pro, commercially supported and actively maintained by AdaCore
     (`http://www.adacore.com').  New releases are frequent but
     provided only to paying customers, under the GNAT-Modified GPL
     described below.  AdaCore runs a test suite comprising more than
     10,000 tests against this compiler, every night, on every supported
     platform.  This test suite consists not only of the ACATS (the
     official ISO standard test suite for validated Ada compilers) but
     also of test cases for all bug reports ever submitted to AdaCore.
     This test suite thus ensures that no bug is ever reintroduced.
     GNAT Pro is being enhanced to implement the upcoming Ada 2005
     standard; the new features are refined as the draft standard
     itself evolves.  If you require GNAT Pro for professional work,
     please contact AdaCore at sales@adacore.com.

   * The Public versions of GNAT ("p" releases).  From time to time,
     AdaCore used to release a stable version of GNAT to the public at
     no cost and under the GNAT-Modified GPL.  These releases benefited
     from bug fixes sent to paying customers, and underwent the same
     extensive test suite as GNAT Pro but were not supported by
     AdaCore.  The last "p" release is GNAT 3.15p in October 2002.
     This is the default Ada compiler in Debian 3.1 "Sarge".  It is
     still possible to download gnat 3.15p source and binaries for
     various platforms from mirrors such as Ada-Belgium
     (ftp://ftp.cs.kuleuven.ac.be/pub/Ada-Belgium/mirrors/gnu-ada/3.15p/)
     and SourceForge (http://sourceforge.net/projects/gnuada).

   * The FSF variant of GNAT.  This is the Ada front-end which has been
     distributed as part of GCC since version 3.1.  The license terms of
     the run-time library are still (as of this edition) the
     GNAT-Modified GPL.

   * The GNAT Academic Programme (GAP) allows registered academics
     (i.e. university professors and their students) to obtain a copy of
     GNAT Pro, with support, at no cost.  However, in newer (2005 and
     later) releases, the license terms of the run-time library changed
     to pure GPL.  Thus, binaries produced with this variant can only be
     distributed under GPL.

   * The GNAT GPL Edition is similar to the GNAT Academic Programme but
     is available to the general public from AdaCore's Libre Software
     site (http://libre.adacore.com).  This Edition replaces the former
     "p" releases.

   The GNAT-Modified GPL is the GPL with the following text added to
each source file:

   "As a special exception, if other files instantiate generics from
this unit or you link this unit with other files to produce an
executable, this unit does not by itself cause the resulting executable
to be covered by the GNU General Public License.  This exception does
not however invalidate any other reasons why the executable file might
be covered by the GNU Public License."

   Thus, the GNAT-Modified GPL permits the distribution of proprietary
software linked with the GNAT run-time library, libgnat.  The pure GPL
disallows this, as any binary linked with a GPL library must also be
distributed under GPL or not at all.  This does not apply to your
source text: your source program is not linked with libgnat, therefore
you can distribute it under whichever licensing terms you choose, even
non-disclosure agreements.

2.3 Timeline of GNAT releases
=============================

2.3.1 GNAT Pro releases
-----------------------

*Announced*  *Release**Based on*  *gnatgcc
                                  -v*
2003-02-18   3.16a    GCC 2.8.1   2003-01-20
2003-07-01   3.16a1   GCC 2.8.1   2003-06-20
2003-08-21   5.01a    GCC 3.2.3   2003-08-08
2004-02-26   5.02a    GCC 3.2.3   2004-01-16
2005-02-21   5.03a    GCC 3.4.1   2005-01-14
2006-01-30   5.04     GCC 3.4.4   2006-01-30
2006-05-09   5.05     GCC 3.4.6   ?
2007-03-07   6.0.1    GCC 4.1.3   ?
2008-03-05   6.1.1    GCC 4.1.3   ?

   In addition to these full releases, supported customers sometimes
receive a "wavefront" release, with "w" in their version number, e.g.
5.02w.  As the name suggests, the "wavefront" changes constantly as
GNAT evolves.

   Version 6.0.1 is the first to officially support the full Ada 2005
standard.  It also uses a new version numbering scheme.  The major
version number will change infrequently when the back-end changes to a
new version of GCC.  The minor number will change about once a year
like in the old scheme; and the micro number will be 0 for a beta
release, 1 for a first production release, and 2 or greater for a
bug-fix release.

2.3.2 Public releases from AdaCore
----------------------------------

The dates in this timeline are the timestamps of the source files for
each release, as stored in the tar.gz archive.  These dates sometimes
differ from the hardcoded "release date" which is visible with "gnatgcc
-v".

*Date*       *Release**Based      *gnatgcc -v*
                      on:*
1995-11-29   3.01p    GCC 2.7.2   none
1996-05-03   3.04p    GCC 2.7.2   none
1996-06-07   3.05p    GCC 2.7.2   1996-06-07
1996-10-23   3.07p    GCC 2.7.2   1996-10-23
1997-01-21   3.09p    GCC 2.7.2   1997-01-21
1997-08-14   3.10p    GCC 2.7.2   1997-08-14
1998-12-18   3.11p    GCC 2.8.1   1998-11-18
1999-09-24   3.12p    GCC 2.8.1   1999-06-29
2000-07-19   3.13p    GCC 2.8.1   2000-05-09
2001-10-07   3.14p    GCC 2.8.1   2001-05-03
2002-10-24   3.15p    GCC 2.8.1   2002-05-23
2005-09-15   2005     GCC 3.4.4   2005-05-24
2006-05-22   2006     GCC 3.4.6   2006-05-22
2007-05-11   2007     GCC 4.1.2   2007-04-03
2008-06-12   2008     GCC 4.1.3   2008-04-17

   The GNAT GPL 2005 Edition changes the licensing terms of the run-time
library to the pure GPL, thereby disallowing the distribution of
non-GPL programs linked with this Edition's run-time library.

2.3.3 GNAT Academic Programme and GNAT GPL Edition
--------------------------------------------------

The GNAT Academic Programme started in 2004.  Under this Programme,
AdaCore made GNAT Pro available at no cost to registered academics.  On
top of this, professors received support from AdaCore at no cost.  GAP
versions 1.0 and 1.1 came with the full complement of tools and
libraries then current for paying customers, all under GMGPL.
Subsequent releases are identical to the GNAT GPL releases starting
with 2005.

2.3.4 FSF releases
------------------

In October 2001, AdaCore contributed their most recent GNAT Pro source
code for the Ada 95 front-end and runtime library to the GCC source
repository.  The first release of GCC that included GNAT was 3.1 in May
2002.  After that, little activity took place on the Ada parts of GCC;
thus, GCC 3.1, 3.2 and 3.3 contain essentially the same Ada front-end
and library.

   In October 2003, after the second merge of GNAT Pro into GCC, AdaCore
closed their own public CVS server, and started doing routine commits
to the FSF's repository.

   AdaCore only work on the main line of development; this means that
no, or very few changes take place in minor versions of GCC, and I don't
show them in the table below.  This also means that AdaCore only merge
from their internal repository during Stage 1
(http://gcc.gnu.org/develop.html) of the development cycle of each
major release of GCC.

2001-10-01   First merge into GCC
2002-05-22   3.1
2002-08-14   3.2
2003-05-13   3.3
2003-10-21   Second merge into GCC
2004-04-18   3.4
2005-04-20   4.0
2006-02-28   4.1
2007-05-13   4.2
2008-03-05   4.3

   GCC 3.4 has several new packages in the GNAT library, most notably a
first version of the Ada 2005 container library, and also the "limited
with" feature of Ada 2005.  It also benefits from the new targets
introduced in recent versions of GCC, such as AMD64 (also known as
x86-64).  There are approximately 70 bug fixes relative to GCC 3.3.

   However, it also has a serious regression: it does not support
tasking on `powerpc-*-linux' (see ada/13897).

   A subset of ACATS 2.5 (basically the executable tests but not the
tests with intentional errors) is included in GCC 3.4 and later.  GCC
3.4 passes all of these tests.

   GCC 4.0's Ada front-end restores tasking on powerpc, fixes about 100
bugs, and contains a newer version of the container library.  One very
major change inside GCC 4.0 warranted the new major version number.
This change, called "tree-SSA", is a new infrastructure for optimisers,
and a new interface between front-ends and the back-end of the
compiler.  This required updating all the language front-ends.
Unfortunately, these changes introduced some bugs too, including a few
ACATS failures.

   GCC 4.1's Ada front-end contains a further 60 bug fixes, brings the
Ada.Containers library closer to the definitive Ada 2005 standard, and
has a more mature interface to Tree-SSA.  The entire ACATS passes in
this release.  This is the default Ada compiler in Debian 4.0 "Etch".

   In GCC 4.2, the Ada run-time library provides many more packages from
the new language standard, support AltiVec instructions on machines
that support them, and a software emulation of AltiVec on machines that
don't.  The compiler front-end supports more Ada 2005 features, in
particular related to interfaces, tagged protected and tagged task
types.

   GCC 4.3 is the best release so far, with 110 bug fixes and several
additional Ada 2005 packages (e.g. Ada.Calendar.Formatting).  This is
the default Ada compiler in Debian 5.0 "Lenny".

2.4 ASIS, GLADE and Florist
===========================

ASIS is the Ada Semantic Interface Specification.  GNAT conforms to
this Specification, and exposes the parse tree of programs, so that
other programs can query and manipulate the parse tree.  The ASIS
distribution comes with several such programs, for example "gnatpp" a
pretty-printer or "gnatelim" which eliminates unused subprograms.
Third-party programs that take advantage of ASIS include the "gch" and
"adastyle" style checkers, "adabrowse" the document generator,
"adasubst" which does mass substitutions of identifier names, and
"adadep" which manages dependencies between compilation units.

   GLADE is the Ecole Nationale de Telecommunications' implementation of
the Distributed Systems annex (Annex E) of the Ada standard.  With
GLADE, it is possible to write a set of programs that run on different
machines and communicate by means of remote procedure calls and shared
objects.  In Ada parlance, these programs are called "partitions" and
the entire system is the "program".  In 2008, GLADE was superseded by
PolyORB, a general middleware technology supporting not only Annex E
but also CORBA, SOAP and several other specifications for distributed
systems, all at the same time.

   Florist is Florida State University's implementation of POSIX.5
standard, which allows Ada programs to use POSIX system services such
as shared memory, pipes, and message queues.

   All GNAT Pro, GAP, GPL and "p" releases of GNAT come with ASIS,
GLADE or PolyORB, and Florist.  In contrast, FSF releases come with
none of them.  Both GLADE and PolyORB rely on parts of GNAT's internal
implementation, so porting them from a GPL Edition to GCC requires
intimate knowledge of GNAT.

2.5 GDB, the GNU debugger
=========================

Because debugging information is in a standard format in object files,
you can use GDB to debug programs written in any language.  However,
special Ada support allows GDB to demangle names and to understand Ada
syntax when displaying variables.

   GNAT 3.15p comes with a patched GDB 4.17 which understands Ada.

   In 2003, AdaCore released a similarly patched GDB 5.3 which
understands Ada; this is the `gnat-gdb' shipped as part of Debian 3.1
"Sarge".

   In GCC 3.4, the default format for debugging information changed from
STABS to DWARF2.  This change breaks compatibility with GDB 5.3; it is
possible to force GCC to use the old STABS format by compiling with the
`-gstabs+' option, like this:

   `gnatmake -gstabs+ my_program'

   As part of the GNAT GPL 2005 Edition (2005-09-15), AdaCore released
an updated patch to GDB 5.3 and also a new patch to GDB 6.3, which
understands DWARF2 natively and is the `gnat-gdb' in Debian 4.0 "Etch".

   AdaCore's patches were eventually merged into GDB. Thus, GDB 6.7 can
debug Ada programs out of the box.  As a consequence, starting with
Debian 5.0 "Lenny", there is no longer a need for a separate `gnat-gdb'
package.

2.6 History of Ada standards
============================

Ada, as an ISO standard, undergoes at least one review every 5 years.
The timeline of past standards is as follows:

1980   MIL-STD-1815
1983   ANSI/MIL-STD-1815A
1987   Ada 83: ISO/IEC 8652:1987
1995   Ada 95: ISO/IEC 8652:1995
2001   Ada 95 Technical Corrigendum
2007   Ada 95 Amendment 1

   There is a validation suite for Ada, called ACATS (Ada Conformity
Assessment Test Suite).  The current version, 2.5, is effective since
2002-04-01.

   The current standard, informally known as "Ada 2005" or simply
"Ada", is formally ISO/IEC 8652:1995 with Technical Corrigendum 1:2001
and Amendment 1:2007.  The name "Ada 2005" was chosen when the ISO
Working Group responsible for the standard (WG9) froze the
specification.

   As of 2008, work is under way to update the ASIS specification
(ISO/IEC 15291:1999) for the new Ada 2005 features.

3 The Debian Ada compiler
*************************

(This chapter is normative.)

   Rule: Package `gnat' is the default Ada compiler for Debian.  All
packages containing Ada programs or libraries SHALL use this compiler.

   Rationale: This allows all programs and libraries to use the same
ABI, so we can link them together.

   Additional information: The default Ada compiler for Debian is as
follows.  Some versions of Debian provide alternative versions of GNAT.
These alternative versions are for experimental purposes only; they
receive no support and Debian packages may not build-depend on any of
them.

*Debian release*   *Default Ada compiler*   *Alternatives*       *Supported Platforms*
2.0 Ham            GNAT 3.07                                     i386
2.1 Slink          GNAT 3.10p                                    i386
2.2 Potato         GNAT 3.12p                                    i386
3.0 Woody          GNAT 3.14p                                    i386, powerpc, sparc
3.1 Sarge          GNAT 3.15p               gnat-3.3, gnat-3.4   i386, powerpc, sparc
4.0 Etch           GCC 4.1                                       +amd64, hppa, hppa64, ia64,
                                                                 kfreebsd-i386, ppc64, sparc64
5.0 Lenny          GCC 4.3                                       +alpha, mips, mipsel

4 Policy for Ada libraries
**************************

(This section is informative.)

   In this section, I will lay out my policy for Ada libraries.  This is
mostly interesting if you want to package additional libraries.  I
would be delighted to hear from you if you contemplate packaging Ada
software for Debian and I can help you get started.

   If you only want to use libraries, see Using shared libraries.

   The goal of this policy is to make Debian a robust and complete
development platform for Ada programmers.  This platform should appeal
both to seasoned programmers and beginners.  The basic tenet is that it
Just Works.  At the same time, the Policy makes Debian an equally
attractive deployment platform for users of Ada programs.  Thanks to
Debian's outstanding package management system, users simply `apt-get
install' watever package they want to use and `apt-get' installs all
the required run-time libraries.  The Policy ensures there are no
conflicts between libraries.

   This policy is based on the GNU Ada Environment Specification
(http://cert.uni-stuttgart.de/projects/ada/gnae.php) as far as is
reasonable.  This specification is an attempt by Florian Weimer to make
all libraries install files in consistent places.

   The GNAE is distribution-agnostic; it mandates a mechanism (similar
to GNOME's pkg-config) to retrieve compiler switches for each library in
a uniform way.  However, thanks to GNAT project files, this is
unnecessary; and Debian's packaging system handles dependencies.  So,
what follows is a stripped-down version of the GNAE suitable for Debian.

4.1 Building a library for reuse
================================

(This section is informative.)

   For some libraries, the upstream authors provide a `Makefile' that
does not compile all of the source files of the library; in particular,
some upstream `Makefile's do not compile all generic bodies.  These
upstream authors assume one of the following:

   * The library user has permission to write into the library's
     directory structure and uses GNAT project files or `gnatmake -i'.

   * The library user compiles the library's source code into their
     application, using `gnatmake -I'.

   * The library user copies the sources of the library into their
     program's directory structure.

   However, in Debian, none of the above applies.  If the Debian
maintainer were to use such `Makefile's and installed the `*.ali' files
in `/usr/lib/ada/adalib/LIBRARY', then some `*.ali' files would be
missing.  This would be a problem for non-root users, because they are
not allowed to write `*.ali' files in `/usr/lib/ada/adalib/LIBRARY'.
To prevent this, it is sometimes necessary for the Debian package
maintainer to bypass upstream's `Makefile' with a scheme that ensures
that all files are compiled.  Here is a sample from
`debian/build_library.gpr' that demonstrates how to do this:

project LIBRARY is
   for Library_Name use "LIBRARY";
   for Library_Kind use External ("LIBRARY_KIND");
   for Library_Version use External ("SONAME");
   for Source_Dirs use (".");
   for Object_Dir use External ("OBJ_DIR");
   package Compiler is
      for Default_Switches ("Ada") use
        ("-g", "-O2", "-gnatafnoy", "-gnatVa", "-gnatwa", "-fstack-check");
   end Compiler;
   package Binder is
      for Default_Switches ("Ada") use ("-E");
   end Binder;
end LIBRARY;

   A Makefile would call this project file like so:

# Parse the version number from the change log:
# major.minor.micro-revision
regexp:=^Version: \([0-9]\+\)\.\([0-9]\+\)\.\([^-]\+\)-\(.\+\)$$
major:=$(shell dpkg-parsechangelog | grep ^Version: | sed 's/$(regexp)/\1/')
minor:=$(shell dpkg-parsechangelog | grep ^Version: | sed  's/$(regexp)/\2/')
micro:=$(shell dpkg-parsechangelog | grep ^Version: | sed  's/$(regexp)/\3/')
revision:=$(shell dpkg-parsechangelog | grep ^Version: | sed  's/$(regexp)/\4/')

soname:=libLIBRARY.so.$(major)

obj-shared/libLIBRARY.so:
        gnatmake -p -Pbuild_LIBRARY.gpr \
                 -XLIBRARY_KIND=dynamic -XOBJ_DIR=$(dir $@@) -XSONAME=$(soname)

obj-static/libLIBRARY.a:
        gnatmake -p -Pbuild_LIBRARY.gpr \
                 -XLIBRARY_KIND=static -XOBJ_DIR=$(dir $@@)

   This scheme effectively replaces upstream's `Makefile' altogether,
modulo any configuration or preprocessing steps that may be necessary.
I would personally advise upstream library authors to consider using
such a scheme in their `Makefile's.

4.2 Packaging structure
=======================

(This section is normative.)

   Rule: Each Ada library MUST follow the Debian Policy, i.e. it must
consist of at least two, preferably three packages:

`libLIBRARY-dev'
     the development package containing the static libraries and
     development files, in section libdevel.

`libLIBRARYN'
     the run-time package containing the shared library, in section
     libs.

`libLIBRARY-doc'
     the documentation (optional), in section doc.

`libLIBRARY-dbg'
     the separate debugging information for the shared library, in
     section libdevel.

   where N is the major number of the library.

4.3 Files provided by the -dev package
======================================

(This section is normative.)

4.3.1 General rules
-------------------

Rule: The `-dev' package SHALL NOT provide any other files than the
ones described in this section.

   Rule: The `-dev' package SHALL be architecture-dependent (i.e.
`Arch: any' or a specific list of architectures).

   Rule: The `-dev' package SHALL be in the section "libdevel".

4.3.2 Source files
------------------

Rule: The `-dev' package SHALL provide all source files (specs and
bodies) necessary for compilation.

   Rule: Source files SHALL reside in directory
`/usr/include/ada/adainclude/LIBRARY'.

   Recommendation: There should not be any subdirectories under
`/usr/share/ada/adainclude/LIBRARY'.  If the upstream authors split the
sources into several subdirectories, merge all source files into one
directory or else, provide several separate library packages.  If you
insist on providing subdirectories, make sure your project file
(described below) reflects this.

   Rationale: Splitting the sources in several directories makes
navigation in the library source code more difficult in some editors or
debuggers.

   Rule: If the upstream sources require preprocessing the Ada source
files before compilation, then the Ada files in
`/usr/share/ada/adainclude/LIBRARY' SHALL be the preprocessed files
corresponding to the shared library in /usr/lib.

   Rule: The directory with all Ada source files SHALL not contain any
`Makefile's or any other files that might be necessary to recompile the
library.

   Rationale: The intention is not that the user can recompile the
library from `/usr/share/ada/adainclude/LIBRARY'; only that they can
use it in their Ada programs.  They can always recompile the library
from the source package.

   Rule: The `-dev' package SHALL, however, provide any source files in
languages other than Ada (e.g. C) that are compiled into the library.

   Rationale: this allows programmers using GDB to trace the execution
of their programs into the library.  See below The separate debugging information package.

4.3.3 Ada object files
----------------------

Rule: The `-dev' package SHALL NOT provide any `*.o' files.

   Rule: The `-dev' package SHALL provide a static library in
`/usr/lib/libLIBRARY.a'.

4.3.4 Ada Library Information files
-----------------------------------

Rule: The `-dev' package SHALL provide Ada Library Information
(`*.ali') files that `gnatgcc' creates when compiling the shared (not
static) library.

   Rule: The `*.ali' files SHALL have read-only permissions for all
users (i.e. `r--r--r--' or 0444).

   Rule: The `*.ali' files SHALL reside in
`/usr/lib/ada/adalib/LIBRARY'.

   Additional information: In Etch, `lintian', `Linda' and
`dh_fixperms' are aware of these rules and enforce them.

4.3.5 Symbolic link to the shared library
-----------------------------------------

Rule: The `-dev' package SHALL provide a symbolic link to the shared
library, as follows:

     /usr/lib/libLIBRARY.so -> libLIBRARY.so.N.MINOR.PATCH

   where MINOR and PATCH are the minor version number and patch level of
the library.  For example:

     /usr/lib/libtexttools.so -> libtexttools.so.2.0.3

   Rule: The `-dev' package SHALL depend on the run-time package.

4.3.6 GNAT project file
-----------------------

Rule: The `-dev' package for each library SHALL provide a GNAT project
file named `/usr/share/ada/adainclude/LIBRARY.gpr'.

   Rule: The project file SHALL have a `Source_Dirs' attribute
containing at least `/usr/share/ada/adainclude/LIBRARY'.

   Rule: The project file SHALL have a `Library_ALI_Dir' equal to
`/usr/lib/ada/adalib/LIBRARY'.

   Rule: The project file SHALL have a `Library_Name' attribute equal
to the library name of the shared library.

   Rule: The project file SHALL have a `Library_Kind' attribute equal
to `dynamic'.

   Rule: The project file SHALL have a `Library_Dir' attribute equal to
`/usr/lib'.

   Rule: The project file SHALL have an `Externally_Built' attribute
equal to `true'.

   Remark: the presence of `Library_Name' and `Library_Dir' makes the
project file a "library" project file which gnatmake treats specially.
In particular this makes the `Linker' subpackage unnecessary.  See the
GNAT documentation for details.

   Rationale: GNAT does not yet support multilib (i.e. the ability to
use libraries for different architectures on the same machine).  If and
when GNAT supports multilib, `/usr/lib' will be split into
architecture-dependent directories.  This will be addressed by the
general Debian Policy; this specific Debian Policy for Ada will follow
suit.

   Example:

     project LIBRARY is
        for Library_Name use "LIBRARY";
        for Library_Dir use "/usr/lib";
        for Library_Kind use "dynamic";
        for Source_Dirs use ("/usr/share/ada/adainclude/LIBRARY");
        for Library_ALI_Dir use "/usr/lib/ada/adalib/LIBRARY";
        for Externally_Built use "true";
     end LIBRARY;

   Remark: Since the `-dev' and library packages provide precompiled
libraries, it is not necessary to provide `package Compiler' or
`package Builder' in the project file.

4.3.7 Documentation
-------------------

Rule: The `-dev' package SHALL have a `README.Debian' that explains how
to use the library in new programs.

   Additional information: This file is not mandatory per Debian Policy,
but this Debian Ada Policy does require it.  See Using shared libraries
for details.

4.4 Files provided by the run-time shared library package
=========================================================

Rule: The run-time shared library package (libLIBRARYN) SHALL provide
these two files:

     /usr/lib/libLIBRARY.so.N.MINOR.PATCH
     /usr/lib/libLIBRARY.so.N -> libLIBRARY.so.N.MINOR.PATCH

   where MINOR and PATCH are the minor version number and patch level of
the library.  For example:

     /usr/lib/libtexttools.so.2.0.3
     /usr/lib/libtexttools.so.2 -> libtexttools.so.2.0.3

   The soname of the shared library must be `libLIBRARY.so.N':

     $ objdump -p /usr/lib/libtexttools.so.2.0.3 | grep SONAME
       SONAME      libtexttools.so.2

4.5 Documentation
=================

(this section is normative.)

   Rule: Documentation other than the `README.Debian' file SHALL be
included either in the `-doc' package or in the `-dev' package.

   Rationale: If the amount of documentation is small or if the
documentation consists mostly of comments in the Ada source files, it
is preferable to place it in the `-dev' package.  The `README.Debian'
file must always be in the `-dev' package, as explained above.

   Remark: You may consider using `adabrowse' to generate HTML
documentation from the source files.

   Rule: If the library provides Info files, then the Info files SHALL
appear under "GNU Ada tools" in the top-level Info directory.

   Additional information: This usually requires adding a few lines near
the top of the first Info file, before the first node.  Here is an
example from package `libaws-doc':

      INFO-DIR-SECTION GNU Ada tools
      START-INFO-DIR-ENTRY
      * AWS: (aws).    The Ada Web Server.
      END-INFO-DIR-ENTRY

   If you generate *.info files from *.texi files using makeinfo, the
following lines achieve the desired effect:

      @dircategory GNU Ada tools
      @direntry
      * AWS: (aws).    The Ada Web Server.
      @end direntry

   Based on this information, dh_installinfo takes care of updating the
top-level Info directory.

   Rule: If the library provides example source files, they SHALL reside
under `/usr/share/doc/LIBRARY-doc/examples' or, if there is no `-doc'
package, in `/usr/share/doc/LIBRARY-dev/examples'.

   Rule: Neither the source files, nor any `Makefile' present in the
examples, SHALL be compressed.

   Additional information: Be careful if you use dh_installexamples, as
it compresses any files larger than 4 kiB by default -- use `-X.ads
-X.adb -XMakefile' as appropriate.

4.6 The separate debugging information package
==============================================

(this section is normative.)

   Recommendation: the package maintainer SHOULD provide a package named
`libLIBRARY-dbg' containing the debugging symbols for the shared
library.

   Rule: the `libLIBRARY-dbg' package, if any, SHALL depend on the
run-time shared library package and be in section "libdevel".

   Rationale: Debian has a mechanism for producing and using `-dbg'
packages containing debugging information.  For this to work, you must
compile the shared library with `-g' and the `-dbg' package must appear
in `debian/control'.  Then, you call `dh_strip -plibLIBRARYN
--dbg-package=libLIBRARY-dbg' from within `debian/rules'.  Since that's
all there is to it, package maintainers have little excuse not to
provide a `-dbg' package.

5 Using shared libraries
************************

(This chapter is informative)

   As a consequence of the Debian policy for Ada libraries, users of the
`-dev' packages have three consistent ways of using libraries in their
programs:

     ADA_INCLUDE_PATH += :/usr/share/ada/adainclude/LIBRARY
     ADA_OBJECTS_PATH += :/usr/lib/ada/adalib/LIBRARY

   or

     gnatmake -aI/usr/share/ada/adainclude/LIBRARY \
       -aO/usr/lib/ada/adalib/LIBRARY \
       PROGRAM \
       -largs -lLIBRARY

   or

   write their own project file and:

     with "LIBRARY";
     project PROGRAM is
        for Source_Dirs use (".");
        for Object_Dir use "obj";
        for Exec_Dir use ".";
        for Main use ("PROGRAM");
     end;

   Starting with Debian 4.0 Etch, GNAT looks for project files in
`/usr/share/ada/adainclude' by default.  In 3.1 Sarge, it was necessary
to specify the full path to the project file in the `with' clause or
set `ADA_PROJECT_PATH' to `/usr/share/ada/adainclude' in the
environment.

   Also, the `.gpr' filename extension is optional in the `with' clause.

   Some upstream library authors provide scripts (e.g.
`/usr/bin/gtkada-config' for GtkAda) but they tend not to work well
when using several libraries simultaneously because the order of the
switches is important.  The recommended way to use libraries is the
project files, especially when using several libraries at the same time:

     with "LIBRARY_ONE";
     with "LIBRARY_TWO";
     project PROGRAM is
        for Source_Dirs use (".");
        for Object_Dir use "obj";
        for Exec_Dir use ".";
        for Main use ("PROGRAM");
     end;

   The user may also wish to use the static library.  Doing this is
straightforward:

     with "LIBRARY";
     project PROGRAM is
        for Source_Dirs use (".");
        for Object_Dir use "obj";
        for Exec_Dir use ".";
        for Main use ("PROGRAM");
        package Linker is
           for Default_Switches ("Ada") use ("/usr/lib/libLIBRARY.a");
        end Linker;
     end;

   The user may also wish to recompile parts of the library into their
program, possibly with different compile-time options.  This is also
possible with GNAT project files but without the library-supplied
project file:

     project PROGRAM is
        for Source_Dirs use (".", "/usr/share/ada/adainclude/LIBRARY");
        for Object_Dir use "obj";
        for Main use ("PROGRAM");
        package Compiler is
           for Default_Switches ("Ada") use
              ("-gnatafoy", "-O3", "-fno-unroll-loops", "-gnatVa", "-gnatwa");
        end Compiler;
     end PROGRAM;

   The above examples can be mixed to suit the user's requirements.  For
example, one library can be linked statically, another can be
compiled-in and a third can be linked dynamically.

5.1 Debugging programs that use shared libraries
================================================

If the package maintainer provides a `-dbg' package, you simply
`apt-get install' it and launch `gdb' on your program (preferably
inside an integrated development environment).  `gdb' automagically
looks for the debugging symbols for the library in the proper place and
will see them with no further help.  However, it may not see the source
files automatically.  If `gdb' fails to find the source files, you need
to say:

     (gdb) dir /usr/share/ada/adainclude/LIBRARY

6 Help wanted
*************

(This chapter is informative)

   Help is wanted to further Ada, Debian and Ada in Debian.  There are
several areas where you can help: as an upstream author or as a
packager.

   As an upstream author, you can contribute to any of the packages
already in Debian.  You can also write new Ada libraries and programs.

   As a packager, you can select existing libraries or software
programs, and package them for Debian.  You should follow the Debian
policy for Ada if you do this.  It is not a healthy situation where the
entire Debian community looks to a single person for all packaging; it
is highly desirable to have at least a backup.  The position is open for
the taking.

   If you are looking for a project to which you can contribute or for
something to package for Debian, here are a few web sites where you can
look:

   * Browse the three main Ada portals: the Ada Information
     Clearinghouse (http://www.adaic.org), Ada Power
     (http://www.adapower.org) and Ada World (http://www.adaworld.com).

   * Look for Ada projects on SourceForge (http://sourceforge.net),
     Berlios (http://developer.berlios.de) and Tigris
     (http://www.tigris.org)

   Please do not hesitate to coordinate with me.

Appendix A Bugs in GNAT
***********************

(This appendix is informative)

   Since I started maitaining GNAT, I have received over a hundred bug
reports against the compiler.  In most of these bugs, GNAT is too lax;
it does not complain when presented with an illegal program.  There are
some quite subtle cases involved; processing these bugs has been a very
good learning experience for me.  You may be interested in perusing
these bugs for your own benefit.

   My processing of these bug reports has been, I believe, quite
thorough.  For each bug:

   * I wrote a small test case that demonstrates the bug (most bug
     reports came with a test case already; this was not much work).

   * I ran the test case against GNAT 3.15p and 3.4.

   * When GNAT 3.15p had the bug, I reported it to the Debian bug
     tracking system.

   * When GCC 3.4 had the bug, I reported it to the GCC Bugzilla
     database.

   * When both versions had the bug, I linked the Debian bug to the GCC
     bug.

   As it turns out, GCC 3.4 has approximately 80% of the bugs of GNAT
3.15p.  It fixes some bugs but also adds a few new ones.

   When possible, I try to track the changes that fix bugs in GCC and
backport them to GNAT 3.15p.  Thus, GNAT 3.15p is under active
maintenance in Debian.  If you would like to contribute, feel free to
send me patches, I will accept them gratefully.

   AdaCore also fix bugs that I report in each major release of GCC.

   The test suite is available in the GNAT source package; to get the
test suite, just `apt-get source gnat' and look in the `testsuite'
directory.

   You can search the Debian bug tracking system on the web here:
`http://bugs.debian.org'

   You can search the GCC bug database here: `http://gcc.gnu.org'.

Appendix B A note about GNAT's shared libraries
***********************************************

(This appendix is informative)

   I've done some extensive research on several GNU/Linux distributions,
and even FreeBSD, to see how they handled libgnat's soname.  Most
distros never included the AdaCore public version of GNAT and started
shipping Ada only after GCC 3.2 went out.

*Variant*   *Version*   *Distribution*       *Shared libraries*                         *soname*
AdaCore     3.07        binary tgz           /usr/lib/libgnat.so.3.07                   libgnat.so
AdaCore     3.09        binary tgz           /usr/lib/libgnat.so.3.09                   libgnat.so
AdaCore     3.12p       Red Hat 7.0          /usr/lib/libgnat-3.12p.so.1.12             libgnat-3.12p.so.1
AdaCore     3.13p       Ada for Linux        /usr/lib/libgnat-3.13p.so.1.8              libgnat-3.13p.so.1
AdaCore     3.13p       Red Hat 7.1          /usr/lib/libgnat-3.13p.so.1.13             libgnat-3.13p.so.1
AdaCore     3.13p       SuSE 8.0             /usr/lib/libgnat-3.13p.so.1.7              libgnat-3.13p.so.1
AdaCore     3.14p       Debian Woody         /usr/lib/libgnat-3.14p.so.1.1              libgnat-3.14p.so.1
AdaCore     3.14p       FreeBSD 4.7          /usr/local/lib/libgnat-3.14.so.1           libgnat-3.14.so.1
AdaCore     3.15p       binary tgz           <prefix>/lib/gcc-lib/.../libgnat-3.15.so   libgnat-3.15.so
AdaCore     3.15p       from source          <prefix>/lib/gcc-lib/.../libgnat-3.15.so   libgnat-3.15.so
AdaCore     3.15p       Debian Sarge         /usr/lib/libgnat-3.15p.so.1.8              libgnat-3.15p.so.1
AdaCore     3.15p       FreeBSD 4.8          /usr/local/lib/libgnat-3.15.so.1           libgnat-3.15.so.1
FSF         3.2         Mandrake 9.0         /usr/lib/libgnat-3.15a.so.1                libgnat-3.15a.so.1
FSF         3.2         Red Hat 8            /usr/lib/libgnat-3.15a.so.1                libgnat-3.15a.so.1
FSF         3.2         SuSE 8.1             /usr/lib/libgnat-3.15a.so                  libgnat-3.15a.so
FSF         3.2.2       ASPLinux             /usr/lib/libgnat-3.15a.so.1                libgnat-3.15a.so.1
FSF         3.2.2       Mandrake 9.1         /usr/lib/libgnat-3.15a.so.1                libgnat-3.15a.so.1
FSF         3.2.2       Red Hat 9            /usr/lib/libgnat-3.15a.so.1                libgnat-3.15a.so.1
FSF         3.2.2       Slackware 9.0        none                                       none
FSF         3.2.2       Yellow Dog           /usr/lib/libgnat-.so.1                     libgnat-.so.1
FSF         3.2.3       Slackware 9.1        none                                       none
FSF         3.3         Polish Linux         /usr/lib/libgnat-3.15.so.1                 libgnat-3.15.so.1
FSF         3.3         SuSE 8.2             /usr/lib/libgnat-3.15.so                   libgnat-3.15.so
FSF         3.3         from source          <prefix>/lib/gcc-lib/.../libgnat-3.15.so   libgnat-3.15.so
FSF         3.3.1       Mandrake 9.2         /usr/lib/libgnat-3.15.so.1                 libgnat-3.15.so.1
FSF         3.3.1       SuSE 9.0             /usr/lib/libgnat-3.15.so                   libgnat-3.15.so
FSF         3.3.2       Fedora Core 1        /usr/lib/libgnat-3.15.so.1                 libgnat-3.15.so.1
FSF         3.3.2       Mandrake 10.0        /usr/lib/libgnat-3.15.so.1                 libgnat-3.15.so.1
FSF         3.3.3       Fedora Core 2        /usr/lib/libgnat-3.15.so.1                 libgnat-3.15.so.1
FSF         3.3.3       SuSE 9.1             /usr/lib/libgnat-3.15.so                   libgnat-3.15.so
FSF         3.3.4       SuSE 9.2             /usr/lib/libgnat-3.15.so                   libgnat-3.15.so
FSF         3.3.5       SuSE 9.3             /usr/lib/libgnat-3.15.so                   libgnat-3.15.so
FSF         3.3.6       Debian Sarge         none                                       none
FSF         3.4         source CVS           <prefix>/lib/gcc-lib/.../libgnat-3.4.so    libgnat-3.4.so
FSF         3.4.1       Mandrake 10.1        /usr/lib/libgnat-3.4.so.1                  libgnat-3.4.so.1
FSF         3.4.2       Fedora Core 3        /usr/lib/libgnat-3.4.so.1                  libgnat-3.4.so.1
FSF         3.4.4       Debian Sarge         /usr/lib/libgnat-3.4.so.1                  libgnat-3.4.so.1
FSF         4.0.0       from source          <prefix>/lib/gcc/.../libgnat-4.0.so        libgnat-4.0.so
FSF         4.0.0       Fedora Core 4        /usr/lib/libgnat-4.0.so.1                  libgnat-4.0.so.1
FSF         4.1.0       from source          <prefix>/lib/gcc/.../libgnat-4.1.so        libgnat-4.1.so
FSF         4.1.0       Debian Etch          /usr/lib/libgnat-4.1.so.1                  libgnat-4.1.so.1
FSF         4.3.0       Debian Lenny         /usr/lib/libgnat-4.3.so.1                  libgnat-4.3.so.1

   The ellipsis (...) stands for <target>/<version>/adalib, for example
`i486-linux-gnu/4.1.0/adalib'.

   All GNU/Linux distributions have historically ignored the AdaCore
default soname and used one consistent pattern, libgnat-x.xxp.so.1.
This includes Debian Woody.  For Sarge and Etch, I have chosen to
continue this tradition.  This allows, by the way, installing both
Debian's and AdaCore's binary distributions on the same system.

Appendix C Ada transition in Debian 4.0 Etch
********************************************

(This appendix is informative)

   The compiler and all Ada packages transitioned from gnat 3.15p in
Sarge to gnat-4.1 in Etch.  This appendix is here for historical
purposes.

C.1 How the Ada compiler for Etch was chosen
============================================

In 2004, even before Sarge was released I had laid out a plan for Etch
and published it in the First Edition of this Policy.  The plan was to
choose a new Ada compiler for Etch and transition all packages to it.
The new Ada compiler would be either the next "p" release from AdaCore,
which was the preferred solution or the latest release of GCC available
roughly 3 months before the freeze of Etch.  These 3 months would be
used to actually perform the transition.

   When AdaCore released GNAT GPL 2005 Edition, my nice plans for Etch
fell apart, because the license change for libgnat meant that some
users would be unhappy about this compiler.  While I have no objection
to this license change, I felt that my duty as a distribution
maintainer was to ask what users wanted and so I did.  I asked for all
interested people to vote on one of GNAT GPL 2005 Edition, gnat-3.4,
gnat-4.0 or gnat-3.4 with patches backported from GNAT GPL, 4.0 and
4.1.  Each voter could give one negative vote to express utter
rejection, two positive votes for a strong preference or one vote for a
normal preference.  Here are the results of the vote:

*Variant*                 *Votes*
GNAT GPL 2005 Edition     -11
gnat-3.4                  7
gnat-4.0                  16
gnat-3.4+patches          0

C.2 Transition plan for Etch
============================

June 2005 - Sarge released.  gcc-4.0 enters testing.  Several major
transitions start simultaneously: g++ from 3.3 to 4.0 (with ABI
change), XFree86 4.3 to X.org 6.8, GNOME from 2.8 to 2.10.  Other
transitions are planned, as well.

   September 2005 - Java, Treelang, libffi and several other binary
packages are no longer built from gcc-3.3 or gcc-3.4 but only from the
gcc-4.0 source package.

   November 2005 - Release branch for GCC 4.1 created.  gcc-4.1 reaches
experimental.

   December 2005 - gnat-3.3 removed from Etch.

   February 2006 - GCC 4.1.0 released.

   March 2006 - gnat-3.4 removed from Etch.  Ground work starts on
gnat-4.1 in experimental:

   * Link the GNAT tools (gnatmake, gnatkr, gnatprep, etc.) dynamically
     against libgnat-4.1.so, instead of statically.  (Done: 2006-03-17)

   * Port the support for symbolic tracebacks from gnat 3.15p

   * Port libgnatvsn and libgnatprj from gnat 3.15p

   * Build ASIS with gnat-4.1.  This will probably be the latest GPL
     version of ASIS, because all the packages that depend on ASIS are
     GPL, and ASIS allows manipulation of programs and so is not just an
     execution library.

   * Build GLADE with gnat-4.1.  This will be the GLADE from AdaCore's
     CVS repository, under GNAT-Modified GPL.

   July 2006 - gnat-4.1 reaches unstable. ghdl transitions to gnat-4.1.

   August 2006 - gnat-4.1 reaches testing and becomes the default Ada
compiler.  All Ada libraries must change their sonames and all packages
require recompilation.

   September 2006 - toolchain freeze

   October 2006 - general freeze

   December 2006 - Etch released 18 months after Sarge.

Appendix D libgnat under GPL - for or against
*********************************************

Here is a summary of the arguments that were expressed by various
people on comp.lang.ada while debating on the Ada compiler for Etch.
The arguments are in no particular order and the summaries are mine.

   The anarchist argument: it is immoral for AdaCore to dictate how
libgnat should be used; everyone should be free to use libgnat however
they see fit and the GPL uses violent but lawful means to make this
impossible.  Therefore, everyone should reject the GNAT GPL 2005
Edition.

   The Free Software argument: it is immoral to write non-free software;
it is even more immoral to use a free software library such as libgnat
in non-free software.  It is appropriate to make this illegal by
releasing libgnat under the GPL.  Therefore, everyone should embrace
GNAT GPL 2005 Edition.

   The Other Free Software argument: we make Free Software under a
license which is incompatible in some ways with the GPL (e.g. the BSD
license).  The GPL prohibits linking libgnat with our software and
distributing our binaries.  Therefore, we reject the GNAT GPL 2005
Edition.

   The selfish argument: we make commercial proprietary software with
GNAT but we cannot or will not pay for GNAT Pro.  If libgnat is under
GPL, we can no longer distribute our proprietary software.  Therefore,
we reject GNAT GPL 2005 Edition.

   The interoperability argument: our software has to link with non-free
software which is outside our control and the license of which
prohibits use of GPLed libraries (variant: we link with other Free
libraries which are under licenses not compatible with the GPL);
therefore we are forced to reject GNAT GPL 2005 Edition.

   The betrayed author's argument: I made contributions to the software
that is now supported commercially by AdaCore, with the understanding
that the license was the GMGPL.  AdaCore revoked the special permission
without consulting me.  While this is specifically allowed by the GPL,
I feel betrayed.  Therefore, I reject the GNAT GPL 2005 Edition.

   The technical quality argument: GNAT GPL 2005 Edition is the best
available Ada compiler.  GCC 3.4 is not as up-to-date with respect to
Ada 2006 and GCC 4.0 is less stable.  Therefore, we should embrace GNAT
GPL 2005 Edition.

   The marketing argument: licensing libgnat under the GPL hinders
promotion of Ada, especially to small businesses (per the selfish
argument).  The move tries to promote Free Software at the expense of
Ada.  Free Software does not need much promotion while Ada does.
Therefore, we should reject GNAT GPL 2005 Edition.