Return to make-stds.texi CVS log

Up to [Apple XNU] / GNUtools / libg++ / etc

Annotation of GNUtools/libg++/etc/make-stds.texi, revision 1.1

1.1     ! root        1: @comment This file is included by both standards.texi and make.texinfo.
        !             2: @comment It was broken out of standards.texi on 1/6/93 by roland.
        !             3: 
        !             4: @node Makefile Conventions
        !             5: @chapter Makefile Conventions
        !             6: @comment standards.texi does not print an index, but make.texinfo does.
        !             7: @cindex makefile, conventions for
        !             8: @cindex conventions for makefiles
        !             9: @cindex standards for makefiles
        !            10: 
        !            11: This chapter describes conventions for writing the Makefiles for GNU programs.
        !            12: 
        !            13: @menu
        !            14: * Makefile Basics::
        !            15: * Utilities in Makefiles::
        !            16: * Standard Targets::
        !            17: * Command Variables::
        !            18: * Directory Variables::
        !            19: @end menu
        !            20: 
        !            21: @node Makefile Basics
        !            22: @section General Conventions for Makefiles
        !            23: 
        !            24: Every Makefile should contain this line:
        !            25: 
        !            26: @example
        !            27: SHELL = /bin/sh
        !            28: @end example
        !            29: 
        !            30: @noindent
        !            31: to avoid trouble on systems where the @code{SHELL} variable might be
        !            32: inherited from the environment.  (This is never a problem with GNU
        !            33: @code{make}.)
        !            34: 
        !            35: Don't assume that @file{.} is in the path for command execution.  When
        !            36: you need to run programs that are a part of your package during the
        !            37: make, please make sure that it uses @file{./} if the program is built as
        !            38: part of the make or @file{$(srcdir)/} if the file is an unchanging part
        !            39: of the source code.  Without one of these prefixes, the current search
        !            40: path is used.  
        !            41: 
        !            42: The distinction between @file{./} and @file{$(srcdir)/} is important
        !            43: when using the @samp{--srcdir} option to @file{configure}.  A rule of
        !            44: the form:
        !            45: 
        !            46: @example
        !            47: foo.1 : foo.man sedscript
        !            48:         sed -e sedscript foo.man > foo.1
        !            49: @end example
        !            50: 
        !            51: @noindent
        !            52: will fail when the current directory is not the source directory,
        !            53: because @file{foo.man} and @file{sedscript} are not in the current
        !            54: directory.
        !            55: 
        !            56: When using GNU @code{make}, relying on @samp{VPATH} to find the source
        !            57: file will work in the case where there is a single dependency file,
        !            58: since the @file{make} automatic variable @samp{$<} will represent the
        !            59: source file wherever it is.  (Many versions of @code{make} set @samp{$<}
        !            60: only in implicit rules.)  A makefile target like
        !            61: 
        !            62: @example
        !            63: foo.o : bar.c
        !            64:         $(CC) -I. -I$(srcdir) $(CFLAGS) -c bar.c -o foo.o
        !            65: @end example
        !            66: 
        !            67: @noindent
        !            68: should instead be written as
        !            69: 
        !            70: @example
        !            71: foo.o : bar.c
        !            72:         $(CC) $(CFLAGS) $< -o $@@
        !            73: @end example
        !            74: 
        !            75: @noindent
        !            76: in order to allow @samp{VPATH} to work correctly.  When the target has
        !            77: multiple dependencies, using an explicit @samp{$(srcdir)} is the easiest
        !            78: way to make the rule work well.  For example, the target above for
        !            79: @file{foo.1} is best written as:
        !            80: 
        !            81: @example
        !            82: foo.1 : foo.man sedscript
        !            83:         sed -s $(srcdir)/sedscript $(srcdir)/foo.man > foo.1
        !            84: @end example
        !            85: 
        !            86: @node Utilities in Makefiles
        !            87: @section Utilities in Makefiles
        !            88: 
        !            89: Write the Makefile commands (and any shell scripts, such as
        !            90: @code{configure}) to run in @code{sh}, not in @code{csh}.  Don't use any
        !            91: special features of @code{ksh} or @code{bash}.
        !            92: 
        !            93: The @code{configure} script and the Makefile rules for building and
        !            94: installation should not use any utilities directly except these:
        !            95: 
        !            96: @example
        !            97: cat cmp cp echo egrep expr grep
        !            98: ln mkdir mv pwd rm rmdir sed test touch
        !            99: @end example
        !           100: 
        !           101: Stick to the generally supported options for these programs.  For
        !           102: example, don't use @samp{mkdir -p}, convenient as it may be, because
        !           103: most systems don't support it.
        !           104: 
        !           105: The Makefile rules for building and installation can also use compilers
        !           106: and related programs, but should do so via @code{make} variables so that the
        !           107: user can substitute alternatives.  Here are some of the programs we
        !           108: mean:
        !           109: 
        !           110: @example
        !           111: ar bison cc flex install ld lex
        !           112: make makeinfo ranlib texi2dvi yacc
        !           113: @end example
        !           114: 
        !           115: When you use @code{ranlib}, you should test whether it exists, and run
        !           116: it only if it exists, so that the distribution will work on systems that
        !           117: don't have @code{ranlib}.
        !           118: 
        !           119: If you use symbolic links, you should implement a fallback for systems
        !           120: that don't have symbolic links.
        !           121: 
        !           122: It is ok to use other utilities in Makefile portions (or scripts)
        !           123: intended only for particular systems where you know those utilities to
        !           124: exist.
        !           125: 
        !           126: @node Standard Targets
        !           127: @section Standard Targets for Users
        !           128: 
        !           129: All GNU programs should have the following targets in their Makefiles:
        !           130: 
        !           131: @table @samp
        !           132: @item all
        !           133: Compile the entire program.  This should be the default target.  This
        !           134: target need not rebuild any documentation files; info files should
        !           135: normally be included in the distribution, and DVI files should be made
        !           136: only when explicitly asked for.
        !           137: 
        !           138: @item install
        !           139: Compile the program and copy the executables, libraries, and so on to
        !           140: the file names where they should reside for actual use.  If there is a
        !           141: simple test to verify that a program is properly installed then run that
        !           142: test.
        !           143: 
        !           144: Use @samp{-} before any command for installing a man page, so that
        !           145: @code{make} will ignore any errors.  This is in case there are systems
        !           146: that don't have the Unix man page documentation system installed.
        !           147: 
        !           148: In the future, when we have a standard way of installing info files,
        !           149: @samp{install} targets will be the proper place to do so.
        !           150: 
        !           151: @item uninstall
        !           152: Delete all the installed files that the @samp{install} target would
        !           153: create (but not the noninstalled files such as @samp{make all} would
        !           154: create).
        !           155: 
        !           156: @item clean
        !           157: Delete all files from the current directory that are normally created by
        !           158: building the program.  Don't delete the files that record the
        !           159: configuration.  Also preserve files that could be made by building, but
        !           160: normally aren't because the distribution comes with them.
        !           161: 
        !           162: Delete @file{.dvi} files here if they are not part of the distribution.
        !           163: 
        !           164: @item distclean
        !           165: Delete all files from the current directory that are created by
        !           166: configuring or building the program.  If you have unpacked the source
        !           167: and built the program without creating any other files, @samp{make
        !           168: distclean} should leave only the files that were in the distribution.
        !           169: 
        !           170: @item mostlyclean
        !           171: Like @samp{clean}, but may refrain from deleting a few files that people
        !           172: normally don't want to recompile.  For example, the @samp{mostlyclean}
        !           173: target for GCC does not delete @file{libgcc.a}, because recompiling it
        !           174: is rarely necessary and takes a lot of time.
        !           175: 
        !           176: @item realclean
        !           177: Delete everything from the current directory that can be reconstructed
        !           178: with this Makefile.  This typically includes everything deleted by
        !           179: distclean, plus more: C source files produced by Bison, tags tables,
        !           180: info files, and so on.
        !           181: 
        !           182: One exception, however: @samp{make realclean} should not delete
        !           183: @file{configure} even if @file{configure} can be remade using a rule in
        !           184: the Makefile.  More generally, @samp{make realclean} should not delete
        !           185: anything that needs to exist in order to run @file{configure}
        !           186: and then begin to build the program.
        !           187: 
        !           188: @item TAGS
        !           189: Update a tags table for this program.
        !           190: 
        !           191: @item info
        !           192: Generate any info files needed.  The best way to write the rules is as
        !           193: follows:
        !           194: 
        !           195: @example
        !           196: info:  foo.info
        !           197: 
        !           198: foo.info: $(srcdir)/foo.texi $(srcdir)/chap1.texi $(srcdir)/chap2.texi
        !           199:         $(MAKEINFO) $(srcdir)/foo.texi
        !           200: @end example
        !           201: 
        !           202: @noindent
        !           203: You must define the variable @code{MAKEINFO} in the Makefile.
        !           204: It should run the Makeinfo program, which is part of the Texinfo2 distribution.
        !           205: 
        !           206: @item dvi
        !           207: Generate DVI files for all TeXinfo documentation.  
        !           208: For example:
        !           209: 
        !           210: @example
        !           211: dvi: foo.dvi
        !           212: 
        !           213: foo.dvi: $(srcdir)/foo.texi $(srcdir)/chap1.texi $(srcdir)/chap2.texi
        !           214:         $(TEXI2DVI) $(srcdir)/foo.texi
        !           215: @end example
        !           216: 
        !           217: @noindent
        !           218: You must define the variable @code{TEXI2DVI} in the Makefile.  It should
        !           219: run the program @code{texi2dvi}, which is part of the Texinfo2
        !           220: distribution.  Alternatively, write just the dependencies, and allow GNU
        !           221: Make to provide the command.
        !           222: 
        !           223: @item dist
        !           224: Create a distribution tar file for this program.  The tar file should be
        !           225: set up so that the file names in the tar file start with a subdirectory
        !           226: name which is the name of the package it is a distribution for.  This
        !           227: name can include the version number.
        !           228: 
        !           229: For example, the distribution tar file of GCC version 1.40 unpacks into
        !           230: a subdirectory named @file{gcc-1.40}.
        !           231: 
        !           232: The easiest way to do this is to create a subdirectory appropriately
        !           233: named, use @code{ln} or @code{cp} to install the proper files in it, and
        !           234: then @code{tar} that subdirectory.
        !           235: 
        !           236: The @code{dist} target should explicitly depend on all non-source files
        !           237: that are in the distribution, to make sure they are up to date in the
        !           238: distribution.  
        !           239: @xref{Releases, , Making Releases, standards, GNU Coding Standards}.
        !           240: 
        !           241: @item check
        !           242: Perform self-tests (if any).  The user must build the program before
        !           243: running the tests, but need not install the program; you should write
        !           244: the self-tests so that they work when the program is built but not
        !           245: installed.
        !           246: @end table
        !           247: 
        !           248: The following targets are suggested as conventional names, for programs
        !           249: in which they are useful.
        !           250: 
        !           251: @table @code
        !           252: @item installcheck
        !           253: Perform installation tests (if any).  The user must build and install
        !           254: the program before running the tests.  You should not assume that
        !           255: @file{$(bindir)} is in the search path.  
        !           256: 
        !           257: @item installdirs
        !           258: It's useful to add a target named @samp{installdirs} to create the
        !           259: directories where files are installed, and their parent directories.
        !           260: There is a script called @file{mkinstalldirs} which is convenient for
        !           261: this; find it in the Texinfo package.@c It's in /gd/gnu/lib/mkinstalldirs.
        !           262: You can use a rule like this:
        !           263: 
        !           264: @example
        !           265: # Make sure all installation directories, e.g. $(bindir) actually exist by
        !           266: # making them if necessary.
        !           267: installdirs: mkinstalldirs
        !           268:         $(srcdir)/mkinstalldirs $(bindir) $(datadir) $(libdir) \
        !           269:                                 $(infodir) $(mandir)
        !           270: @end example
        !           271: @end table
        !           272: 
        !           273: @node Command Variables
        !           274: @section Variables for Specifying Commands
        !           275: 
        !           276: Makefiles should provide variables for overriding certain commands, options,
        !           277: and so on.
        !           278: 
        !           279: In particular, you should run most utility programs via variables.
        !           280: Thus, if you use Bison, have a variable named @code{BISON} whose default
        !           281: value is set with @samp{BISON = bison}, and refer to it with
        !           282: @code{$(BISON)} whenever you need to use Bison.
        !           283: 
        !           284: File management utilities such as @code{ln}, @code{rm}, @code{mv}, and
        !           285: so on, need not be referred to through variables in this way, since users
        !           286: don't need to replace them with other programs.
        !           287: 
        !           288: Each program-name variable should come with an options variable that is
        !           289: used to supply options to the program.  Append @samp{FLAGS} to the
        !           290: program-name variable name to get the options variable name---for
        !           291: example, @code{BISONFLAGS}.  (The name @code{CFLAGS} is an exception to
        !           292: this rule, but we keep it because it is standard.)  Use @code{CPPFLAGS}
        !           293: in any compilation command that runs the preprocessor, and use
        !           294: @code{LDFLAGS} in any compilation command that does linking as well as
        !           295: in any direct use of @code{ld}.
        !           296: 
        !           297: If there are C compiler options that @emph{must} be used for proper
        !           298: compilation of certain files, do not include them in @code{CFLAGS}.
        !           299: Users expect to be able to specify @code{CFLAGS} freely themselves.
        !           300: Instead, arrange to pass the necessary options to the C compiler
        !           301: independently of @code{CFLAGS}, by writing them explicitly in the
        !           302: compilation commands or by defining an implicit rule, like this:
        !           303: 
        !           304: @example
        !           305: CFLAGS = -g
        !           306: ALL_CFLAGS = -I. $(CFLAGS)
        !           307: .c.o:
        !           308:         $(CC) -c $(CPPFLAGS) $(ALL_CFLAGS) $<
        !           309: @end example
        !           310: 
        !           311: Do include the @samp{-g} option in @code{CFLAGS}, because that is not
        !           312: @emph{required} for proper compilation.  You can consider it a default
        !           313: that is only recommended.  If the package is set up so that it is
        !           314: compiled with GCC by default, then you might as well include @samp{-O}
        !           315: in the default value of @code{CFLAGS} as well.
        !           316: 
        !           317: Put @code{CFLAGS} last in the compilation command, after other variables
        !           318: containing compiler options, so the user can use @code{CFLAGS} to
        !           319: override the others.
        !           320: 
        !           321: Every Makefile should define the variable @code{INSTALL}, which is the
        !           322: basic command for installing a file into the system.
        !           323: 
        !           324: Every Makefile should also define variables @code{INSTALL_PROGRAM} and
        !           325: @code{INSTALL_DATA}.  (The default for each of these should be
        !           326: @code{$(INSTALL)}.)  Then it should use those variables as the commands
        !           327: for actual installation, for executables and nonexecutables
        !           328: respectively.  Use these variables as follows:
        !           329: 
        !           330: @example
        !           331: $(INSTALL_PROGRAM) foo $(bindir)/foo
        !           332: $(INSTALL_DATA) libfoo.a $(libdir)/libfoo.a
        !           333: @end example
        !           334: 
        !           335: @noindent
        !           336: Always use a file name, not a directory name, as the second argument of
        !           337: the installation commands.  Use a separate command for each file to be
        !           338: installed.
        !           339: 
        !           340: @node Directory Variables
        !           341: @section Variables for Installation Directories
        !           342: 
        !           343: Installation directories should always be named by variables, so it is
        !           344: easy to install in a nonstandard place.  The standard names for these
        !           345: variables are:
        !           346: 
        !           347: @table @samp
        !           348: @item prefix
        !           349: A prefix used in constructing the default values of the variables listed
        !           350: below.  The default value of @code{prefix} should be @file{/usr/local}
        !           351: (at least for now).
        !           352: 
        !           353: @item exec_prefix
        !           354: A prefix used in constructing the default values of the some of the
        !           355: variables listed below.  The default value of @code{exec_prefix} should
        !           356: be @code{$(prefix)}.
        !           357: 
        !           358: Generally, @code{$(exec_prefix)} is used for directories that contain
        !           359: machine-specific files (such as executables and subroutine libraries),
        !           360: while @code{$(prefix)} is used directly for other directories.
        !           361: 
        !           362: @item bindir
        !           363: The directory for installing executable programs that users can run.
        !           364: This should normally be @file{/usr/local/bin}, but write it as
        !           365: @file{$(exec_prefix)/bin}.
        !           366: 
        !           367: @item libdir
        !           368: The directory for installing executable files to be run by the program
        !           369: rather than by users.  Object files and libraries of object code should
        !           370: also go in this directory.  The idea is that this directory is used for
        !           371: files that pertain to a specific machine architecture, but need not be
        !           372: in the path for commands.  The value of @code{libdir} should normally be
        !           373: @file{/usr/local/lib}, but write it as @file{$(exec_prefix)/lib}.
        !           374: 
        !           375: @item datadir
        !           376: The directory for installing read-only data files which the programs
        !           377: refer to while they run.  This directory is used for files which are
        !           378: independent of the type of machine being used.  This should normally be
        !           379: @file{/usr/local/lib}, but write it as @file{$(prefix)/lib}.
        !           380: 
        !           381: @item statedir
        !           382: The directory for installing data files which the programs modify while
        !           383: they run.  These files should be independent of the type of machine
        !           384: being used, and it should be possible to share them among machines at a
        !           385: network installation.  This should normally be @file{/usr/local/lib},
        !           386: but write it as @file{$(prefix)/lib}.
        !           387: 
        !           388: @item includedir
        !           389: @c rewritten to avoid overfull hbox --roland
        !           390: The directory for installing header files to be included by user
        !           391: programs with the C @samp{#include} preprocessor directive.  This
        !           392: should normally be @file{/usr/local/include}, but write it as
        !           393: @file{$(prefix)/include}.
        !           394: 
        !           395: Most compilers other than GCC do not look for header files in
        !           396: @file{/usr/local/include}.  So installing the header files this way is
        !           397: only useful with GCC.  Sometimes this is not a problem because some
        !           398: libraries are only really intended to work with GCC.  But some libraries
        !           399: are intended to work with other compilers.  They should install their
        !           400: header files in two places, one specified by @code{includedir} and one
        !           401: specified by @code{oldincludedir}.
        !           402: 
        !           403: @item oldincludedir
        !           404: The directory for installing @samp{#include} header files for use with
        !           405: compilers other than GCC.  This should normally be @file{/usr/include}.
        !           406: 
        !           407: The Makefile commands should check whether the value of
        !           408: @code{oldincludedir} is empty.  If it is, they should not try to use
        !           409: it; they should cancel the second installation of the header files.
        !           410: 
        !           411: A package should not replace an existing header in this directory unless
        !           412: the header came from the same package.  Thus, if your Foo package
        !           413: provides a header file @file{foo.h}, then it should install the header
        !           414: file in the @code{oldincludedir} directory if either (1) there is no
        !           415: @file{foo.h} there or (2) the @file{foo.h} that exists came from the Foo
        !           416: package.
        !           417: 
        !           418: The way to tell whether @file{foo.h} came from the Foo package is to put
        !           419: a magic string in the file---part of a comment---and grep for that
        !           420: string.
        !           421: 
        !           422: @item mandir
        !           423: The directory for installing the man pages (if any) for this package.
        !           424: It should include the suffix for the proper section of the
        !           425: manual---usually @samp{1} for a utility.
        !           426: 
        !           427: @item man1dir
        !           428: The directory for installing section 1 man pages.
        !           429: @item man2dir
        !           430: The directory for installing section 2 man pages.
        !           431: @item @dots{}
        !           432: Use these names instead of @samp{mandir} if the package needs to install man
        !           433: pages in more than one section of the manual.
        !           434: 
        !           435: @strong{Don't make the primary documentation for any GNU software be a
        !           436: man page.  Write a manual in Texinfo instead.  Man pages are just for
        !           437: the sake of people running GNU software on Unix, which is a secondary
        !           438: application only.}
        !           439: 
        !           440: @item manext
        !           441: The file name extension for the installed man page.  This should contain
        !           442: a period followed by the appropriate digit.
        !           443: 
        !           444: @item infodir
        !           445: The directory for installing the info files for this package.  By
        !           446: default, it should be @file{/usr/local/info}, but it should be written
        !           447: as @file{$(prefix)/info}.
        !           448: 
        !           449: @item srcdir
        !           450: The directory for the sources being compiled.  The value of this
        !           451: variable is normally inserted by the @code{configure} shell script.
        !           452: @end table
        !           453: 
        !           454: For example:
        !           455: 
        !           456: @example
        !           457: @c I have changed some of the comments here slightly to fix an overfull
        !           458: @c hbox, so the make manual can format correctly. --roland
        !           459: # Common prefix for installation directories.
        !           460: # NOTE: This directory must exist when you start the install.
        !           461: prefix = /usr/local
        !           462: exec_prefix = $(prefix)
        !           463: # Where to put the executable for the command `gcc'.
        !           464: bindir = $(exec_prefix)/bin
        !           465: # Where to put the directories used by the compiler.
        !           466: libdir = $(exec_prefix)/lib
        !           467: # Where to put the Info files.
        !           468: infodir = $(prefix)/info
        !           469: @end example
        !           470: 
        !           471: If your program installs a large number of files into one of the
        !           472: standard user-specified directories, it might be useful to group them
        !           473: into a subdirectory particular to that program.  If you do this, you
        !           474: should write the @code{install} rule to create these subdirectories.
        !           475: 
        !           476: Do not expect the user to include the subdirectory name in the value of
        !           477: any of the variables listed above.  The idea of having a uniform set of
        !           478: variable names for installation directories is to enable the user to
        !           479: specify the exact same values for several different GNU packages.  In
        !           480: order for this to be useful, all the packages must be designed so that
        !           481: they will work sensibly when the user does so.
        !           482: 

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.