Re: How to nicely distribute a simple Ada library?

[Georg Bauhaus <rm.dash-bauhaus@futureapps.de>]

On 04.12.11 12:19, Natasha Kerensikova wrote:

> So my first question is, since the policies say to include in the
> package all the body and specification files required to compile
> something against the library, but not the others, how can I know which
> files are required and which are not?


If your library depends on Ada only, then only an Ada compiler
is required. I find this a sign of quality.

I'd start from guiding questions:

(0) Is this a source distribution?

(1) Does your library depend on an implementation?

(2) Does your library include test cases?

(3) Does your library need the services of an OS, or OS abstraction?


I'll assume the answer to (0) is yes.

As a general guiding principle, it will greatly help portability
if sources are such that they can be translated separately with

  pragma Restrictions (
   No_Implementation_Attribute,
   No_Implementation_Pragmas,
   No_obsolescent_Features);

Also, whenever there is a new way and an old way of expressing
the *same* algorithm, new syntax for example, it'll help owners of
slightly older compilers if the old way is chosen. Not because
old is necessarily better. Obsolete isn't better. But
being slightly conservative WRT the latest language changes might
be more practically portable: the latest language basically means that
everyone without a current AdaCore support contract might run into
issues without need, since the algorithm is the same,
assuming that circuitry for older language (Ada 95
and some Ada 2005) is in better shape, and more widely
supported. (However, source depending on recent language can
sometimes be made an option through configuration,
such as a subdirectory for Ada 2012 source text files.)

It might also be interesting to (temporarily) enable
pragma Profile (Ravenscar) in order to see any issues
that might arise should the library be used with a Ravenscar program.

Lastly, if you haven't done so, add pragma Pure, or pragma
Preelaborate to packages where possible.


Distribution format:

A default distribution that always works is to package the
library's source files as one source text, or two in case (2, tests) is true.
All Ada compilers are required to be able to process the source text
of an Ada program. TTBOMK, all implementations of
Ada will be able to section the sources if they need to,
i.e. add them to a library of program units.)
A simple source text is a boon to any future
porters as they won't be bothered with extracting the sources proper
from a purportedly convenient packaging system, or create them
with the help of a macro processor. BTDT, terrible experience, close to automess.

With GNAT:
$ gnatchop [-r] [-w] Simple_Ada_Library.ada

This will chop the source text into pieces that the GNAT front end,
or, in fact, other compilers and tools will find convenient. (Chopping could be
made part of Makefile.GNAT, perhaps unpacking into some subdirectory.
Same with sources of test cases, if any.)

An alternative is to store the source files in some archive, such
as a ZIP or pax (tar), possibly sectioned into sources proper and test,
using directories.  Ada compilers should be able to extend their
search paths accordingly.

With ObjectAda (and AdaMagic), assuming the simple Ada library has been
unpacked into a dicrectory named "simple_ada_library", programmers
might simply command

$ adaopts -p simple_ada_library/src
$ adaopts -p simple_ada_library/test


Dependences:

If (1, implementation or 3, OS services) is true, then I imagine
the sources will reflect this:

- pragma Import is present
- compiler specific packages are with-ed.
- compiler specific pragma Linker_Options

The information is easily collected from the sources. System gurus
should be able to tell, from a listing of these, what else is required
besides the sources. I'd list other dependences as I know them. For
example, if tests (2) rely on AUnit (simply version 1, as this is working well
and is also usable with many compilers), I'd simply mention the dependence.


> The policies also ask for a .gpr file used for building programs against
> the library, which seems different from the .gpr file used to build the
> library itself. Should I, as upstream, try to provide both of them, or
> should I leave the former .gpr file to the packager?

In a source based distribution, a .gpr file (a highly experimental
piece of software, frequently changing) is not strictly necessary; yet,
if there is a test program, then a .gpr file for making the test
program is a way to provide an example of how to use the library
in programs translated with GNAT and using GNAT's project support
programs.


> I gather that packaging systems have their own way to perform the
> installation, but how can I provide an installation mechanism that does
> not depend on a distribution?

Ludovic suggested catering to people's expectations and provide a
configure dummy and a Makefile. I second the motion. Invoking
configure or make can have the effect of displaying a file called
README.txt, which only experienced programmers bother to read
without such service. ;)
Provide a simple Makefile for the compiler that you know and that
you have tested. The emphasis is on simple.

I'd not add a premature install target before version 2.0 ;-)
With a source distribution, there is not so much need for one, anyway.


- Georg