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