Automake install data files

We realize this annoys some people, because aclocal was not so strict in the past and many third party macros are underquoted; and we have to apologize for this temporary inconvenience.

The reason we have to be stricter is that a future implementation of aclocal see The Future of aclocal will have to temporarily include all of these third party. Doing so should alleviate many problems of the current implementation; however, it requires a stricter style from macro authors.

Hopefully it is easy to revise the existing macros. For instance,. For consistency we like to quote even arguments such as 2. If you have been directed here by the aclocal diagnostic but are not the maintainer of the implicated macro, you will want to contact the maintainer of that macro. Another situation where aclocal is commonly used is to manage macros that are used locally by the package; Handling Local Macros. Feature tests offered by Autoconf do not cover all needs.

People often have to supplement existing tests with their own macros, or with third-party macros. The first possibility the historical practice is to list all your macros in acinclude. This file will be included in aclocal. However if it contains numerous macros, it will rapidly become difficult to maintain, and it will be almost impossible to share macros between packages.

The second possibility, which we do recommend, is to write each macro in its own file and gather all these files in a directory. Macros not found locally will still be searched in system-wide directories, as explained in Macro Search Path. Custom macros should be distributed for the same reason that configure. However there is no consensus on the distribution of third-party macros that your package may use.

Many libraries install their own macro in the system-wide aclocal directory see Writing your own aclocal macros. For instance, Guile ships with a file called guile. Technically, that means a user who needs to rebuild aclocal. This is probably OK, if Guile already is a requirement to build the package.

However, if Guile is only an optional feature, or if your package might run on architectures where Guile cannot be installed, this requirement will hinder development. Since Automake 1. Then the locally installed macros will have precedence over the system-wide installed macros each time aclocal is run again.

One reason why you should keep --install in the flags even after the first run is that when you later edit configure. Another one is that serial numbers see Serial Numbers can be used to update the macros in your source tree automatically when new system-wide versions are installed. A serial number should be a single line of the form. It should appear in the M4 file before any macro definition.

It is a good practice to maintain a serial number for each macro you distribute, even if you do not use the --install option of aclocal : this allows other people to use it. This makes it easier to tell which of two M4 files is newer. Such a line should appear in the M4 file before any macro definition. Normally these serial numbers are completely ignored by aclocal and autoconf , like any genuine comment.

Note that a serial number applies to a whole M4 file, not to any macro it contains. A file can contain multiple macros, but only one serial. Here is a use case that illustrates the use of --install and its interaction with serial numbers. The first time we run aclocal --install , it will notice that. Because both files have the same serial number, aclocal uses the first it found in its search path order see Macro Search Path. Local directories specified with -I are always searched before system-wide directories, so a local file will always be preferred to the system-wide file in case of equal serial numbers.

Now suppose the system-wide third-party macro is changed. This can happen if the package installing this macro is updated. When aclocal sees a greater serial number, it immediately forgets anything it knows from files that have the same basename and a smaller serial number.

This brings us back to a situation similar to that at the beginning of our example, where no local file defined the macro. MyPackage just had its macro updated as a side effect of running aclocal.

Finally, note that the --force option of aclocal has absolutely no effect on the files installed by --install. For instance, if you have modified your local macros, do not expect --install --force to replace the local macros by their system-wide versions.

Previous: Serial Numbers , Up: Auto-generating aclocal. Ideally, aclocal should not be part of Automake. The fact that some people install Automake just to use aclocal , but do not use automake otherwise is an indication of how that feature is misplaced.

The new implementation will probably be done slightly differently. We have no idea when and how this will happen. This has been discussed several times in the past, but someone still has to commit to that non-trivial task. There is a simple precaution that you may take to make that switch more seamless: never call aclocal yourself.

If otherwise you used to call aclocal directly yourself or from some script, you will quickly notice the change. Many packages come with a script called bootstrap or autogen. In fact, this is precisely what autoreconf can do for you. If your package has such a bootstrap or autogen. Previous: Auto-generating aclocal. Automake ships with several Autoconf macros that you can use from your configure.

When you use one of them it will be included by aclocal in aclocal. In this form, there are two required arguments: the package and the version number. Autoconf tries to derive a tarball name from the package name, which should work for most but not all package names.

