Oh mighty Emacs, please use -*- Outline -*- mode in this humble file.

Packaging a new upstream release of PolyORB for Debian
------------------------------------------------------

* Choosing which version to package

The implementation of the Distributed Systems Annex in PolyORB
(package System.Partition_Interface in file s-parint.ad[bs]) is
tightly coupled with the package of the same name in the GNAT run-time
library.

When building a monolithic application, GNAT uses its own version of
System.Partition_Interface which is part of libgnat.  When building a
distributed application under the control of gnatdist, GNAT uses the
version from PolyORB instead. For this reason, both versions must have
compatible interfaces at the source level.

The first versions of System.Partition_Interface did not have any
version number.  Later, a constant was introduced: PCS_Version.  Later
still, the PCS_Version became a function of the implementation of the
distributed systems annex; i.e. it has one value for GARLIC/GLADE and
another value for PolyORB.  For Ada Distributed Systems to work, this
constant must be the same in gnat (file exp_dist.ads) and in PolyORB.

The following denotes the PolyORB value of PCS_Version.

** PCS_Version = 1
- introduced in PolyORB on 2007-07-11.
- released in PolyORB 2.3
- introduced in GCC on 2007-08-14.
- released in GCC 4.3.0 on 2008-03-05.

** PCS_Version = 2
- introduced in PolyORB on 2008-04-30.
- released in PolyORB 2.4 included in GNAT GPL 2008 Edition.
- introduced in GCC on 2008-05-26.
- released in GCC 4.4.0 on 2009-04-21.

** PCS_Version = 3
- fixes a release-critical bug related to passing Strings across
  partitions.
- introduced in PolyORB on 2009-02-12.
- to be released in PolyORB 2.6
- introduced in GCC on 2009-05-06.
- to be released in GCC 4.5.0.

(The staged development process of GCC with timeline is at
http://gcc.gnu.org/develop.html)

I (Ludovic) have backported PCS_Version=3 into gnat-4.4 for Squeeze;
this should make it possible to support the Distributed Systems Annex
with a recent (>=2.6) version of PolyORB.

* Licencing terms for the sources

As explained in debian/copyright, the license of PolyORB is the pure
GPL no matter what the sources say.  If you check out from AdaCore's
Subversion repository, you will see that the sources contain the
"special exception" (GNAT-Modified GPL) text.  This does NOT change
the license.  The license is the pure GPL.  In order to reduce
confusion for Debian users, it is necessary to remove the exception
text from all sources of PolyORB before packaging a new .orig.tar.gz.
Here is a shell script that achieves that:

** Shell script

#!/bin/bash
# remove-gmgpl-exception - remove the GMGPL exception from all Ada source files
# Copyright (c) 2006 Ludovic Brenta

# This script is free software; you can redistribute it and/or modify
# it under terms of the GNU General Public License as published by the
# Free Software Foundation; either version 2, or (at your option) any
# later version.  GtkAda 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.

# On Debian GNU/Linux systems, the complete text of the GNU General
# Public License can be found in `/usr/share/common-licenses/GPL'.

# Starting with GtkAda 2.8, the license changed from GNAT-Modified to
# pure GPL.  However, upstream has not yet removed the exception text
# from all source files, creating potential for confusion.  This
# script removes the exception text; I used it before creating the
# .orig.tar.gz file.  GtkAda also contains some C source files, but I
# have not yet removed the exception text from them because they're
# not installed in the -dev binary packages.

ex1="As +a +special +exception\, +if +other +files +instantiate +generics +from"
ex6="covered +by +the +GNU +Public +License\."

cat > program <<EOF
BEGIN { p = 1 }
/${ex1}/ { p = 0 }
/${ex6}/ { p = 2 }
 { if (p == 0) { };
   if (p == 1) print;
   if (p == 2) p = 1; }
EOF

sources=$(find . -type f)

if [ "x$sources" != "x" ] ; then
    for source in $sources; do
	tmp=${source}.tmp
	echo ${source}
	awk -f program < ${source} > ${source}.tmp
	touch --reference=${source} ${source}.tmp
	mv -f ${source}.tmp ${source}
    done
fi

rm program

* Licensing terms for the documentation

Like everything else on the AdaCore public web site, the documentation
is under GPL, despite the fact that the PolyORB user's guide
(docs/polyorb_ug.texi) says it uses the GNU Free Documentation License
with invariant sections.

This has a number of consequences:

1) The Debian maintainer must change the licensing terms in
docs/polyorb_ug.texi to the GPL.

2) The documentation belongs to the main section in Debian (this is
good news because the invariant sections in the GFDL would prevent
that and relegate the documentation to non-free and to a separate
source package).

3) The Debian maintainer needs not (indeed may not) include
docs/gfdl.texi in the .orig.tar.gz.
