How to nicely distribute a simple Ada library?

How to nicely distribute a simple Ada library?

[Natasha Kerensikova]

Hello,

sorry for spamming you again, and for the arrogance of thinking anyone
might possibly want to use my code, but I'm wondering what is the best
way to distribute a library (once it's ready for release) written in
Ada.

I have found the packaging policies for Debian, which is very complete
and useful, and for Fedora, which seems nice too but less interesting
for upstream. And I would like to eventually maintain a FreeBSD port.

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?

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?

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? I would rather avoid automess tools, they
feel extremely overkill compared to the simplicity and presumed
portability of my libraries. I can write a `make install` in pure
makefile language, but is there another more idiomatic way of doing it?
What about windows or mac platforms?

And while all the above assumes a GNAT toolchain, there are probably
people using other compiles. I guess I cannot really support all Ada
compilers that exist (especially those to which I don't have access), so
the burden for porting the library to their toolchain is probably
theirs, but is there any step I should to make it easier for them?

And lastly, is there anything else I should know to make my libraries
easier to use for packagers and users?


Thanks for your help,
Natasha

Re: How to nicely distribute a simple Ada library?

[Dmitry A. Kazakov]

On Sun, 4 Dec 2011 11:19:49 +0000 (UTC), Natasha Kerensikova wrote:

> I have found the packaging policies for Debian, which is very complete
> and useful, and for Fedora, which seems nice too but less interesting
> for upstream. And I would like to eventually maintain a FreeBSD port.

AFAIK, Ada on Fedora is maintained again. E.g. it has GtkAda 2.18 for gcc
4.6 which Debian still lacks.

> 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?

You should maintain dependencies.

Your library under Linux would have at least two packages: binary and
developing dependant on different sets of packages.

> 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?

I used to generate the .gpr files for building my libraries. I wrote a
script which took the original .gpr file and patched it in order to produce
a build-gpr.

> 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?

There is no one, AFAIK.

Fedora and Debian packaging systems is an utter mess. For my packages I
wrote a set of scripts generating the corresponding inputs for both
packaging systems. They have little in common. Furthermore, since GNAT
distributions on both systems suffer various problems (bugs), to overcome
them you might need workarounds, which then would depend on the target
system. (I stopped packaging my stuff until Linux distributions mature.
Presently I cannot compile much of it either under Fedora or under Debian.)

You should likely try to package your stuff manually first, in order to
understand the scale of the problem you are face. RPM (Fedora) is
considerable easier than Debian packager to start. IMO, packaging is as
twice harder than developing and testing a medium sized Ada library. You
should really consider if the adventure is worth the efforts...

> I would rather avoid automess tools, they
> feel extremely overkill compared to the simplicity and presumed
> portability of my libraries. I can write a `make install` in pure
> makefile language, but is there another more idiomatic way of doing it?

Well, but that is not the standard way how packages are distributed in
Linux.

I wrote a small tool to integrate a library into GNAT GPS without
packaging. But it is rather intended for custom libraries distributed in
sources. If you plan to distribute your library on "industrial scale", you
have to package it properly.

> What about windows or mac platforms?

For Windows you need to create an *.msi file. If you have a MS Developing
Studio, that is relatively simply to do, at least comparing to the
exercises needed for RPM and Debian packages.

> And while all the above assumes a GNAT toolchain, there are probably
> people using other compiles. I guess I cannot really support all Ada
> compilers that exist (especially those to which I don't have access), so
> the burden for porting the library to their toolchain is probably
> theirs, but is there any step I should to make it easier for them?

From a packaged library I would expect a full integration into GNAT GPS.
That means placing files on certain GNAT-specific locations depending on
the GNAT installation at hand.

OK, Linux does not really support GPS, or, for that matter, gprbuild
either. Under Debian there exists a GPS package, but it was not gcc 4.6,
last time I checked it.

> And lastly, is there anything else I should know to make my libraries
> easier to use for packagers and users?

1. Always provide gpr files. Whatever configuration you need should be done
using project variables.

2. Don't use any tools (e.g. make, autoconf, etc). Many nice Ada libraries
became unusable because in 2-3 years the makefile stopped working and
nobody knew how to fix it.

3. Don't use preprocessor! [Since AdaCore introduced it, there are troubles
installing Win32Ada]. If you need to tune the source, take the varying part
of it, make it a proper Ada package. Place two versions of this package
into separate subdirectories. Make a scenario variable to select the file
in the .gpr file.

4. Never set linker options using pragmas! Linker options belong to the
.gpr file.

-- 
Regards,
Dmitry A. Kazakov
http://www.dmitry-kazakov.de

Re: How to nicely distribute a simple Ada library?

[Ludovic Brenta]

Natasha Kerensikova <lithiumcat@gmail.com> writes:
> sorry for spamming you again, and for the arrogance of thinking anyone
> might possibly want to use my code, but I'm wondering what is the best
> way to distribute a library (once it's ready for release) written in
> Ada.
>
> I have found the packaging policies for Debian, which is very complete
> and useful, and for Fedora, which seems nice too but less interesting
> for upstream. And I would like to eventually maintain a FreeBSD port.
>
> 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?

When in doubt, include everything that is written in Ada.

> 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?

It is the packager's responsibility to provide the .gpr file used for
building against the library.  In particular, the location where GNAT
will look for this .gpr file depends on the version of GNAT and on the
distribution.  So, do not bother creating a .gpr file for a particular
distribution unless you are also the packager for that distribution.

However, you might want to provide a .gpr file for people who install
your library from sources (as opposed to from their distribution's
packages).  This .gpr file should not assume anything about where it, or
other .gpr files, are installed but it may make assumptions about where
the library sources, .ali and .so files are installed relative to
itself; see below.

> 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? I would rather avoid automess
> tools, they feel extremely overkill compared to the simplicity and
> presumed portability of my libraries. I can write a `make install` in
> pure makefile language, but is there another more idiomatic way of
> doing it?

People who install from source are used to "./configure; make; sudo make
install", so maybe you should provide an empty, no-op configure script
and a Makefile.  The default destination directory should be /usr/local
and there should be a way to override this default at install time
(e.g. "sudo make install DESTDIR=$HOME/lib").  The "install" target of
your Makefile should respect the Filesystem Hierarchy Standard and place
everything in subdirectories of $(DESTDIR).  Anything beyond that is
overkill IMHO.

> What about windows or mac platforms?

That's why the job of a packager is not the same as the job of the
upstream author :) If you don't have Windows or Mac OS X, leave that job
to other people who do have them and are prepared to contribute.

> And while all the above assumes a GNAT toolchain, there are probably
> people using other compiles. I guess I cannot really support all Ada
> compilers that exist (especially those to which I don't have access),
> so the burden for porting the library to their toolchain is probably
> theirs, but is there any step I should to make it easier for them?

I would say: don't bother.  If you follow the guidelines below, it
should be extremely easy for someone with another Ada compiler to use
your library and perhaps even contribute patches back to you.

> And lastly, is there anything else I should know to make my libraries
> easier to use for packagers and users?

To make life easier to everyone:

- Do not split your sources into many directories.  Ideally a single
  directory, unless there are several configurations to choose from at
  build time.

- Avoid preprocessing steps (especially automess)

- Do not require the use of a Makefile to use the library (requiring one
  to build the library is OK).

- Make the .gpr files as simple as you can; they should be readable by a
  human not familiar with the .gpr syntax.  This makes it easy for
  people with compilers other than GNAT to build and use your library.

HTH

-- 
Ludovic Brenta.
Controlling should globally think out of the box. 

Re: How to nicely distribute a simple Ada library?

[Georg Bauhaus]

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

Re: How to nicely distribute a simple Ada library?

[Jeffrey Carter]

On 12/04/2011 04:19 AM, Natasha Kerensikova wrote:
>
> sorry for spamming you again, and for the arrogance of thinking anyone
> might possibly want to use my code, but I'm wondering what is the best
> way to distribute a library (once it's ready for release) written in
> Ada.

If your library is intended to be portable, then source is really the only 
option. You can't include information about every possible compiler, and should 
assume that those using the compiler know how to compile a source library.

The PragmARCs include a null program that withs all the packages in the library. 
Most compilers have a way to compile everything needed for a program, so that 
serves as a kind of cross-compiler build mechanism.

-- 
Jeff Carter
"Ada has made you lazy and careless. You can write programs in C that
are just as safe by the simple application of super-human diligence."
E. Robert Tisdale
72

--- Posted via news://freenews.netfront.net/ - Complaints to news@netfront.net ---

Re: How to nicely distribute a simple Ada library?

[Tero Koskinen]

On Sun, 4 Dec 2011 11:19:49 +0000 (UTC)
Natasha Kerensikova <lithiumcat@gmail.com> wrote:

> Hello,
> 
> sorry for spamming you again, and for the arrogance of thinking anyone
> might possibly want to use my code, but I'm wondering what is the best
> way to distribute a library (once it's ready for release) written in
> Ada.

Check how other open source Ada projects do it.

Examples:
Ahven
- http://sourceforge.net/projects/ahven/files/latest/download?source=files

Alog
- http://www.codelabs.ch/download/libalog-0.4.tar.bz2

Adacontrol
- https://sourceforge.net/projects/adacontrol/files/adactl-src-1.13r8.tgz

I personally try to ignore all distribution specific policies as much
as possible and just make sure that my test program, which uses my
libraries, works after I have installed ("make install") my library to
the system. [1]

At the moment in Ahven, I provide installer only for Linux/Unix
systems. Windows users are expected to do the installation by hand
(copy src\*.adb src\*.ads etc. c:\installation_directory).

> 
> 
> 
> Thanks for your help,
> Natasha


-- 
Tero Koskinen - http://iki.fi/tero.koskinen/

[1] https://bitbucket.org/tkoskine/ahven/src/0d53c00ea8fe/tools/test_release.sh

Re: How to nicely distribute a simple Ada library?

[Simon Wright]

Natasha Kerensikova <lithiumcat@gmail.com> writes:

> 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? I would rather avoid automess
> tools, they feel extremely overkill compared to the simplicity and
> presumed portability of my libraries. I can write a `make install` in
> pure makefile language, but is there another more idiomatic way of
> doing it?  What about windows or mac platforms?

I don't have access to other compilers than GNAT, but for GNAT (GPL and
FSF) I do try to support Linux and Windows/Cygwin as well as Mac OS X.

I've put a small writeup from the user point of view at [1]. This is a
work in progress.

One thing I personally find helpful is to install alongside the
compiler, because I have more than one installed (at the moment, GCC
4.6.0 and GNAT GPL 2011). The source may be compiler-agnostic, but the
object and ali files certainly aren't. Also, this saves the bother of
specifying the ADA_PROJECT_PATH.

There are at least 2 ways of doing this with GNAT. One is the way that
GNAT GPL and FSF GCC use, which is that the GPR is found in
$prefix/lib/gnat/, source in $prefix/include/$package/ and objects in
$prefix/lib/$package/. The other is the way that Debian uses (see the
Policy).

[1] http://booch95.sourceforge.net/installation.html

Re: How to nicely distribute a simple Ada library?

[Yannick Duchêne (Hibou57)]

Le Sun, 04 Dec 2011 12:19:49 +0100, Natasha Kerensikova  
<lithiumcat@gmail.com> a écrit:
> And while all the above assumes a GNAT toolchain, there are probably
> people using other compilers.
Yes, but there are default compiler for each platform. At least for Ubuntu  
and Debian, the Ada compiler is GNAT and nothing else (simply because the  
default C compiler is GCC and GNAT FSF is part of GCC).

-- 
“Syntactic sugar causes cancer of the semi-colons.” [1]
“Structured Programming supports the law of the excluded muddle.” [1]
[1]: Epigrams on Programming — Alan J. — P. Yale University

Re: How to nicely distribute a simple Ada library?

[Yannick Duchêne (Hibou57)]

Le Sun, 04 Dec 2011 13:06:50 +0100, Dmitry A. Kazakov  
<mailbox@dmitry-kazakov.de> a écrit:

> Fedora and Debian packaging systems is an utter mess.
Ok, so at least Ada is not the only one mess on earth (just teasing)

-- 
“Syntactic sugar causes cancer of the semi-colons.” [1]
“Structured Programming supports the law of the excluded muddle.” [1]
[1]: Epigrams on Programming — Alan J. — P. Yale University

Re: How to nicely distribute a simple Ada library?

[Yannick Duchêne (Hibou57)]

Le Sun, 04 Dec 2011 13:06:50 +0100, Dmitry A. Kazakov  
<mailbox@dmitry-kazakov.de> a écrit:
> 4. Never set linker options using pragmas! Linker options belong to the
> .gpr file.
Not even in a platform dependent body ?


-- 
“Syntactic sugar causes cancer of the semi-colons.” [1]
“Structured Programming supports the law of the excluded muddle.” [1]
[1]: Epigrams on Programming — Alan J. — P. Yale University

Re: How to nicely distribute a simple Ada library?

[Dmitry A. Kazakov]

On Mon, 05 Dec 2011 12:58:36 +0100, Yannick Duch�ne (Hibou57) wrote:

> Le Sun, 04 Dec 2011 13:06:50 +0100, Dmitry A. Kazakov  
> <mailbox@dmitry-kazakov.de> a �crit:
>> 4. Never set linker options using pragmas! Linker options belong to the
>> .gpr file.
> Not even in a platform dependent body ?

Yes

-- 
Regards,
Dmitry A. Kazakov
http://www.dmitry-kazakov.de

Re: How to nicely distribute a simple Ada library?

[Yannick Duchêne (Hibou57)]

Le Mon, 05 Dec 2011 14:31:16 +0100, Dmitry A. Kazakov  
<mailbox@dmitry-kazakov.de> a écrit:
>> Not even in a platform dependent body ?
>
> Yes
Why ?


-- 
“Syntactic sugar causes cancer of the semi-colons.” [1]
“Structured Programming supports the law of the excluded muddle.” [1]
[1]: Epigrams on Programming — Alan J. — P. Yale University

Re: How to nicely distribute a simple Ada library?

[Georg Bauhaus]

On 05.12.11 15:11, Yannick Duchêne (Hibou57) wrote:
> Le Mon, 05 Dec 2011 14:31:16 +0100, Dmitry A. Kazakov
> <mailbox@dmitry-kazakov.de> a écrit:
>>> Not even in a platform dependent body ?
>>
>> Yes
> Why ?

Not even with a single "compiler", because there is no such
thing as a single compiler (or rather, linker).

Another reason is obfuscation. Where do you find the build
settings for this software?  Somewhere in the sources.

Change the build settings, change the sources. This means I
might find myself violating licensing terms.

Change the platform from M bits to N bits, N > M, and
see how everything at least compiles just fine. Then, learn
that there is -lfooM somewhere...

A possible exception could be when a body's algorithms semantically
depend on the linker options.  I can't think of a meaningful
example.

Some software I have seen included -lsomething only because
this was useful on the development platform at some point,
not because the software needed "something".

Perhaps options in sources is a habit imported from some
dialect of Pascal?

Re: How to nicely distribute a simple Ada library?

[Dmitry A. Kazakov]

On Mon, 05 Dec 2011 15:11:54 +0100, Yannick Duch�ne (Hibou57) wrote:

> Le Mon, 05 Dec 2011 14:31:16 +0100, Dmitry A. Kazakov  
> <mailbox@dmitry-kazakov.de> a �crit:
>>> Not even in a platform dependent body ?
>>
>> Yes
> Why ?

Because linker options have global effect on the program.

Actually there might be some exceptions where a linker option might be
appropriate for a source file, e.g. renaming or a weak reference
declaration. But even then I would consider one place (gpr-file) for this.

-- 
Regards,
Dmitry A. Kazakov
http://www.dmitry-kazakov.de

Re: How to nicely distribute a simple Ada library?

[Yannick Duchêne (Hibou57)]

Le Mon, 05 Dec 2011 16:22:19 +0100, Georg Bauhaus  
<rm.dash-bauhaus@futureapps.de> a écrit:
> Another reason is obfuscation. Where do you find the build
> settings for this software?  Somewhere in the sources.
> […]
For readability, on the opposite (see below)

> Some software I have seen included -lsomething only because
> this was useful on the development platform at some point,
> not because the software needed "something".
Reply to both you and Dmitry: I like to use it for system library  
dependencies. When a platform provides a library which is not optional  
because it is part of the standard environment, I like to add a pragma  
Linker_Options in bodies. I see three advantages for this: first this is  
clearly visible from body source (especially if specified at the top of  
the source) and then, this applies localization principle (lack of  
localization does not help understanding), and then again, if this package  
is not used, then the linker option is automatically dropped (avoid  
unneeded dependencies). If multiple package links to the same library,  
there is no troubles anyway.

Do you (either you or Dmitry) see a serious reason to not do this way ?

I did not though about linker options in the large, only about this one:  
specify a library to be linked with the package.

The only one issue I know is linker dependency. The pragma Linker_Options  
arguments syntax is not specified by the standard. I don't know about the  
syntax used with other linkers than GNU LD.

> Perhaps options in sources is a habit imported from some
> dialect of Pascal?
Be sure, no (I've suffered to much with this to repeat the experience)

-- 
“Syntactic sugar causes cancer of the semi-colons.” [1]
“Structured Programming supports the law of the excluded muddle.” [1]
[1]: Epigrams on Programming — Alan J. — P. Yale University

Re: How to nicely distribute a simple Ada library?

[Dmitry A. Kazakov]

On Mon, 05 Dec 2011 16:51:55 +0100, Yannick Duchêne (Hibou57) wrote:

> Le Mon, 05 Dec 2011 16:22:19 +0100, Georg Bauhaus  
> <rm.dash-bauhaus@futureapps.de> a écrit:
>> Another reason is obfuscation. Where do you find the build
>> settings for this software?  Somewhere in the sources.
>> […]
> I see three advantages for this: first this is  
> clearly visible from body source (especially if specified at the top of  
> the source) and then,

Which body? The option is seen in the gnatmake/gprbuild string. If an
inappropriate option appears there, your actions? If a desired option does
not, how do you find the body missing it?

> this applies localization principle (lack of  
> localization does not help understanding), and then again, if this package  
> is not used, then the linker option is automatically dropped (avoid  
> unneeded dependencies).

Normally, linker options do not apply to the bodies, they do to the program
as a whole.

> If multiple package links to the same library,  
> there is no troubles anyway.

That depends on the option. If conflicting options appear, good luck in
resolving the problem.

> The only one issue I know is linker dependency. The pragma Linker_Options  
> arguments syntax is not specified by the standard.

Yes, the compiler has all rights to ignore it. So you would definitely
enjoy gathering linker options spread across all *used* bodies guessing
what was ignored and what was taken...

-- 
Regards,
Dmitry A. Kazakov
http://www.dmitry-kazakov.de

Re: How to nicely distribute a simple Ada library?

[Randy Brukardt]

"Dmitry A. Kazakov" <mailbox@dmitry-kazakov.de> wrote in message 
news:361x89sndsg9$.16ruxrwxud090$.dlg@40tude.net...
...
> 4. Never set linker options using pragmas! Linker options belong to the
> .gpr file.

We made the opposite decision in Claw. We put all of the needed linker 
options into (one) body, tailored for each compiler. (Note that since Claw 
is for Windows only, we really only had one target per compiler.)

One of the main reasons is that pragma Linker_Options works in most Ada 
compilers, while the project facilities are all over the map. (.GPR files 
didn't even exist for GNAT when we created Claw in the late 1990's). 
Moreover, we wanted to supply libraries in pure source form, without any 
"building" artifacts that go out of date the moment a new compiler or OS 
version is released.

Indeed, every Ada compiler has a decent make facility. Needing more than 
that suggests an overcomplicated setup for most libraries. Just create a 
directory, dump the source in it, and point your compiler (using a project, 
maybe) to it. Everything else should be automated by the compiler, and I can 
hardly imagine a decent programmer that couldn't do the first three steps in 
their sleep.

So I would give a different setup:

(1) Depend on as few other libraries (other than the Ada-defined stuff) as 
possible. Most of the trouble comes from depending on other libraries, and 
few things really need to do that. If you have a package of GTK widgets, of 
course you'll need a dependency, but unless those are the primary reason for 
your package, keep them separate. (Someone might want to use your library 
with QT or with Claw, and they shouldn't need GTK in that case.)

(2) Put as much as possible into the source code. Perferably, *everything* 
will be in the source code, so a simple make will do the trick.

(3) I do agree with others in one sense -- never put build information into 
the source code unless it has a direct impact on the library (as in Claw 
needing to force linking of various Win32 object libraries). Indeed, if you 
need build information anywhere, refer back to point 1. :-)

(4) Don't worry about fancy installers unless you are planning a large 
project that many people will (not might) use. The amount of time sucked up 
by creating and testing such things is immense (it probably accounts for 30% 
of my time working on Janus/Ada -- example: the current release is 
unfinished in large part because the uninstaller doesn't work right on 
Windows 7. Grrrr.) You're much better off spending your time on the project, 
not on installers and other cruft. You could spend that 30% of time 
individually helping users and still be better off (because you'll learn 
about the pain points and think about ways to mitigate them).

YMMV. The situation probably is different if you are creating a GNAT-only 
project -- but I'd recommend against that (even if you don't directly 
support non-GNAT-use) -- depending only on Ada allows more people to use 
your work. (And Ada compilers are pretty similar compared to other languages 
with multiple implementations.)

                                             Randy.

Re: How to nicely distribute a simple Ada library?

[J-P. Rosen]

Le 06/12/2011 01:22, Randy Brukardt a �crit :
> (4) Don't worry about fancy installers unless you are planning a large 
> project that many people will (not might) use. The amount of time sucked up 
> by creating and testing such things is immense

Which installer are you using? I use Inno Setup (which is free BTW), and
found it remarkably easy to use and powerful.

-- 
---------------------------------------------------------
           J-P. Rosen (rosen@adalog.fr)
Adalog a d�m�nag� / Adalog has moved:
2 rue du Docteur Lombard, 92441 Issy-les-Moulineaux CEDEX
Tel: +33 1 45 29 21 52, Fax: +33 1 45 29 25 00

Re: How to nicely distribute a simple Ada library?

[Ludovic Brenta]

Dmitry A. Kazakov wrote on comp.lang.ada:
> AFAIK, Ada on Fedora is maintained again. E.g. it has GtkAda 2.18 for gcc
> 4.6 which Debian still lacks.

I still have not found the time properly to review the new packaging
of GtkAda 2.24 by Nicolas Boulenguez but if you are interested, I can
send it to you so you can test and evaluate GtkAda 2.24 with GCC 4.6
on Debian unstable.  If it weren't for my busy schedule, this package
would have been in the distribution two months ago; sorry about that.

--
Ludovic Brenta.

Re: How to nicely distribute a simple Ada library?

[Dmitry A. Kazakov]

On Tue, 6 Dec 2011 00:57:40 -0800 (PST), Ludovic Brenta wrote:

> Dmitry A. Kazakov wrote on comp.lang.ada:
>> AFAIK, Ada on Fedora is maintained again. E.g. it has GtkAda 2.18 for gcc
>> 4.6 which Debian still lacks.
> 
> I still have not found the time properly to review the new packaging
> of GtkAda 2.24 by Nicolas Boulenguez but if you are interested, I can
> send it to you so you can test and evaluate GtkAda 2.24 with GCC 4.6
> on Debian unstable.  If it weren't for my busy schedule, this package
> would have been in the distribution two months ago; sorry about that.

2.24, where it comes from?

Anyway, I have a x86 64 wheezy machine and could try it on that.

-- 
Regards,
Dmitry A. Kazakov
http://www.dmitry-kazakov.de

Re: How to nicely distribute a simple Ada library?

[Ludovic Brenta]

Dmitry A. Kazakov wrote on comp.lang.ada:
> On Tue, 6 Dec 2011 00:57:40 -0800 (PST), Ludovic Brenta wrote:
>> Dmitry A. Kazakov wrote on comp.lang.ada:
>>> AFAIK, Ada on Fedora is maintained again. E.g. it has GtkAda 2.18 for gcc
>>> 4.6 which Debian still lacks.
>
>> I still have not found the time properly to review the new packaging
>> of GtkAda 2.24 by Nicolas Boulenguez but if you are interested, I can
>> send it to you so you can test and evaluate GtkAda 2.24 with GCC 4.6
>> on Debian unstable.  If it weren't for my busy schedule, this package
>> would have been in the distribution two months ago; sorry about that.
>
> 2.24, where it comes from?

From AdaCore's Subversion repository, of course.

> Anyway, I have a x86 64 wheezy machine and could try it on that.

OK, I'll send the package to you by email tonight then, unless Nicolas
beats me to it.

--
Ludovic Brenta.

Re: How to nicely distribute a simple Ada library?

[Randy Brukardt]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain, Size: 2170 bytes --]

"J-P. Rosen" <rosen@adalog.fr> wrote in message 
news:jbkcjv$og8$1@dont-email.me...
> Le 06/12/2011 01:22, Randy Brukardt a �crit :
>> (4) Don't worry about fancy installers unless you are planning a large
>> project that many people will (not might) use. The amount of time sucked 
>> up
>> by creating and testing such things is immense
>
> Which installer are you using? I use Inno Setup (which is free BTW), and
> found it remarkably easy to use and powerful.

It's our in-house design (all Ada code, of course) using Claw for the GUI.

I detest installers that spend many minutes doing navel-gauzing before they 
start, which includes all .MSI-based ones that I've used. So I avoided 
that -- the actual work of installation is trivial and needs nothing that 
isn't present in standard Ada packages.

But our requirements are fairly complex: we have to copy several thousand 
files, call various tools to properly (re)locate the run-time library, 
register patches that make the old, unfixable GUI work, compile Claw if the 
user wants to install that, check for configurations of Microsoft tools (or 
tell them what to do if they're missing), allow the user to select a number 
of options, support the installation of a number of different versions of 
the product depending on what the customer paid for, and test all of that on 
a bunch of versions of Windows. It is an infinite time-sink, just like 
documentation is.

I have the actual creation of the installation packages automated, but that 
doesn't eliminate the testing requirements, or the continual futzing needed 
when the programs change. No commercial or free package is going to be able 
to do anything to eliminate, unless it imposes a very strict set of 
restrictions that I could never live with anyway. (I have a similar problem 
with most of the version control systems I've seen.)

And most libraries are better distributed in a plain old ZIP file anyway --  
anyone who can't figure out how to unzip that and use their compiler's make 
facility shouldn't be programming (in anything!!) anyway. The fancy 
installer is just a time sink.

                                          Randy.

Re: How to nicely distribute a simple Ada library?

[Ludovic Brenta]

Randy Brukardt wrote on comp.lang.ada:
> And most libraries are better distributed in a plain old ZIP file anyway --

I think this is too simplistic.
Zip files cannot manage dependencies between libraries and force the
user to
recompile everything.  This may be fine for a single computer, a small
number
of libraries, and small libraries, but does not scale to tens of
computers
that need the same development environment, or to dozens of libraries,
or to
very large tools and libraries.

> anyone who can't figure out how to unzip that and use their compiler's make
> facility shouldn't be programming (in anything!!) anyway. The fancy
> installer is just a time sink.

Sure, professional programmers should know how to unzip and compile
from
sources.  But you cannot become one until you've learned how to do
that.
By definition, novices don't know how to unzip and compile, and they
don't
know how to read a README file either :/ They need hand holding and a
"standard" (whatever that means for their platform) installer.

--
Ludovic Brenta.

Re: How to nicely distribute a simple Ada library?

[Natasha Kerensikova]

On 2011-12-04, Georg Bauhaus <rm.dash-bauhaus@futureapps.de> wrote:
> 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.

Does it mean I should rather embed a library (especially if it's simple
and from me) than depend on it externally?

I'm thinking about the Natools thing here: it's code that will end up
useful in several projects of mine, so it certainly make sense to fator
it out into project-agnostic Ada packages.

From there I thought in the C/Unix way, and planned to make Natools a
dynamic library. But you seem to think it's the opposite of a quality
approach, have I understood correctly?

I can embed the Natools into the project cleanly (or at least, cleanly
enough for me). I would guess it leads to a negligible amount of extra
disk space used, and the lack of system-wide updates, which is somewhat
uncomfortable (what if I forget about a binary that embeds Natools, and
fail to update it after encountering a security issue or a critical
bug?).

On the other hand, in-place dynamic library update seems even more
fragile in Ada than in C, because it requires .ali compatibility on top
of binary compatibility. So maybe the drop-in compatible replacement is
too rare to be worth considering, isn't it?

Other than that, I'm also writing binding to C libraries, which have the
obvious non-Ada dependency, but that cannot be avoided.

> 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 have no plan of ever answering "no" to (0). And I think if I ever do,
it will be for a company or a distribution, which will provide me with
their "right" way of doing it anyway, so I don't need to care about it
now.

(1) is an interesting question. I guess the answer is "yes" for my
bindings to C libraries, in that GNAT provides interface for GCC C
libraries. On the other hand, the source itself does not depend (as far
as I know) on GNAT itself, only on an Ada compiler that correctly
interfaces with the relevant C compiler.

(2) should be yes most of the time.

(3) depends which project of mine is being considered. I avoid them when
I can (e.g. when I need a filter from unix standard input to standard
output, I use Ada.Text_IO.Current_Input and ..._Output), but sometimes
Ada standard library is not enough (e.g. for TCP sockets).

> 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);

It seems I do use a GNAT-specific pragma, which is pragma Unreferenced.
I find it very useful (with the associated "unreferenced" warning), but
only during active development. I guess once released, and used without
modification, it becomes useless?

Should I remove them from the release branch, for better portability?
(Probably "removed" as in "commented out", so that humans reading the
code understand it's intentional.) Or should I leave that to non-GNAT
users (with a warning in the README), since it's such an easy change?

> 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.

OK, thanks a lot for all your advice (even what I snipped, I still read
and assimilated it).


Natasha

Re: How to nicely distribute a simple Ada library?

[Ludovic Brenta]

Natasha Kerensikova wrote on comp.lang.ada:
> On 2011-12-04, Georg Bauhaus wrote:
>> I'd start from guiding questions:
>
>> (0) Is this a source distribution?
>
> I have no plan of ever answering "no" to (0). And I think if I ever do,
> it will be for a company or a distribution, which will provide me with
> their "right" way of doing it anyway, so I don't need to care about it
> now.

I think the question really was: Is this a source-*only* distribution?
A source-only distribution (e.g. FreeBSD ports, Gentoo emerge)
consists of the sources and Makefiles (or other files) that build the
library automatically at installation time. In contrast, a binary
distribution (e.g. Debian, FreeBSD packages) provides precompiled
binaries and the option to get the sources separately and recompile
them if you need to.

The simplest form of source-only distribution is just a tarball with
the sources in it; it leaves installation, compilation, configuration
and dependency management to the user.  This is probably what you
should do as an upstream developer; packagers for various target
platforms will then create the packages using the best practices and
standards applicable for their target platform.

If you are also the packager (e.g. for FreeBSD as you mentioned) then
you will need to consider issues and make decisions such as:

- do you want to provide binaries (a "package" as opposed to a
  "port")?  In which case you must provide .ali files and care
  about their compatibility; you must also consider package
  dependencies, in particular what happens in the presence of
  multiple versions of GNAT, as this has an impact on the .ali
  files.
- do you want to support multiple version of GNAT?
- do you want to support Ada compilers other than GNAT?
- do you want to provide a shared library?

Note that these decisions are the responsibility of the packager, not
the upstream author.  One packager might decide to provide only the
sources and require users to recompile the library statically into
their executables; another might decide to provide a precompiled
static library along with the source and .ali files; another (e.g. on
Debian) might decide to provide the full shebang: .ali files, .gpr
file, shared library, static library and detached debugging symbols.

--
Ludovic Brenta.

Re: How to nicely distribute a simple Ada library?

[Robert A Duff]

Natasha Kerensikova <lithiumcat@gmail.com> writes:

> It seems I do use a GNAT-specific pragma, which is pragma Unreferenced.
> I find it very useful (with the associated "unreferenced" warning), but
> only during active development. I guess once released, and used without
> modification, it becomes useless?

Note that a compiler that doesn't support pragma Unreferenced will
ignore it (with a warning).  Same for any other unrecognized pragmas.
So if a pragma doesn't do anything important at run time (like
Unreferenced), then it's safe to leave it in.

The warnings ("Never heard of pragma Unreferenced") might be annoying,
but that's unavoidable.  Different compilers give different warnings.
If you're using multiple compilers, pick one whose warnings you like,
and pay attention to them (and use "pragma Warnings(Off)" or whatever
as appropriate).  For other compilers, just ignore the warnings.

- Bob

Re: How to nicely distribute a simple Ada library?

[Georg Bauhaus]

On 08.12.11 15:00, Robert A Duff wrote:

> The warnings ("Never heard of pragma Unreferenced") might be annoying,
> but that's unavoidable.  Different compilers give different warnings.
> If you're using multiple compilers, pick one whose warnings you like,
> and pay attention to them (and use "pragma Warnings(Off)" or whatever
> as appropriate).  For other compilers, just ignore the warnings.

One such warning is

p.adb: Warning: line 10 col 10 LRM:2.8(11), Unrecognized pragma name =>
"unreferenced", Continuing

With programmable IDEs, warnings can be ignored inasmuch as the IDE
allows classifying and filtering messages. One easy way to achieve
this is to ignore messages that have uniquely identifying substrings.


  To_Be_Ignored.Append ("Unrecognized pragma name => ""unreferenced""");

  Pattern := +"";
  for Warning of To_Be_Ignored loop
     Pattern := Pattern or Warning;
  end loop;

Then, something like

$ gnatmake -Pfoo 2>&1 | grep -v "${Pattern}"

Re: How to nicely distribute a simple Ada library?

[Yannick Duchêne (Hibou57)]

Le Sun, 04 Dec 2011 13:06:50 +0100, Dmitry A. Kazakov  
<mailbox@dmitry-kazakov.de> a écrit:
> Fedora and Debian packaging systems is an utter mess.
For easier creation of Debian/Ubuntu package, one may lool at Debreate
http://debreate.sourceforge.net/
I don't know it in deep, but had a look at it some times ago, and seems  
OK. Ludovic may have a wiser opinion than mine about this utilities.

-- 
“Syntactic sugar causes cancer of the semi-colons.” [1]
“Structured Programming supports the law of the excluded muddle.” [1]
[1]: Epigrams on Programming — Alan J. — P. Yale University

Re: How to nicely distribute a simple Ada library?

[Dmitry A. Kazakov]

On Thu, 08 Dec 2011 16:53:16 +0100, Yannick Duch�ne (Hibou57) wrote:

> Le Sun, 04 Dec 2011 13:06:50 +0100, Dmitry A. Kazakov  
> <mailbox@dmitry-kazakov.de> a �crit:
>> Fedora and Debian packaging systems is an utter mess.
> For easier creation of Debian/Ubuntu package, one may lool at Debreate
> http://debreate.sourceforge.net/
> I don't know it in deep, but had a look at it some times ago, and seems  
> OK.

OK for what? Do you believe that this tool will create you binary, source,
developing, debug packages with the corresponding Debian Ada policies, all
dependencies, test, samples, documentation subprojects etc?

If I were 20 years younger and had nothing to do, I would probably extend
the gpr files to support platform-specific deployment targets, letting
*.deb, *.rpm, *.msi files generated from *.gpr.

Just compare gpr and make-files. See why gpr is so useful and makefile is
such an awful mess? This equally applies to debian/control or rpm spec
files. At the project description level, there is not so many things left
to change. The corresponding policy rules actually define almost
everything. If grpbuild or gnatmake knew these rules, it could generate
deployment packages automatically.

-- 
Regards,
Dmitry A. Kazakov
http://www.dmitry-kazakov.de

Re: How to nicely distribute a simple Ada library?

[Randy Brukardt]

"Ludovic Brenta" <ludovic@ludovic-brenta.org> wrote in message 
news:b1d86c67-0f3b-49ae-998c-2e7f904d6bfc@n10g2000vbg.googlegroups.com...
> Randy Brukardt wrote on comp.lang.ada:
>> And most libraries are better distributed in a plain old ZIP file 
>> anyway --
>
> I think this is too simplistic.
> Zip files cannot manage dependencies between libraries...

True enough, but I already said that dependencies between libraries is bad. 
Most libraries shouldn't depend on anything other than what Ada gives you 
out of the box. (Claw, for instance, is designed to be completely 
self-contained.) The only exceptions that I can think of is for GUI and 
database interfaces, which gives you a maximum of two dependencies -- which 
you shouldn't need fancy tools to manage.

>... and force the user to recompile everything.

Any decent Ada compiler (which includes all Ada compilers I'm aware of) has 
a simple mechanism to compile everything needed for your application. 
Nothing more is needed for the vast majority of libraries.

>  This may be fine for a single computer, a small number
> of libraries, and small libraries, but does not scale to tens of computers
> that need the same development environment, or to dozens of libraries,
> or to very large tools and libraries.

I had prefaced my original remarks by saying that you should forget 
installers unless you are intended to distribute to large numbers of people. 
My follow-on message surely included that proviso, even if it was not 
explicit. Most of the readers here are not creating something like Claw or 
GtkAda and do not need the complexity of fancy installers.

And you seem to agree in another message, where you suggest making a tarball 
and letting the "upstream packager" (whatever the heck that is) worry about 
packaging. That's precisely what I'm suggesting to the library author --  
don't worry about "packaging", because it's really only useful in the 
context of widely-used packages. It's better to just make a source-only 
distribution and give some hints on compiling for you favorite compiler. 
(That's certainly true if you want me to be able to use your work, because 
my favorite compiler is nothing like yours.)

>> anyone who can't figure out how to unzip that and use their compiler's 
>> make
>> facility shouldn't be programming (in anything!!) anyway. The fancy
>> installer is just a time sink.
>
> Sure, professional programmers should know how to unzip and compile from
> sources.  But you cannot become one until you've learned how to do that.
> By definition, novices don't know how to unzip and compile, and they don't
> know how to read a README file either :/ They need hand holding and a
> "standard" (whatever that means for their platform) installer.

Sure, they need that for their compiler and possibly a handful of "big" 
libraries (like Claw). There is a reason that I spend a lot of my Janus/Ada 
time working on our installer (and documentation and ease-of-use and 
everything but actual functionality). And it surely applies to the good work 
that you do, as well. (Please don't think that I am saying that you or 
anyone else shouldn't package GNAT or GtkAda or other things like that!)

But that does not apply to the sorts of small hobbyest projects that are 
mostly discussed here -- including the OP of this thread.

                                      Randy.

Re: How to nicely distribute a simple Ada library?

[Ludovic Brenta]

Randy Brukardt wrote on comp.lang.ada:
>>... and force the user to recompile everything.
>
> Any decent Ada compiler (which includes all Ada compilers I'm aware of) has
> a simple mechanism to compile everything needed for your application.
> Nothing more is needed for the vast majority of libraries.

Complexity is one thing, time necessary to recompile is another.  For
example, GtkAda 2.24 took 1 hour and 44 minutes to recompile on ARM a
couple of days ago:

https://buildd.debian.org/status/fetch.php?pkg=libgtkada&arch=armel&ver=2.24.0-2&stamp=1323307454

But we are in agreement; simple libraries need no or only very simple
installers.

> letting the "upstream packager" (whatever the heck that is) worry about
> packaging.

Sorry, Debian parlance but I think it deserves an explanation.  I did
not say "upstream packager" because it makes no sense and here is
why.  The software flows from the original author ("upstream") through
the packager (middle man), then sometimes through derivative
distributions like Knoppix, and finally to the end users
("downstream").  Thus the Debian packager is "downstream" from the
original author and "upstream" from the end user.  Note that bug
reports flow in the opposite direction; that's why a packager
sometimes "forwards a bug report upstream", meaning he reports the bug
to the original author.

--
Ludovic Brenta.
Our gut-feeling is that aligned values quickly empower the Chief
Management Office Officer.