This can be avoided by passing the no-define option see List of Automake options :. Other emacsen can cause this test to hang some, like old versions of MicroEmacs, start up in interactive mode, requiring C-x C-c to exit, which is hardly obvious for a non-emacs user. In most cases, however, you should be able to use C-c to kill the test. You must use this macro when you use the archiver in your project, if you want support for unusual archivers such as Microsoft lib.

The content of the optional argument is executed if the archiver interface is not recognized; the default action is to abort configure with an error message. Use this macro when you have assembly code in your project. This is an obsolescent macro that checks that the C compiler supports the -c and -o options together. Note that, since Automake 1. HP-UX 10 is one such system. This macro finds the gcj program or causes an error. This macro will abort configure if no Unified Parallel C compiler is found.

Find a maintainer tool program and define the name environment variable with its location. If program is not detected, then name will instead invoke the missing script, in order to give useful advice to the user about the missing maintainer tool.

Control the machinery for less verbose build output see How Automake can help in silencing Make. Add support for the Dmalloc package. Although using some of the following macros was required in past releases, you should not use any of them in new code. All these macros will be removed in the next major Automake version ; if you are still using them, running autoupdate should adjust your configure. Do it NOW!

From Automake 1. The following macros are private macros you should not call directly. They are called by the other public macros when appropriate. Do not rely on them, as they might be changed in a future version. Consider them as implementation details; or better, do not consider them at all: skip this section! They are called automatically by Automake when required, and there should be no need to invoke them manually.

This macro is automatically invoked when needed; there should be no need to invoke it manually. This is used to find a version of install that can be used to strip a program at installation time. This macro is automatically included when required. This checks to make sure that a file created in the build directory is newer than a file in the source directory. This can fail on systems where the clock is set incorrectly. For simple projects that distribute all files in the same directory it is enough to have a single Makefile.

In larger projects, it is common to organize files in different directories, in a tree. Because this approach is very widespread, Automake offers built-in support for it. In packages using make recursion, the top level Makefile. The rules for many targets e. This allows inclusion of libraries from packages that do not use Automake such as gettext ; see also Third-Party Makefile s.

In packages that use subdirectories, the top-level Makefile. For instance, here is the Makefile. Automake can be used to construct packages of arbitrary depth this way. By default, Automake generates Makefiles that work depth-first in postfix order: the subdirectories are built before the current directory. However, it is possible to change this ordering. It is customary to arrange test directories to be built after everything else since they are meant to test what has been constructed.

In addition to the built-in recursive targets defined by Automake all , check , etc. Automake generates rules to handle the recursion for such targets; and the developer can define real actions for them by defining corresponding -local targets.

There are two ways to set up a project like this. Using Automake conditionals is the preferred solution. It must be defined manually; Automake will never guess a directory is to be built. As we will see in the next two sections, it is possible to define it conditionally so that some directory will be omitted from the build. Here by configuring we mean creating the Makefile it might also involve running a nested configure script: this is a costly operation that explains why people want to do it conditionally, but only the Makefile is relevant to the discussion.

The above examples all assume that every Makefile is created, even in directories that are not going to be built. Building packages that do not configure every subdirectory is a tricky business, and we do not recommend it to the novice as it is easy to produce an incomplete tarball by mistake. We will not discuss this topic in depth here, yet for the adventurous here are a few rules to remember.

Think of the former as a way to tell which directories listed in the latter should be built. That is, the Makefile must exist or the recursive make rules will not be able to process the directory.

This is so the cleaning rules remove the generated Makefile s. In a few packages, unconfigured directories are not even expected to be distributed. Although these packages do not require the aforementioned extra arrangements, there is another pitfall. Consequently automake cannot be run on such a distribution when one directory has been omitted.

Automake is intended to have sufficient cross-directory support to enable you to write a single Makefile. If it seems to be lacking, please report the issue as usual. By default an installable file specified in a subdirectory will have its directory name stripped before installation. For instance, the last example could be rewritten as follows:. This latter syntax makes it possible to change one destination directory without changing the layout of the source tree. This means that a package can embed other packages with their own configure , Makefile s, etc.

These other packages should just appear as subdirectories of their parent package. So although it appears to be embedded in another package, it can still be used separately. The historical default is to search for these auxiliary scripts in the parent directory and the grandparent directory.

Packages that do not use Automake need more work to be integrated this way. See Third-Party Makefile s. In order to build a program, you need to tell Automake which sources are part of it, and which libraries it should be linked with. This section also covers conditional compilation of sources or programs. Most of the comments about these also apply to libraries see Building a library and libtool libraries see Building a Shared Library. In this simple case, the resulting Makefile.

