Software Release Tools Manual
PrevNext

standard.mk

NAME

standard.mk — SRT make entities

Description

FIXME

Makefile Variables

Installation Directories

The release tools' standard makefile body defines the following variables. Many of them are actually defined by configure and only used by the makefiles. You must not change the values of any of these variables, nor should you try to override them on the command line. Use the appropriate options with configure instead.

The following two variables set the installation root. All other installation directories will be subdireectories of one or the other. Nothing will be installed directly into these two directories.

prefix

The prefix used to construct the default values of the other variables listed below. Defaults to ROOT/installed where ROOT is the release root directory.

exec_prefix

The prefix used to construct the default values of those variables listed below that are used for directories that will contain machine-specific files such as executables and libraries. Defaults to exec_prefix is $(prefix)/$SRT_TARGET.

Executable Programs

Executable programs are installed in one of the following directories.

bindir

The directory for installing executable programs that users can run. The default value is $(exec_prefix)/bin.

sbindir

The directory for installing executable programs that can be run from the shell, but are only generally useful to system administrators. Defaults to $(exec_prefix)/sbin.

libexecdir

The directory for installing executable programs to be run by other programs, not by users. The default value is $(exec_prefix)/libexec.

Data Files

Data files that programs use during their execution can be defined into categories in two ways:

  • some files are normally modified by programs; others are never normally modified (though users may edit some of them)

  • some files are independent of architecture and can be shared by all machines; some are dependent of architecture and can be shared only by machines of the same kind and operating system; others may never be shared between two machines.

This makes for a total of six different possibilities. However, a package should avoid using architecture-dependent files, aside of object files and libraries. It is much cleaner to make other data files architecture-independent, and it is generally not hard. Therefore, here are the variables to specify directories for data files.

datadir

The directory for installing read-only architecture-independent data files. Defaults to $(prefix)/share.

sharedstatedir

The directory for installing architecture-independent data files which the programs modify while they run. Defaults to $(prefix)/com.

NOTE

When releases are installed in one central area on a distributed file system, it is unlikely that applications will be able to modify files in this directory. Either the location should be overridden when configure is run, or the applications should not need the directory in the first place.

localstatedir

The directory for installing data files which the programs modify while they run, and that pertain to one specific machine. Users should never need to modify the files in this directory to configure the package's operation; such configuration information should be put into separate files that go in $(datadir). The default value is $(prefix)/var.

NOTE

When releases are installed in one central area on a distributed file system, there is no possibility of installing files that pertain to individual machines. There should be an additional installation procedure to carry out this step, or the applications should avoid such data in the first place. In any case the default value for this directory is unlikely to be of use; it should be overridden when configure is run.

libdir

The directory for object files and libraries of object code. Executables should not be installed here, they probably belong in $(libexecdir) instead. The default value is $(exec_prefix)/lib.

docdir

The directory for documentation other than the manual pages. If there are more than one documentation file, a subdirectory should be created in $(docdir) and the files should be put in there, not into the documentation directory itself. Defaults to $(datadir)/doc.

includedir

The directory for installing architecture-independent header files to be included by user programs with the #include preprocessor directive. It is never necessary to install header files that are needed only during the builds, not even if one of the packages is in a base release and the other is in a working release. Defaults to $(prefix)/include.

archincludedir

The directory for installing architecture-dependent header files to be included by user programs with the #include preprocessor directive. It is never necessary to install header files that are needed only during the builds, not even if one of the packages is in a base release and the other is in a working release. Defaults to $(exec_prefix)/include.

Manual Pages

Unix-style man pages use the following directories.

mandir

The directory in which various manual page sections are installed. The default value is $(prefix)/man.

man1dir, man1mdir, man2dir, man3dir, man4dir, man5dir, man6dir, man7dir, man8dir, man9dir, manldir

Use these names names to install manual pages to their proper sections. Do not make the primary documentation for any package to be a manual page. Instead, write the manual as a Web or as something easily convertible to a Web.

