5.2 Installation FAQs

I have an executable which creates some files during the build -- how do I prevent it from being installed?

Use the noinst prefix when you declare the program. See Section 2.1.2.

How do I install things in /local-star/{docs,etc,examples,help}?

In the Makefile.am use the DATA prefixes stardocs, staretc, and so on. See Section 2.1.2 for an example.

Note that by /local-star, here, we refer to the directory indicated by STARCONF_DEFAULT_STARLINK -- if you are interested in changing this when making distribution tarballs, see the next question.

I want to make distribution tarballs (for example) install into /star. How?

This is a general question about forcing the $prefix for a directory. See the description of ./bootstrap in Section 4.3.1, which uses a general mechanism described in Section 2.2.1.

Automake flattens paths when it installs things. Why?

This is a feature, which you can turn off if necessary. A Makefile.am line like include_HEADERS = a.h subdir/b.h will cause both a.h and b.h to be installed in the same place, as indicated by the _HEADERS primary. It means that if you had some good reason for creating or distributing the header b.h in its subdirectory, you don't have to copy it into the top directory just prior to installation. If you specify nobase_include_HEADERS, on the other hand, this will cause the hierarchy to be preserved. This is documented rather in passing in the automake manual, in the section An Alternative Approach to Subdirectories (and no, I don't know why `nobase' is supposed to be intuitive, either).

There's an example of using this in Section 4.5.2.

I want to install symbolic links at install time. How?

That counts as `weird' for the purposes of this discussion. See the next item.

I want to do weird things at install time. How?

Automake provides a couple of escape hatches for installing extra material. These are the install-exec-local and install-data-local targets for installing platform-dependent and -independent files. The associated rules are run at install time, and can do anything, the similar install-exec-hook and install-data-hook targets are run after all other install targets, and can do post-installation cleanup and the like. See section What Gets Installed in the automake manual for details.

For example, the dtask component installs a special object file in the library directory. This isn't a program, or script, or library, and so isn't naturally handled by any other automake mechanism. The Makefile.am there includes the following:

dtask_main.o: dtask_main.f
install-exec-local: dtask_main.o
        $(mkdir_p) $(DESTDIR)$(libdir)
	$(INSTALL_PROGRAM) dtask_main.o $(DESTDIR)$(libdir)
        $(MANIFEST) && echo "MANIFEST:$(DESTDIR)$(libdir)/dtask_main.o" || :

This first creates the library directory if necessary. The rules then use the $(INSTALL_PROGRAM) command to install the object file in the library directory (you'd use $(INSTALL_DATA) command for a data target). The installation location is $(libdir), which is a location which includes the $(prefix) variable, so that this install rule behaves as other such rules do. Also, it prefixes the installation location with $(DESTDIR): this is usually the empty string, but it can be set to something else to perform a staged installation. Finally, if the $(MANIFEST) variable evaluates to true, then we echo the echo the name of installed file to stdout prefixed by the string MANIFEST:; note that the command ends with `|| :', which ensures that this composite command succeeds even if $(MANIFEST) evaluates to false. This is a Starlink extension, and is how the manifest file is built up.

Yes, this is a fuss, but it's the consequence of using the install-xxx-local back door. Each of these features is important if this hand-made install rule is to behave the same way as the automatically-generated rules. This technique is also inherently precarious, since if there were ever some reason to modify the installation conventions (for example to modify the way the manifests were built up), then each such back-door would have to be adjusted by hand. That is, don't use this mechanism unless you really have to.

In particular, you often need to create links in this situation. To do that portably (symbolic links are not required by POSIX, and so the autoconf macros are able to emulate them if necessary), put the AC_PROG_LN_S macro in your configure.ac, and use the $(LN_S) macro in your Makefile.am. Note that the autoconf manual notes that this macro does not in principle support a path in the second argument; thus do not write $(LN_S) /target/TARGET /link/LINK, but instead

cd $(DESTDIR)/link; rm -f LINK; $(LN_S) $(DESTDIR)/target/TARGET LINK

The option rm -f is portable. Note that we have included the important $(DESTDIR) variable here, and that the /link and /target locations here should probably be one or other of the $(???dir) variables instead.