Associated with each program are several assisting variables that are named after the program. These variables are all optional, and have reasonable defaults. This causes each mentioned. Then all are linked to produce hello. Multiple programs can be built in a single directory. Sometimes, multiple programs are built in one directory but do not share the same link-time requirements.

For instance, in GNU cpio, pax , cpio and mt are linked against the library libcpio. However, rmt is built in the same directory, and has no such link requirement. Also, mt and rmt are only built on certain architectures. It is also occasionally useful to have a program depend on some other target that is not in fact part of that program.

Each program depends on the contents both variables, but no further interpretation is done. Since these dependencies are associated to the link rule used to create the programs they should normally list files used by the link command.

Instead, write the file name of the library explicitly as in the above cpio example. Use -l only to list third-party libraries. Automake will give an error if you try to do this.

Fortunately there are two other ways to achieve the same result. Automake must know all the source files that could possibly go into a program, even if not all the files are built in every circumstance. For instance, if hello-linux. An often simpler way to compile source files conditionally is to use Automake conditionals. For instance, you could use this Makefile.

In this case, configure. Sometimes it is useful to determine the programs that are to be built at configure time. For instance, GNU cpio only builds mt and rmt under special circumstances. The means to achieve conditional compilation of programs are the same you can use to compile source files conditionally: substitutions or conditionals.

In this case, you must notify Automake of all the programs that can possibly be built, but at the same time cause the generated Makefile. You can also use Automake conditionals see Conditionals to select programs to be built. Building a library is much like building a program. Libraries can be installed in libdir or pkglibdir.

For instance, to create a library named libcpio. This should be used for objects determined by configure. Again from cpio :. Be careful when selecting library components conditionally. Because building an empty library is not portable, you should ensure that any library always contains at least one object.

In the following example, the program cpio is statically linked with the library libcpio. Building shared libraries portably is a relatively complex matter. Libtool abstracts shared and static libraries into a unified concept henceforth called libtool libraries. Libtool libraries are files using the. Their exact nature cannot be determined until. Because object files for shared and static libraries must be compiled differently, libtool is also used during compilation.

Object files built by libtool are called libtool objects : these are files using the. Libtool libraries are built from these libtool objects. You should not assume anything about the structure of. There are situations where you may have to refer to these, for instance when expressing dependencies for building source files conditionally see Libtool Libraries with Conditional Sources.

This offers a portable dlopening facility to load libtool libraries dynamically, and can also achieve static linking where unavoidable. Before we discuss how to use libtool with Automake in detail, it should be noted that the libtool manual also has a section about how to use Automake with libtool see Using Automake with Libtool in The Libtool Manual.

For instance, to create a libtool library named libgettext. If gettext. Headers listed in the latter should be internal headers that are not part of the public interface. A package can build and install such a library along with other programs that use it. The following example builds a program named hello that is linked with libgettext.

Whether hello is statically or dynamically linked with libgettext. The important implementation detail you have to be aware of is that the place where a library will be installed matters to libtool: it needs to be indicated at link-time using the -rpath option. For libraries whose destination directory is known when Automake runs, Automake will automatically supply the appropriate -rpath option to libtool. Therefore the -rpath argument must be explicitly supplied. Here is how the same Makefile.

Conditional compilation of sources in a library can be achieved in the same way as conditional compilation of sources in a program see Conditional compilation of sources.

So, to mimic the hello example from Conditional compilation of sources , we could build a libhello. Sometimes you want to build libtool libraries that should not be installed. These are called libtool convenience libraries and are typically used to encapsulate many sublibraries, later gathered into one big installed library.

Unlike installed libtool libraries they do not need an -rpath flag at link time this is in fact the only difference. Here is a sample setup merging libtool convenience libraries from subdirectories into one main libtop.

When using such a setup, beware that automake will assume libtop. If one of the sublibraries contains non-C source, it is important that the appropriate linker be chosen. One way to achieve this is to pretend that there is such a non-C file among the sources of the library, thus forcing automake to select the appropriate linker. In effect the file dummy. These are libtool libraries meant to be dlopened. They are indicated to libtool by passing -module at link-time. However, when building a dynamically loadable module you might wish to use a "nonstandard" name.