man1ext, man1mext, man2ext, man3ext, man4ext, man5ext, man6ext, man7ext, man8ext, man9ext, manlext

The file name extesions for installed manual pages in a particular section.

Build-Time Directories

The following variables are available to designate various build-time directories.

srcdir

The directory for the source being compiler. In other words, the directory in the source tree corresponding to the directory in which this makefile is.

top_srcdir

If the package contains subdirectories, then this variable points to the top-most source directory (the package root). If the package has no internal hierarchy, $(top_srcdir) is redundant as it will always be identical to $(srcdir).

top_builddir

The relative path pointing to the package's root directory in the build area. It is always either . for the top-most source directory in the package or a series of .. directories separated with slashes for source directories at deeper nesting levels.

Variables That Modify Behaviour

These variables modify the behaviour of the release tools makefiles. In general, they should not be set in the makefiles--the user running make should be left with the choice to apply them.

QUIET

If set to the value yes, most rules will become more quiet. Usually they will just print out what rule is being applied, and if the compiler produces no output, all you will see a list of files as they are being compiled. Use this option to cut out the verbosity of the command lines. This option should not, however, be used when compiling official releases as it renders the task of tracking errors--especially those that arise from incorrect command line options--impossible.

USE_PCH

Tell compilers to use precompiled header files if they can. This will usually make the compilations much faster, but risks hiding certain types of errors. Package authors should always make sure the package compiles without the use of precompiled headers, but otherwise they can use it as routine part of their development.

Only few compilers have precompiled header mechanisms that are usable. In fact, the release tools currently support only the mechanism used by aCC on HP-UX. Even that one has a broken implementation as of version 1.12; if enabling precompiled headers breaks in your package, file a bug report with the compiler and disable the feature.

USE_OPTION_SETS

Set the default option sets; the value should be a space-separated list of option set names. Setting this variable is equivalent to using the --with-option-sets argument to the configure scripts, except that you need to remember to supply this one every time you run make (which may be exactly what you want if you want to recompile just one file with different options). Note that this variable only defines the default option sets; targets and individual files may override this choice.

USE_TOOL

Use this tool in compilation. Few tools allow you to change the setting dynamically: all but purify require you to use the --with-tool option to configure instead. Once you have defined the tool you are not allowed to change it without rerunning configure again.

USE_FULL_PATH

This option will cause compilers that create object files to use the full path of the source files. This may help the compilers to produce debugging information that is actually usable. More precisely, when files are compiled with relative paths some compilers put only the relative path in the debugging information. This will force you to tell the debugger about all the source directories in order for you to see your files. When an executable consists of dozens of libraries created in different packages this task becomes utterly annoying. It is probably a good idea to compile official releases with this option set--at least when using compilers that are known to cause trouble.

Variables That Describe The Target

exeext

Program file extension (empty or .exe).

objext

The object file extension (o or obj).

libprefix

Library prefix for both shared and archive libraries (lib or empty).

libext

Archive library extension (a or lib).

shlext

Shared library extension (so, sl, a or dll).

_pic

File name prefix for position independent code (pic- or empty). Object code for shared libraries must often be compiled differently from code that is destined for executables or archive libraries. Systems that have no such requirements define this prefix to be empty. As the name of the variable implies, it is reserved for internal use by SRT and may be removed or changed without notice.

AR

Archive library creator.

ARFLAGS

Options to AR to create an archive library.

ARXFLAGS

Options to AR to extract object files from an archive library.

RANLIB

Command to run on archive libraries after they have been created (traditionally ranlib created an index for the library, but today that is no longer necessary on a number of systems).

INSTALL

The command that runs a BSD-style install program.

INSTALL_PROGRAM

The command to install programs (uses INSTALL)

INSTALL_DATA

The command to install data files (uses INSTALL)

Standard Targets

SRT makefiles define the following targets. Most of them are directly from the GNU Coding Standards, although some have been changed slightly and some targets have been added. For each target below you can define an extension target-local. The commands you define for that rule will be executed after the commands defined by SRT; you should not try to redefine any of these targets (adding dependencies to a target does not count as a redefinition).

