make: Standard Targets
1
1 16.6 Standard Targets for Users
1 ===============================
1
1 All GNU programs should have the following targets in their Makefiles:
1
1 'all'
1 Compile the entire program. This should be the default target.
1 This target need not rebuild any documentation files; Info files
1 should normally be included in the distribution, and DVI (and other
1 documentation format) files should be made only when explicitly
1 asked for.
1
1 By default, the Make rules should compile and link with '-g', so
1 that executable programs have debugging symbols. Otherwise, you
1 are essentially helpless in the face of a crash, and it is often
1 far from easy to reproduce with a fresh build.
1
1 'install'
1 Compile the program and copy the executables, libraries, and so on
1 to the file names where they should reside for actual use. If
1 there is a simple test to verify that a program is properly
1 installed, this target should run that test.
1
1 Do not strip executables when installing them. This helps eventual
1 debugging that may be needed later, and nowadays disk space is
1 cheap and dynamic loaders typically ensure debug sections are not
1 loaded during normal execution. Users that need stripped binaries
1 may invoke the 'install-strip' target to do that.
1
1 If possible, write the 'install' target rule so that it does not
1 modify anything in the directory where the program was built,
1 provided 'make all' has just been done. This is convenient for
1 building the program under one user name and installing it under
1 another.
1
1 The commands should create all the directories in which files are
1 to be installed, if they don't already exist. This includes the
1 directories specified as the values of the variables 'prefix' and
1 'exec_prefix', as well as all subdirectories that are needed. One
1 way to do this is by means of an 'installdirs' target as described
1 below.
1
1 Use '-' before any command for installing a man page, so that
1 'make' will ignore any errors. This is in case there are systems
1 that don't have the Unix man page documentation system installed.
1
1 The way to install Info files is to copy them into '$(infodir)'
1 with '$(INSTALL_DATA)' (⇒Command Variables), and then run
1 the 'install-info' program if it is present. 'install-info' is a
1 program that edits the Info 'dir' file to add or update the menu
1 entry for the given Info file; it is part of the Texinfo package.
1
1 Here is a sample rule to install an Info file that also tries to
1 handle some additional situations, such as 'install-info' not being
1 present.
1
1 do-install-info: foo.info installdirs
1 $(NORMAL_INSTALL)
1 # Prefer an info file in . to one in srcdir.
1 if test -f foo.info; then d=.; \
1 else d="$(srcdir)"; fi; \
1 $(INSTALL_DATA) $$d/foo.info \
1 "$(DESTDIR)$(infodir)/foo.info"
1 # Run install-info only if it exists.
1 # Use 'if' instead of just prepending '-' to the
1 # line so we notice real errors from install-info.
1 # Use '$(SHELL) -c' because some shells do not
1 # fail gracefully when there is an unknown command.
1 $(POST_INSTALL)
1 if $(SHELL) -c 'install-info --version' \
1 >/dev/null 2>&1; then \
1 install-info --dir-file="$(DESTDIR)$(infodir)/dir" \
1 "$(DESTDIR)$(infodir)/foo.info"; \
1 else true; fi
1
1 When writing the 'install' target, you must classify all the
1 commands into three categories: normal ones, "pre-installation"
11 commands and "post-installation" commands. ⇒Install Command
Categories.
1
1 'install-html'
1 'install-dvi'
1 'install-pdf'
1 'install-ps'
1 These targets install documentation in formats other than Info;
1 they're intended to be called explicitly by the person installing
1 the package, if that format is desired. GNU prefers Info files, so
1 these must be installed by the 'install' target.
1
1 When you have many documentation files to install, we recommend
1 that you avoid collisions and clutter by arranging for these
1 targets to install in subdirectories of the appropriate
1 installation directory, such as 'htmldir'. As one example, if your
1 package has multiple manuals, and you wish to install HTML
1 documentation with many files (such as the "split" mode output by
1 'makeinfo --html'), you'll certainly want to use subdirectories, or
1 two nodes with the same name in different manuals will overwrite
1 each other.
1
1 Please make these 'install-FORMAT' targets invoke the commands for
1 the FORMAT target, for example, by making FORMAT a dependency.
1
1 'uninstall'
1 Delete all the installed files--the copies that the 'install' and
1 'install-*' targets create.
1
1 This rule should not modify the directories where compilation is
1 done, only the directories where files are installed.
1
1 The uninstallation commands are divided into three categories, just
11 like the installation commands. ⇒Install Command
Categories.
1
1 'install-strip'
1 Like 'install', but strip the executable files while installing
1 them. In simple cases, this target can use the 'install' target in
1 a simple way:
1
1 install-strip:
1 $(MAKE) INSTALL_PROGRAM='$(INSTALL_PROGRAM) -s' \
1 install
1
1 But if the package installs scripts as well as real executables,
1 the 'install-strip' target can't just refer to the 'install'
1 target; it has to strip the executables but not the scripts.
1
1 'install-strip' should not strip the executables in the build
1 directory which are being copied for installation. It should only
1 strip the copies that are installed.
1
1 Normally we do not recommend stripping an executable unless you are
1 sure the program has no bugs. However, it can be reasonable to
1 install a stripped executable for actual execution while saving the
1 unstripped executable elsewhere in case there is a bug.
1
1 'clean'
1 Delete all files in the current directory that are normally created
1 by building the program. Also delete files in other directories if
1 they are created by this makefile. However, don't delete the files
1 that record the configuration. Also preserve files that could be
1 made by building, but normally aren't because the distribution
1 comes with them. There is no need to delete parent directories
1 that were created with 'mkdir -p', since they could have existed
1 anyway.
1
1 Delete '.dvi' files here if they are not part of the distribution.
1
1 'distclean'
1 Delete all files in the current directory (or created by this
1 makefile) that are created by configuring or building the program.
1 If you have unpacked the source and built the program without
1 creating any other files, 'make distclean' should leave only the
1 files that were in the distribution. However, there is no need to
1 delete parent directories that were created with 'mkdir -p', since
1 they could have existed anyway.
1
1 'mostlyclean'
1 Like 'clean', but may refrain from deleting a few files that people
1 normally don't want to recompile. For example, the 'mostlyclean'
1 target for GCC does not delete 'libgcc.a', because recompiling it
1 is rarely necessary and takes a lot of time.
1
1 'maintainer-clean'
1 Delete almost everything that can be reconstructed with this
1 Makefile. This typically includes everything deleted by
1 'distclean', plus more: C source files produced by Bison, tags
1 tables, Info files, and so on.
1
1 The reason we say "almost everything" is that running the command
1 'make maintainer-clean' should not delete 'configure' even if
1 'configure' can be remade using a rule in the Makefile. More
1 generally, 'make maintainer-clean' should not delete anything that
1 needs to exist in order to run 'configure' and then begin to build
1 the program. Also, there is no need to delete parent directories
1 that were created with 'mkdir -p', since they could have existed
1 anyway. These are the only exceptions; 'maintainer-clean' should
1 delete everything else that can be rebuilt.
1
1 The 'maintainer-clean' target is intended to be used by a
1 maintainer of the package, not by ordinary users. You may need
1 special tools to reconstruct some of the files that 'make
1 maintainer-clean' deletes. Since these files are normally included
1 in the distribution, we don't take care to make them easy to
1 reconstruct. If you find you need to unpack the full distribution
1 again, don't blame us.
1
1 To help make users aware of this, the commands for the special
1 'maintainer-clean' target should start with these two:
1
1 @echo 'This command is intended for maintainers to use; it'
1 @echo 'deletes files that may need special tools to rebuild.'
1
1 'TAGS'
1 Update a tags table for this program.
1
1 'info'
1 Generate any Info files needed. The best way to write the rules is
1 as follows:
1
1 info: foo.info
1
1 foo.info: foo.texi chap1.texi chap2.texi
1 $(MAKEINFO) $(srcdir)/foo.texi
1
1 You must define the variable 'MAKEINFO' in the Makefile. It should
1 run the 'makeinfo' program, which is part of the Texinfo
1 distribution.
1
1 Normally a GNU distribution comes with Info files, and that means
1 the Info files are present in the source directory. Therefore, the
1 Make rule for an info file should update it in the source
1 directory. When users build the package, ordinarily Make will not
1 update the Info files because they will already be up to date.
1
1 'dvi'
1 'html'
1 'pdf'
1 'ps'
1 Generate documentation files in the given format. These targets
1 should always exist, but any or all can be a no-op if the given
1 output format cannot be generated. These targets should not be
1 dependencies of the 'all' target; the user must manually invoke
1 them.
1
1 Here's an example rule for generating DVI files from Texinfo:
1
1 dvi: foo.dvi
1
1 foo.dvi: foo.texi chap1.texi chap2.texi
1 $(TEXI2DVI) $(srcdir)/foo.texi
1
1 You must define the variable 'TEXI2DVI' in the Makefile. It should
1 run the program 'texi2dvi', which is part of the Texinfo
1 distribution. ('texi2dvi' uses TeX to do the real work of
1 formatting. TeX is not distributed with Texinfo.) Alternatively,
1 write only the dependencies, and allow GNU 'make' to provide the
1 command.
1
1 Here's another example, this one for generating HTML from Texinfo:
1
1 html: foo.html
1
1 foo.html: foo.texi chap1.texi chap2.texi
1 $(TEXI2HTML) $(srcdir)/foo.texi
1
1 Again, you would define the variable 'TEXI2HTML' in the Makefile;
1 for example, it might run 'makeinfo --no-split --html' ('makeinfo'
1 is part of the Texinfo distribution).
1
1 'dist'
1 Create a distribution tar file for this program. The tar file
1 should be set up so that the file names in the tar file start with
1 a subdirectory name which is the name of the package it is a
1 distribution for. This name can include the version number.
1
1 For example, the distribution tar file of GCC version 1.40 unpacks
1 into a subdirectory named 'gcc-1.40'.
1
1 The easiest way to do this is to create a subdirectory
1 appropriately named, use 'ln' or 'cp' to install the proper files
1 in it, and then 'tar' that subdirectory.
1
1 Compress the tar file with 'gzip'. For example, the actual
1 distribution file for GCC version 1.40 is called 'gcc-1.40.tar.gz'.
1 It is ok to support other free compression formats as well.
1
1 The 'dist' target should explicitly depend on all non-source files
1 that are in the distribution, to make sure they are up to date in
1 the distribution. ⇒Making Releases (standards)Releases.
1
1 'check'
1 Perform self-tests (if any). The user must build the program
1 before running the tests, but need not install the program; you
1 should write the self-tests so that they work when the program is
1 built but not installed.
1
1 The following targets are suggested as conventional names, for
1 programs in which they are useful.
1
1 'installcheck'
1 Perform installation tests (if any). The user must build and
1 install the program before running the tests. You should not
1 assume that '$(bindir)' is in the search path.
1
1 'installdirs'
1 It's useful to add a target named 'installdirs' to create the
1 directories where files are installed, and their parent
1 directories. There is a script called 'mkinstalldirs' which is
1 convenient for this; you can find it in the Gnulib package. You
1 can use a rule like this:
1
1 # Make sure all installation directories (e.g. $(bindir))
1 # actually exist by making them if necessary.
1 installdirs: mkinstalldirs
1 $(srcdir)/mkinstalldirs $(bindir) $(datadir) \
1 $(libdir) $(infodir) \
1 $(mandir)
1
1 or, if you wish to support 'DESTDIR' (strongly encouraged),
1
1 # Make sure all installation directories (e.g. $(bindir))
1 # actually exist by making them if necessary.
1 installdirs: mkinstalldirs
1 $(srcdir)/mkinstalldirs \
1 $(DESTDIR)$(bindir) $(DESTDIR)$(datadir) \
1 $(DESTDIR)$(libdir) $(DESTDIR)$(infodir) \
1 $(DESTDIR)$(mandir)
1
1 This rule should not modify the directories where compilation is
1 done. It should do nothing but create installation directories.
1