Automake will not complain about such nonstandard names if it knows the library being built is a libtool module, i. Therefore if -module is set via such a variable, Automake cannot notice it and will proceed as if the library was an ordinary libtool library, with strict naming.

See Link mode in The Libtool Manual. The libtool command has two kinds of options: mode-specific options and generic options. They should appear before the mode selection on the command line; in Makefile. Note that the verbosity of libtool can also be influenced by the Automake support for silent rules see How Automake can help in silencing Make.

This is required because the object files that libtool operates on do not necessarily end in. Running this command will install ltmain.

You should execute it before aclocal and automake. People upgrading old packages to newer autotools are likely to face this issue because older Automake versions used to call libtoolize.

Therefore old build scripts do not call libtoolize. Instead, that functionality has been moved into the autoreconf command see Using autoreconf in The Autoconf Manual.

If you do not want to remember what to run and when, just learn the autoreconf command. Hopefully, replacing existing bootstrap or autogen. Sometimes, the same source file is used both to build a libtool library and to build another non-libtool target be it a program or another library.

In this trivial case the issue could be avoided by linking libfoo. Technically, it means that we should build foo. The problem is that in the course of creating foo. A workaround for this issue is to ensure that these two objects get different basenames. As explained in Why are object files sometimes renamed?

However as a side effect it will cause prog. Associated with each program is a collection of variables that can be used to modify how that program is built. There is a similar list of such variables for each library. The canonical name of the program or library is used as a base for naming these variables.

In your Makefile. This variable, if it exists, lists all the source files that are compiled to build the program. These files are added to the distribution by default. When building the program, Automake will cause each source file to be compiled to a single. Normally these object files are named after the source file, but other factors can change this.

If a suffix rule exists for turning files with the unrecognized extension into. Otherwise, the file will be ignored as though it were a header file. By default the output file on Unix systems, the. However, if the option subdir-objects is in effect in the current directory then the. Some projects prefer or require this mode of operation.

This may or may not be changed in the future. Automake needs to know the list of files you intend to compile statically. For one thing, this is the only way Automake has of knowing what sort of language support a given Makefile. There are other, more obscure reasons for this limitation as well. If you intend to conditionally compile source files and use configure to substitute the appropriate object names into, e.

For instance, this should be used for objects determined by configure see Building a library. For instance, this should be used for objects determined by configure see Linking the program. For instance, if your configure. We recommend that you use -l and -L only when referring to third-party libraries, and give the explicit file names of any library built by your package.

This variable is used to pass extra flags to the link step of a program or a shared library. This variable is used to pass extra options to libtool. It is also occasionally useful to have a target program or library depend on some other file that is not in fact part of that target.

Each target depends on the contents of such a variable, but no further interpretation is done. Since these dependencies are associated with the link rule used to create the programs they should normally list files used by the link command.

You can override the linker on a per-program basis. By default the linker is chosen according to the languages used by the program. Automake allows you to set compilation flags on a per-program or per-library basis. A single source file can be included in several programs, and it will potentially be compiled with different flags for each program. This works for any language directly supported by Automake. When using a per-target compilation flag, Automake will choose a different name for the intermediate object files.

Ordinarily a file like sample. See also Why are object files sometimes renamed? On some platforms the allowable file names are very short. For instance, in the following example,. This facility is rarely needed in practice, and we recommend avoiding it until you find it is required. When no such variable is specified for a target, Automake will define one itself. For example if you have the following somewhere in your Makefile.

Default sources are mainly useful in test suites, when building many test programs each from a single source. For instance, in. Without the last line, they will be built from test1.

Another case where this is convenient is building many Libtool modules module n. Finally, there is one situation where this default source computation needs to be avoided: when a target should not be built from sources. They are substituted by configure. These variables are usually used to build a portability library that is linked with all the programs of the project.

We now review a sample setup. First, configure. Here is its Makefile. The library can have any name, of course, and anyway it is not going to be installed: it just holds the replacement versions of the missing or broken functions so we can later link them in. You should ensure that there is always something to put in libcompat. Occasionally it is useful to know which Makefile variables Automake uses for compilations, and in which order see Flag Variables Ordering ; for instance, you might need to do your own compilation in some special cases.

The contents of this variable are passed to every compilation that invokes the C preprocessor; it is a list of arguments to the preprocessor. For instance, -I and -D options should be listed here. Automake already provides some -I options automatically, in a separate variable that is also passed to every compilation that invokes the C preprocessor.