all

Build everything apart from documentation and manual page files. This will be the default target in the makefile as long as the package author has not defined any other targets before including standard.mk.

check

Perform self-tests. SRT does not provide any, so you must write the checks as commands for check-local (or as commands of its dependencies). The user must run the targets the package provides before running the tests, but need not install them. The tests should be written such that they work when the targets are built but not yet installed. You should also remember to use the $(srcdir) variable to reference the programs and the data in the source directory. For example: 
check-local: prog$(exeext)
       ./prog < $(srcdir)/input.txt > out.txt
       if cmp -s $(srcdir)/valid.txt out.txt; then \
          echo check passed;                       \
       else                                        \
          echo check failed; exit 1;               \
       fi

clean

Deletes all files that are normally created by building the package. It will not delete files that record the results of running configure. It also will not delete files that are normally produced only once.

mostlyclean

Like clean, but will refrain from deleting a number of files that people normally don't want to regenerate or recompile. That is, most intermediate files will be deleted. Examples of files that will be left behind are the sources and headers generated from Objectivity schemas. Examples of files that will be deleted are the object files and built executables.

distclean

Deletes all the files that are created by configuring or building the package. Typically this returns the package to the state it was in when it was checked out from CVS. For packages that are also used outside the release tools, this target may refrain from deleting files that can be generated by the makefile but the generation requires special tools and hence the files are usually distributed with the package.

maintainer-clean

Deletes almost everything that be can be reconstructed with this makefile. This includes everything deleted by distclean and more, including files that may require special tools to regenerate and are therefore stored in CVS. The reason for ``almost everything'' is that this target will not delete the configure script, or anything that the script requires to run, even if they can be remade using rules in the makefile.

Executing this target may result in putting the package into a state where you cannot build it any more (at least not without a cvs update). Hence, building this target will cause a warning to be printed out before anything is deleted. For obvious reasons, this target is really mean only for the use of the package maintainers, not for ordinary package users. If a user is inconvenienced by the fact that special files have disappeared, they can only blame themselves. The warning the commands of this rule print helps users to be aware of this.

install

Builds all the targets except documentation and manual pages and copies them to where they should reside for actual use (the release's installation area). It will also execute the installcheck target. The release tools makes it best effort not to modify files in the installation locations unless it is absolutely necessary: if the target is built more than once in a row, only the first time around it does any real work. It also modifies nothing in the package directory provided that all has already been built; your extensions of the rule should also do the same. This is convenient for building programs under one user name and installing them under another. The target builds installdirs, too.

You should use ``-'' before any command for installing a man page so that make will ignore any errors. This is in case the pages are not wanted and the directories do not exist.

install-strip

Like install, but strips the executable files while installing them.

installcheck

Performs a simple test to verify that the programs are properly installed. The release tools know of no such tests, so write yours in the installcheck-local rule extension.

installdirs

Creates all the directories into which files will be installed, if they do not already exist. If your package needs to install files that are not covered by the release tools' support, you should probably extend this rule as well. This is necessary because it should be possible to create the installation directories under user name and install the files under another; installing the files should not try to create new directories any more.

install-man

Like install, but only for the targets built by man.

uninstall

Deletes all the installed files that the install target would create, but not the non-installed files such as all would create. This rule does not modify the directories where compilation is done, only the directories where the files are installed; the extensions of this rule should have the same behaviour.

bin

Builds all program targets (both normal and private ones). Program targets are defined with TARGET_BINS, TARGET_SBINS, TARGET_LIBEXECS, and their private counterparts.

lib

Builds all archive and shared library targets (both normal and private).

man

Builds all manual pages.

doc

Builds all documentation targets apart from the manual pages.

install-bin

Like install, but installs only the targets built by bin.

install-lib

Like install, but installs only the targets built by lib.

install-doc

Like install, but installs only the targets built by doc.

PrevHomeNext
autoconf definitionsUpsrt-env