share/mk/bsd.README

   1 #       @(#)bsd.README  8.2 (Berkeley) 4/2/94
   2 # $FreeBSD: src/share/mk/bsd.README,v 1.15.2.6 2002/07/19 08:34:07 ru Exp $
   3 # $DragonFly: src/share/mk/bsd.README,v 1.6 2006/09/27 12:10:35 corecode Exp $
   4
   5 XXX This document is seriously out of date, it is currenly being revised.
   6
   7 This is the README file for the new make "include" files for the BSD
   8 source tree.  The files are installed in /usr/share/mk, and are, by
   9 convention, named with the suffix ".mk".
  10
  11 bsd.cpu.gcc34.mk        - handle GCC 3.4 specific CPU flags & variables
  12 bsd.cpu.gcc40.mk        - handle GCC 4.0 specific CPU flags & variables
  13 bsd.cpu.gcc41.mk        - handle GCC 4.1 specific CPU flags & variables
  14 bsd.cpu.mk              - handle CPU flags & variables
  15 bsd.dep.mk              - handle Makefile dependencies
  16 bsd.doc.mk              - building troff system documents
  17 bsd.files.mk            -
  18 bsd.hostlib.mk          -
  19 bsd.hostprog.mk         -
  20 bsd.incs.mk             -
  21 bsd.info.mk             - building GNU Info hypertext system
  22 bsd.init.mk             -
  23 bsd.kmod.mk             - building loadable kernel modules
  24 bsd.lib.mk              - support for building libraries
  25 bsd.libnames.mk         - define library names
  26 bsd.links.mk            -
  27 bsd.man.mk              - installing manual pages and their links
  28 bsd.nls.mk              -
  29 bsd.obj.mk              - creating 'obj' directories and cleaning up
  30 bsd.own.mk              - define common variables
  31 bsd.patch.mk            -
  32 bsd.prog.mk             - building programs from source files
  33 bsd.subdir.mk           - targets for building subdirectories
  34 bsd.sys.mk              -
  35 sys.mk                  -
  36
  37
  38 Note, this file is not intended to replace reading through the .mk
  39 files for anything tricky.
  40
  41 See also make(1), mkdep(1) and `PMake - A Tutorial',
  42 located in /usr/share/doc/psd/12.make.
  43
  44 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
  45
  46 RANDOM THINGS WORTH KNOWING:
  47
  48 The files are simply C-style #include files, and pretty much behave like
  49 you'd expect.  The syntax is slightly different in that a single '.' is
  50 used instead of the hash mark, i.e. ".include <bsd.prog.mk>".
  51
  52 One difference that will save you lots of debugging time is that inclusion
  53 of the file is normally done at the *end* of the Makefile.  The reason for
  54 this is because .mk files often modify variables and behavior based on the
  55 values of variables set in the Makefile.  To make this work, remember that
  56 the FIRST target found is the target that is used, i.e. if the Makefile has:
  57
  58         a:
  59                 echo a
  60         a:
  61                 echo a number two
  62
  63 the command "make a" will echo "a".  To make things confusing, the SECOND
  64 variable assignment is the overriding one, i.e. if the Makefile has:
  65
  66         a=      foo
  67         a=      bar
  68
  69         b:
  70                 echo ${a}
  71
  72 the command "make b" will echo "bar".  This is for compatibility with the
  73 way the V7 make behaved.
  74
  75 It's fairly difficult to make the BSD .mk files work when you're building
  76 multiple programs in a single directory.  It's a lot easier split up the
  77 programs than to deal with the problem.  Most of the agony comes from making
  78 the "obj" directory stuff work right, not because we switch to a new version
  79 of make.  So, don't get mad at us, figure out a better way to handle multiple
  80 architectures so we can quit using the symbolic link stuff.  (Imake doesn't
  81 count.)
  82
  83 The file .depend in the source directory is expected to contain dependencies
  84 for the source files.  This file is read automatically by make after reading
  85 the Makefile.
  86
  87 The variable DESTDIR works as before.  It's not set anywhere but will change
  88 the tree where the file gets installed.
  89
  90 The profiled libraries are no longer built in a different directory than
  91 the regular libraries.  A new suffix, ".po", is used to denote a profiled
  92 object.
  93
  94 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
  95
  96 The include file <sys.mk> has the default rules for all makes, in the BSD
  97 environment or otherwise.  You probably don't want to touch this file.
  98
  99 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
 100
 101 The include file <bsd.man.mk> handles installing manual pages and their
 102 links.
 103
 104 It has three targets:
 105
 106         all-man:
 107                 build manual pages.
 108         maninstall:
 109                 install the manual pages and their links.
 110         manlint:
 111                 verify the validity of manual pages.
 112
 113 It sets/uses the following variables:
 114
 115 MANDIR          Base path for manual installation.
 116
 117 MANGRP          Manual group.
 118
 119 MANOWN          Manual owner.
 120
 121 MANMODE         Manual mode.
 122
 123 MANSUBDIR       Subdirectory under the manual page section, i.e. "/vax"
 124                 or "/tahoe" for machine specific manual pages.
 125
 126 MAN             The manual pages to be installed (use a .1 - .9 suffix).
 127
 128 MLINKS          List of manual page links (using a .1 - .9 suffix).  The
 129                 linked-to file must come first, the linked file second,
 130                 and there may be multiple pairs.  The files are soft-linked.
 131
 132 The include file <bsd.man.mk> includes a file named "../Makefile.inc" if
 133 it exists.
 134
 135 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
 136
 137 The include file <bsd.own.mk> contains the owners, groups, etc. for both
 138 manual pages and binaries.
 139
 140 It has no targets.
 141
 142 It sets/uses the following variables:
 143
 144 BINGRP          Binary group.
 145
 146 BINOWN          Binary owner.
 147
 148 BINMODE         Binary mode.
 149
 150 STRIP           The flag passed to the install program to cause the binary
 151                 to be stripped.  This is to be used when building your
 152                 own install script so that the entire system can be made
 153                 stripped/not-stripped using a single nob.
 154
 155 MANDIR          Base path for manual installation.
 156
 157 MANGRP          Manual group.
 158
 159 MANOWN          Manual owner.
 160
 161 MANMODE         Manual mode.
 162
 163 This file is generally useful when building your own Makefiles so that
 164 they use the same default owners etc. as the rest of the tree.
 165
 166 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
 167
 168 The include file <bsd.prog.mk> handles building programs from one or
 169 more source files, along with their manual pages.  It has a limited number
 170 of suffixes, consistent with the current needs of the BSD tree.
 171
 172 It has seven targets:
 173
 174         all:
 175                 build the program and its manual page
 176         clean:
 177                 remove the program, any object files and the files a.out,
 178                 Errs, errs, mklog, and ${PROG}.core.
 179         cleandir:
 180                 remove all of the files removed by the target clean, as
 181                 well as .depend, tags, and any manual pages.
 182         depend:
 183                 make the dependencies for the source files, and store
 184                 them in the file .depend.
 185         install:
 186                 install the program and its manual pages; if the Makefile
 187                 does not itself define the target install, the targets
 188                 beforeinstall and afterinstall may also be used to cause
 189                 actions immediately before and after the install target
 190                 is executed.
 191         lint:
 192                 run lint on the source files
 193         tags:
 194                 create a tags file for the source files.
 195
 196 It sets/uses the following variables:
 197
 198 BINGRP          Binary group.
 199
 200 BINOWN          Binary owner.
 201
 202 BINMODE         Binary mode.
 203
 204 CLEANFILES      Additional files to remove and
 205 CLEANDIRS       additional directories to remove during clean and cleandir
 206                 targets.  "rm -f" and "rm -rf" used respectively.
 207
 208 COPTS           Additional flags to the compiler when creating C objects.
 209
 210 FILES           A list of non-executable files.
 211                 The installation is controlled by the FILESNAME, FILESOWN,
 212                 FILESGRP, FILESMODE, FILESDIR variables that can be
 213                 further specialized by FILES<VAR>_<file>.
 214
 215 HIDEGAME        If HIDEGAME is defined, the binary is installed in
 216                 /usr/games/hide, and a symbolic link is created to
 217                 /usr/games/dm.
 218
 219 LDADD           Additional loader objects.  Usually used for libraries.
 220                 For example, to load with the compatibility and utility
 221                 libraries, use:
 222
 223                         LDFILES=-lutil -lcompat
 224
 225 LDFLAGS         Additional loader flags.
 226
 227 LINKS           The list of binary links; should be full pathnames, the
 228                 linked-to file coming first, followed by the linked
 229                 file.  The files are hard-linked.  For example, to link
 230                 /bin/test and /bin/[, use:
 231
 232                         LINKS=  ${DESTDIR}/bin/test ${DESTDIR}/bin/[
 233
 234 MAN             Manual pages (should end in .1 - .9).  If no MAN variable
 235                 is defined, "MAN=${PROG}.1" is assumed.
 236
 237 PROG            The name of the program to build.  If not supplied, nothing
 238                 is built.
 239
 240 PROG_CXX        If defined, the name of the program to build.  Also
 241                 causes <bsd.prog.mk> to link the program with the
 242                 standard C++ library.  PROG_CXX overrides the value
 243                 of PROG if PROG is also set.
 244
 245 PROGNAME        The name that the above program will be installed as, if
 246                 different from ${PROG}.
 247
 248 SRCS            List of source files to build the program.  If SRCS is not
 249                 defined, it's assumed to be ${PROG}.c or, if PROG_CXX is
 250                 defined, ${PROG_CXX}.cc.
 251
 252 DPADD           Additional dependencies for the program.  Usually used for
 253                 libraries.  For example, to depend on the compatibility and
 254                 utility libraries use:
 255
 256                         SRCLIB=${LIBCOMPAT} ${LIBUTIL}
 257
 258                 There is a predefined identifier for each (non-profiled,
 259                 non-shared) library and object.  Library file names are
 260                 transformed to identifiers by removing the extension and
 261                 converting to upper case.
 262
 263                 There are no special identifiers for profiled or shared
 264                 libraries or objects.  The identifiers for the standard
 265                 libraries are used in DPADD.  This works correctly iff all
 266                 the libraries are built at the same time.  Unfortunately,
 267                 it causes unnecessary relinks to shared libraries when
 268                 only the static libraries have changed.  Dependencies on
 269                 shared libraries should be only on the library version
 270                 numbers.
 271
 272 STRIP           The flag passed to the install program to cause the binary
 273                 to be stripped.
 274
 275 SUBDIR          A list of subdirectories that should be built as well.
 276                 Each of the targets will execute the same target in the
 277                 subdirectories.
 278
 279 SCRIPTS         A list of interpreter scripts [file.{sh,csh,pl,awk,...}].
 280                 The installation is controlled by the SCRIPTSNAME, SCRIPTSOWN,
 281                 SCRIPTSGRP, SCRIPTSMODE, SCRIPTSDIR variables that can be
 282                 further specialized by SCRIPTS<VAR>_<script>.
 283
 284 The include file <bsd.prog.mk> includes the file named "../Makefile.inc"
 285 if it exists, as well as the include file <bsd.man.mk>.
 286
 287 Some simple examples:
 288
 289 To build foo from foo.c with a manual page foo.1, use:
 290
 291         PROG=   foo
 292
 293         .include <bsd.prog.mk>
 294
 295 To build foo from foo.c with a manual page foo.2, add the line:
 296
 297         MAN2=   foo.2
 298
 299 If foo does not have a manual page at all, add the line:
 300
 301         NOMAN=  noman
 302
 303 If foo has multiple source files, add the line:
 304
 305         SRCS=   a.c b.c c.c d.c
 306
 307 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
 308
 309 The include file <bsd.subdir.mk> contains the default targets for building
 310 subdirectories.  It has the same seven targets as <bsd.prog.mk>: all, clean,
 311 cleandir, depend, install, lint, and tags.  For all of the directories
 312 listed in the variable SUBDIRS, the specified directory will be visited
 313 and the target made.  There is also a default target which allows the
 314 command "make subdir" where subdir is any directory listed in the variable
 315 SUBDIRS.
 316
 317 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
 318
 319 The include file <bsd.lib.mk> has support for building libraries.  It has
 320 the same seven targets as <bsd.prog.mk>: all, clean, cleandir, depend,
 321 install, lint, and tags.  It has a limited number of suffixes, consistent
 322 with the current needs of the BSD tree.
 323
 324 It sets/uses the following variables:
 325
 326 LIBDIR          Target directory for libraries.
 327
 328 LINTLIBDIR      Target directory for lint libraries.
 329
 330 LIBGRP          Library group.
 331
 332 LIBOWN          Library owner.
 333
 334 LIBMODE         Library mode.
 335
 336 LDADD           Additional loader objects.
 337
 338 MAN             The manual pages to be installed (use a .1 - .9 suffix).
 339
 340 SRCS            List of source files to build the library.  Suffix types
 341                 .s, .c, and .f are supported.  Note, .s files are preferred
 342                 to .c files of the same name.  (This is not the default for
 343                 versions of make.)
 344
 345 The include file <bsd.lib.mk> includes the file named "../Makefile.inc"
 346 if it exists, as well as the include file <bsd.man.mk>.
 347
 348 It has rules for building profiled objects; profiled libraries are
 349 built by default.
 350
 351 Libraries are ranlib'd before installation.