You can disable the default -I options using the nostdinc option. This matters especially for packages that use header files placed in sub-directories and want to allow builds outside the source tree see Parallel Build Trees a. In that case we recommend using a pair of -I options, such as, e. Note that the reference to the build tree should come before the reference to the source tree, so that accidentally leftover generated files in the source directory are ignored.

It is an older name for the same functionality. This is the variable the Makefile. This is the command used to compile a C source file. The file name is appended to form the complete command line. This is the command used to link a C program. Automake assumes that the. That is, for a Yacc source file foo. Be aware that header files are generated only when the option -d is given to Yacc; see below for more information about this flag, and how to specify it.

Files with the extension. The intermediate files generated by yacc or lex will be included in any distribution that is made. If a Yacc source file is seen, then your configure. The latter is a user variable and the former is intended for the Makefile. What Automake cannot guess, though, is where this header will be used: it is up to you to ensure the header gets built before it is first used.

Typically this is necessary in order for dependency tracking to work when the header is included by another file. If a Lex source file is seen, then your configure. When Yacc or Lex sources are used, automake -a automatically installs an auxiliary program called ylwrap in your package see Programs automake might require.

This program is used by the build rules to rename the output of these tools, and makes it possible to include multiple yacc or lex source files in a single directory. For yacc , simply managing locking as with ylwrap is insufficient. These defines work for bison , byacc , and traditional yacc s. If you find a parser generator that uses a symbol not covered here, please report the new name so it can be added to the list.

The command used to compile an Objective C source file. The command used to compile a Unified Parallel C source file. Automake includes some support for assembly code. The variable CCAS holds the name of the compiler used to build assembly code. This compiler must work a bit like a C compiler; in particular it must accept -c and -o. Only the suffixes. S , and. Any package including Fortran 77 code must define the output variable F77 in configure. The command used to compile a Fortran 77 source file.

Automake can handle preprocessing Fortran 77 and Ratfor source files in addition to compiling them 2. This rule runs just the preprocessor to convert a preprocessable Fortran 77 or Ratfor source file into a strict Fortran 77 source file.

The precise command used is as follows:. However, there are many other issues related to mixing Fortran 77 with other languages that are not currently handled by Automake, but that are handled by other packages 3. It is the responsibility of the person writing the Makefile. When a program or library mixes several languages, Automake chooses the linker according to the following priorities.

The names in parentheses are the variables containing the link command. Sometimes this is inconvenient because you are linking against a library written in another language and would like to set the linker more appropriately.

Any package including Fortran 9x code must define the output variable FC in configure. The command used to compile a Fortran 9x source file. Up: Fortran 9x Support [ Contents ][ Index ]. Automake includes support for natively compiled Java, using gcj , the Java front end to the GNU Compiler Collection rudimentary support for compiling Java to bytecode using the javac compiler is also present, albeit deprecated ; see Java bytecode compilation deprecated.

Any package including Java code to be compiled must define the output variable GCJ in configure. If it is necessary to pass options to gcj from Makefile. This requires valac version 0.

The generated. The end user does not need to have a Vala compiler installed. This macro takes three optional arguments. The first argument, if present, is the minimum version of the Vala API required to compile this package. For Vala releases, this is the same as the major and minor release number; e.

If a compiler is found and satisfies minimum-version , then action-if-found is run this defaults to do nothing. Otherwise, action-if-not-found is run. How can I tell automake to install arbitrary data files in places I want? I can't bear on make dist. It needs to be copied by make install its a long explanation, so, pelase just take this into account.

I rather not use install-hook , but prefer to have a more elegant approach if possible. Really thanks! Improve this question. Add a comment. Active Oldest Votes. Improve this answer. William Pursell William Pursell k 44 44 gold badges silver badges bronze badges.

Its not my choice. Any hint? Thanks — j4x. If the former, my answer works. If you mean the latter, then stop using automake; you are abusing the tool.

I mean "I, the worker that obeys my boss". The absolute path does not. Next: Why is everything so complicated? Previous: What are the differences to other build systems? Next: Where is the official documentation? Next: How do I install the Autotools as user? Next: What does. Next: Which files are hand-written and which generated and how?

Next: How do I add a Makefile. Next: How do I communicate configure test results to a Makefile? Next: How do I override Makefile macros set by automake?