autotools FAQ (was: how to turn off shared library notice in output of make install?)

[Ralf Wildenhues]

[ dropping bug-libtool; apologies for the resend ]

Assorted answers and corrections to your the first half of your proto
FAQ:

* Kent Boortz wrote on Thu, Sep 28, 2006 at 06:00:12AM CEST:
> * General questions
> 
>  Q: When do I want to use aufoconf? When automake? When libtool?
>     What combinations? Is there ever an idea to use "libtool"
>     without the other tools? To use "automake" without "libtool"?

If you are asking about whether and when the three packages should be
used at all or not, these sections in the Autoconf manual provide help:
http://www.gnu.org/software/autoconf/manual/html_node/Introduction.html
http://www.gnu.org/software/autoconf/manual/html_node/The-GNU-Build-System.html

If you are asking about at what time exactly to run the programs named
`autoconf', `automake', and `libtool', then the answer is a completely
different one.  (Not expanding on this because I don't think this was
the question.)

>  Q: The "auto" in the name of "automake" and "autoconf", does this
>     mean I can create the build environment on one platform and the
>     build will work on all Unix/Linux platforms?
> 
>  A: Unfortunately not.

Well, at least that is one goal: to help you to create such a build
environment so that it works everywhere.

>     Libtool is kind of a script with collectively built in knowledge
>     built up over time, so yes it will in most cases solve the problem
>     how to link and create executables and libraries on all platforms.
>     It "knows things", as it has its own (a bit unstructured) database
>     over what to do. But for a new platform it might be lost.

For a new unix-like platform unknown to Libtool, it should still be able
to create static libraries.  Please report a bug if you find one where
that is not the case.

>     Autoconf threoretically will find out what is right by doing
>     "tests" instead of relying on any built in knowledge. Tests to try
>     find out things about your compiler, linker and operating system.
>     And there is a library of macros you can use to customize what
>     tests you want it to perform.
> 
>     Still, in most cases this is not enough. You will find yourself
>     writing new tests for things not covered, and for each new
>     platform you start building on, find yourself doing tweaks. If you
>     google around you will find most configure.in scripts to be quite
>     messy and many of them buggy. So this is not "easy" and definitely
>     not "automatic".

For many problems, there are rather complete tests out there.  Be
encouraged to take a look at gnulib and the Autoconf Macro archive:
http://www.gnu.org/software/gnulib/
http://autoconf-archive.cryp.to/

>      Automake is more like a toolbox where someone
>     else has written many tests saving you time.

Not really.  Automake is there to help you create portable makefiles.
The aclocal program (that is unfortunately part of the Automake package)
can help to manage third-party macro test files, but the program itself
does not provide many tests; it's third-party packages that provide
them.

>     Automake will from a "simplified make file", "Makefile.am", that
>     try to look like a specification, create portable make files
>     "Makefile.in". When the user unpack he runs the "configure" script
>     it will fill in the last parts to create the actual "Makefile".

This sounds ok.

>     Automake works well in most cases. But it is easy to write
>     unmaintainable "Makefile.am" files as well.

A sentence such as this one makes me choke.  Are you trying to scare the
reader?  Or are you putting down on the users, stating that they write
bad Makefile.am files?  I know and agree that some things are not easily
solved in Makefile.am files, but still, an unqualified warning does not
seem very helpful.

>  Q: If I run into problems and need to call for help, what is the rule
>     of thumb for what is to send to <address@hidden,
>     <address@hidden> and <address@hidden>?
> 
>  A: See the diagram at the page ....., but in general....
> 
>     (I'm sure the maintainers doesn't agree, but for me they are
>     really one package and I would be happy if they were distributed
>     as one package ;-) )

Here's a stab at a diagram, though not in diagram form, to be applied in
order.  In the following, TOOL can mean any of autoconf, automake, or
libtool.

If an error message tells you to write to address@hidden, then write
there.

If you are currently building or testing one of these tools, and
encounter an error during this work, then write to its bug address,
address@hidden

If you have found a bug in one of the tools, and even know how to fix
it, send a patch to address@hidden  (In this case you will know
which TOOL is the right one.  ;-)

If you have some problem in some package that uses the autotools, and
are not sure which of them to write to, here are some less clear hints:

If your issue revolves around the creation and usage of shared
libraries, then most likely, address@hidden is the best place.

If you have issues with building in general, like dependencies, the
addition of custom commands, matters revolving around package source
layout and similar, and all kinds of other issues happening in
Makefile.am files, address@hidden is appropriate.

If your package configures and builds fine on some system, but fails to
build on other systems, or with different compilers, shells, any kind of
difference in environment, then:
- try to find out whether there is already a test executed by the
  configure script that helps with this difference.  If there is, then
- try to find out where this feature test comes from; it could be from
  any of the autotools, or external packages, or your package (in
  configure.ac, for example).  There is no simple recipe to answer this
  question; the config.log part that deals with the test in question
  can certainly help, as well as the respective part of the configure
  script.  For new users, the latter may well be too daunting, though.
  So in case of doubt pick the package that seems most appropriate to
  you.

Unfortunately, often it is not immediately clear what the difference
really is.  I guess in this case writing to address@hidden happens
more often that not.


In case of doubt, choose one of the lists, and write to it.  Most
likely, you will be told if it's the wrong list; but also most likely,
you will be helped as well, and nobody is really bothered by people
using the wrong list.  If possible, avoiding to write to several lists
at once is more important (and if you have to, be sure to cross-post
rather than send multiple copies).

Latency on any of these lists may be high.

(Personally, more difficult questions will take longer to answer, but
that's not a good rule, as the person asking often cannot easily guess
whether a given question is difficult.)


> * Cookbook (should be more structured of course)
> 
>  Q: How do I make sure "make dist" copies the source I want
>     to be included?
> 
>  A: All files listed in the varaibles below will be included
> 
>       <prog>_SOURCES

This is answered in the Automake manual:
  info Automake Dist
or
  http://sources.redhat.com/automake/automake.html#Dist

>  Q: How do I include "almost" all in a directory without listing all files?

This question is also answered exactly there.

>  Q: What will automatically be cleaned with "make distclean", "make
>     clean"...., and how do I add more things to clean away?

http://sources.redhat.com/automake/automake.html#Clean

>  Q: What are the different "install" locations and do they differ
>     between different flavors of Unix, like Linux and Solaris?

Partly answered in the manual of Automake-1.9b; it contains a new
introductory chapter that was posted here:
http://lists.gnu.org/archive/html/automake/2006-08/msg00051.html
http://lists.gnu.org/archive/html/automake-patches/2006-08/msg00026.html

>  Q: How do I specify what to install?

http://sources.redhat.com/automake/automake.html#Install

>  Q: What are the rules of thumb what to install where?

Again a question dealt with in the new introduction of the Automake
manual, see above, but also mentioned in the Autoconf manual:
http://www.gnu.org/software/autoconf/manual/html_node/Installation-Directory-Variables.html

>  Q: Does the install locations follow the Linux LSB specification?

I think it can be made to follow by suitable configure arguments.
(I don't know the exact specification, but using --prefix, --sysconfdir,
and maybe a couple more should be sufficient).

>  Q: Can I change the defaults for these standard locations?

The answer upon this question depends on who `I' is.
The user: at configure time, by specifying arguments.
The user: at configure time, by the config.site mechanism:
http://www.gnu.org/software/autoconf/manual/html_node/Site-Defaults.html
(so that the same set of changes can be applied to lots of packages
easily).

The package author: hmm, possible in principle, yes, but most often not
advisable.  At least not as an absolute override: users may not have
root permissions but still want to use your software.

>  Q: Will it break if I'm over-specifying things to copy or build?

I don't understand this question.  You may want to keep one principle in
mind with Automake: the contents you put in Makefile.am will not only
cause Automake to generate lots of additional stuff, but _also_ it will
be copied (mostly) verbatim into the resulting Makefile.  And for most
targets that you write a rule for, Automake will refrain from adding
one, so that you can override things.

>  Q: I have seen some put header files into <prog>_SOURCES, is that
>     allowed and when do I want to do that? And when don't I?

Yes, that is fine.  You can do that always.  If you want to install some
particular header, you should add it to include_HEADERS (and then you
should omit it from prog_SOURCES).

I can answer more, but probably not before the end of next week.

Cheers,
Ralf