includes, configure, /usr/lib vs. /usr/local/lib, and linux coders

[Giorgos Keramidas]

On Fri, 31 Oct 2008 12:30:46 -0700, "Steve Franks" <stevefranks at ieee.org> wrote:
> Let's backup.  What's the 'right' way to get a bloody linux program
> that expects all it's headers in /usr/include to compile on freebsd
> where all the headers are in /usr/local/include?  That's all I'm
> really asking.  Specifically, it's looking for libusb & libftdi.  If I
> just type gmake, it can't find it, but if I manually edit the
> Makefiles to add -I/usr/local/include, it can.  Obviously, manually
> editing the makefiles is *not* the right way to fix it (plus it's
> driving me crazy).

Then you run `configure' with the `right' environment:

    env CPPFLAGS='-I/usr/local/include' \
      LDFLAGS='-L/usr/local/lib' ./configure

The `--includedir' and `--libdir' options are *not* meant to be useful
to the developer that uses the GNU build tools, but to the person who
compiles something for the target host.

There are several types of people involved in the `release' of a full
program:

    * The maintainer, who uses `automake', `libtool' and `autoconf' to
      write portable Makefiles and build tools.

    * The builder, who compiles the program with specific options.

    * The packager, who runs `make install' in the build tree, creates a
      set of installed files, and then packages *some* of these files in
      a packaging-specific format.

These types of people commonly have different constraints in the way
they can tweak and twist the GNU build tools, to match their needs.

1. The _maintainer_ of the program is free to set up his environment to
   include any `CPPFLAGS', `CFLAGS' or `LDFLAGS' they find useful.  For
   example, if they have an experimental third-party library installed
   in a custom location they can use:

     export CPPFLAGS='-I/opt/foolib/include' LDFLAGS='-L/opt/foolib/lib'
     ./configure --prefix='/var/tmp/myprog'

   This way `configure' will emit Makefiles that try to use the
   third-party library from `/opt/foolib' instead of the system-default
   location for header files and libraries.

   This may often be a lot easier than waiting until the necessary bits
   are installed in the ``official'' places at development systems.
   Developers who want to experiment with a new version of `libfoo',
   i.e. to integrate it with the rest of a program, can use custom
   `CPPFLAGS' and `LDFLAGS' while everyone else is merrily going along
   with the ``standard'' version of the `libfoo' library.

2. The _builder_ may be constrained in the sets of options he can pass
   to the `CFLAGS'.  He is, after all, testing how a pristine, clean
   version of the program can build in what is defined as the ``official
   release'' environment.

   He may be allowed to tinker with include paths and library paths, but
   it is often safer to wrap the build process in scripts and tools that
   yield a repeatable, verifiable build process.  This may preclude the
   use of options like `-I/custom/hdr/path' and `-L/custom/lib/path'.

   The builder of a program may not be an actual person, but a cron job
   or another automated process, i.e. a `nightly build' script that runs
   a clean build in a pristine environment, verifies that it can all
   complete without errors, and then emails one or more reports.

   When the builder _is_ a real person, he may be sharing roles with the
   third type of person involved in the build life of a program that
   uses the GNU build tools: the packaging person.

3. The _packager_ is someone who runs `make install', to produce the
   final program distribution and then bundles parts of or even all the
   files that are produced by the usual `install' target of GNU tools.
   The installation of all the files may be done in the default
   installation `prefix', but it may also be redirected to a staging
   area by setting `DESTDIR' in the environment:

     mkdir /var/tmp/proto
     env DESTDIR=/var/tmp/proto make install

   Depending on the type of the target system, and on particular needs
   of the packaging person, there may be cases where certain files have
   to be installed in a `non-standard' location, or in a location that
   was not foreseen by the original maintainer.  In that case, the
   packager can use the `--libdir' and `--includedir' options to change
   the final, installed location of the relevant bits.

   A typical example is the case of Solaris systems, where libraries may
   be installed in `/usr/lib/64' for 64-bit architectures.  When a
   packager prepares installation images for these architectures, he can
   build the program with:

     ./configure --prefix='/opt/foo' --libdir='$prefix/lib/64'

All this is a pretty long-winded way of saying:

   The `--includedir' and `--libdir' options are not really something
   that is meant to be a convenience option for the _maintainer_ of a
   program,, the person who writes the code.  They are meant to be
   useful tools for the _packager_ of the program, the person who
   builds and prepares the final, install-able images.

   If you are the maintainer, who writes the code of a program, and you
   find yourself in a position where you need to use the `--libdir' and
   the `--includedir' options, then YOU ARE DOING IT WRONG.

and, as you have probably guessed by now:

   The Linux people of the original post are wrong.

The GNU build tools are a relatively good set of tools to automate a lot
of the mundane details of setting up a build system.  It is unfortunate
that many people who use them have absolutely no clue of what they are
using, and they think that slapping a bunch of copy-paste snippets from
Google searches in a `configure.in' script will magically turn any odd
mess into a clean release process.  Alas, Linux newbies are very often
exactly _this_ sort of person :/