contrib/bmake/mk/README

   1 #       $Id: README,v 1.1 1997/03/11 07:27:15 sjg Exp $
   2
   3 This directory contains some macro's derrived from the NetBSD bsd.*.mk
   4 macros.  They have the same names but without the bsd., separate macro
   5 files are needed to ensure we can make them do what we want for
   6 builing things outside of /usr/src.  Nearly all the comments below
   7 apply.
   8
   9 #       $NetBSD: bsd.README,v 1.18 1997/01/13 00:54:23 mark Exp $
  10 #       @(#)bsd.README  5.1 (Berkeley) 5/11/90
  11
  12 This is the README file for the new make "include" files for the BSD
  13 source tree.  The files are installed in /usr/share/mk, and are, by
  14 convention, named with the suffix ".mk".
  15
  16 Note, this file is not intended to replace reading through the .mk
  17 files for anything tricky.
  18
  19 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
  20
  21 RANDOM THINGS WORTH KNOWING:
  22
  23 The files are simply C-style #include files, and pretty much behave like
  24 you'd expect.  The syntax is slightly different in that a single '.' is
  25 used instead of the hash mark, i.e. ".include <bsd.prog.mk>".
  26
  27 One difference that will save you lots of debugging time is that inclusion
  28 of the file is normally done at the *end* of the Makefile.  The reason for
  29 this is because .mk files often modify variables and behavior based on the
  30 values of variables set in the Makefile.  To make this work, remember that
  31 the FIRST target found is the target that is used, i.e. if the Makefile has:
  32
  33         a:
  34                 echo a
  35         a:
  36                 echo a number two
  37
  38 the command "make a" will echo "a".  To make things confusing, the SECOND
  39 variable assignment is the overriding one, i.e. if the Makefile has:
  40
  41         a=      foo
  42         a=      bar
  43
  44         b:
  45                 echo ${a}
  46
  47 the command "make b" will echo "bar".  This is for compatibility with the
  48 way the V7 make behaved.
  49
  50 It's fairly difficult to make the BSD .mk files work when you're building
  51 multiple programs in a single directory.  It's a lot easier split up the
  52 programs than to deal with the problem.  Most of the agony comes from making
  53 the "obj" directory stuff work right, not because we switch to a new version
  54 of make.  So, don't get mad at us, figure out a better way to handle multiple
  55 architectures so we can quit using the symbolic link stuff.  (Imake doesn't
  56 count.)
  57
  58 The file .depend in the source directory is expected to contain dependencies
  59 for the source files.  This file is read automatically by make after reading
  60 the Makefile.
  61
  62 The variable DESTDIR works as before.  It's not set anywhere but will change
  63 the tree where the file gets installed.
  64
  65 The profiled libraries are no longer built in a different directory than
  66 the regular libraries.  A new suffix, ".po", is used to denote a profiled
  67 object.
  68
  69 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
  70
  71 The include file <sys.mk> has the default rules for all makes, in the BSD
  72 environment or otherwise.  You probably don't want to touch this file.
  73
  74 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
  75
  76 The include file <bsd.man.mk> handles installing manual pages and their
  77 links.
  78
  79 It has a single target:
  80
  81         maninstall:
  82                 Install the manual pages and their links.
  83
  84 It sets/uses the following variables:
  85
  86 MANDIR          Base path for manual installation.
  87
  88 MANGRP          Manual group.
  89
  90 MANOWN          Manual owner.
  91
  92 MANMODE         Manual mode.
  93
  94 MANSUBDIR       Subdirectory under the manual page section, i.e. "/vax"
  95                 or "/tahoe" for machine specific manual pages.
  96
  97 MAN             The manual pages to be installed (use a .1 - .9 suffix).
  98
  99 MLINKS          List of manual page links (using a .1 - .9 suffix).  The
 100                 linked-to file must come first, the linked file second,
 101                 and there may be multiple pairs.  The files are soft-linked.
 102
 103 The include file <bsd.man.mk> includes a file named "../Makefile.inc" if
 104 it exists.
 105
 106 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
 107
 108 The include file <bsd.own.mk> contains source tree configuration parameters,
 109 such as the owners, groups, etc. for both manual pages and binaries, and
 110 a few global "feature configuration" parameters.
 111
 112 It has no targets.
 113
 114 To get system-specific configuration parameters, bsd.own.mk will try to
 115 include the file specified by the "MAKECONF" variable.  If MAKECONF is not
 116 set, or no such file exists, the system make configuration file, /etc/mk.conf
 117 is included.  These files may define any of the variables described below.
 118
 119 bsd.own.mk sets the following variables, if they are not already defined
 120 (defaults are in brackets):
 121
 122 BSDSRCDIR       The real path to the system sources, so that 'make obj'
 123                 will work correctly. [/usr/src]
 124
 125 BSDOBJDIR       The real path to the system 'obj' tree, so that 'make obj'
 126                 will work correctly. [/usr/obj]
 127
 128 BINGRP          Binary group. [bin]
 129
 130 BINOWN          Binary owner. [bin]
 131
 132 BINMODE         Binary mode. [555]
 133
 134 NONBINMODE      Mode for non-executable files. [444]
 135
 136 MANDIR          Base path for manual installation. [/usr/share/man/cat]
 137
 138 MANGRP          Manual group. [bin]
 139
 140 MANOWN          Manual owner. [bin]
 141
 142 MANMODE         Manual mode. [${NONBINMODE}]
 143
 144 LIBDIR          Base path for library installation. [/usr/lib]
 145
 146 LINTLIBDIR      Base path for lint(1) library installation. [/usr/libdata/lint]
 147
 148 LIBGRP          Library group. [${BINGRP}]
 149
 150 LIBOWN          Library owner. [${BINOWN}]
 151
 152 LIBMODE         Library mode. [${NONBINMODE}]
 153
 154 DOCDIR          Base path for system documentation (e.g. PSD, USD, etc.)
 155                 installation. [/usr/share/doc]
 156
 157 DOCGRP          Documentation group. [bin]
 158
 159 DOCOWN          Documentation owner. [bin]
 160
 161 DOCMODE         Documentation mode. [${NONBINMODE}]
 162
 163 NLSDIR          Base path for National Language Support files installation.
 164                 [/usr/share/nls]
 165
 166 NLSGRP          National Language Support files group. [bin]
 167
 168 NLSOWN          National Language Support files owner. [bin]
 169
 170 NLSMODE         National Language Support files mode. [${NONBINMODE}]
 171
 172 STRIP           The flag passed to the install program to cause the binary
 173                 to be stripped.  This is to be used when building your
 174                 own install script so that the entire system can be made
 175                 stripped/not-stripped using a single knob. [-s]
 176
 177 COPY            The flag passed to the install program to cause the binary
 178                 to be copied rather than moved.  This is to be used when
 179                 building our own install script so that the entire system
 180                 can either be installed with copies, or with moves using
 181                 a single knob. [-c]
 182
 183 Additionally, the following variables may be set by bsd.own.mk or in a
 184 make configuration file to modify the behaviour of the system build
 185 process (default values are in brackets along with comments, if set by
 186 bsd.own.mk):
 187
 188 EXPORTABLE_SYSTEM
 189                 Do not build /usr/src/domestic, even if it is present.
 190
 191 SKEY            Compile in support for S/key authentication. [yes, set
 192                 unconditionally]
 193
 194 KERBEROS        Compile in support for Kerberos 4 authentication.
 195
 196 KERBEROS5       Compile in support for Kerberos 5 authentication.
 197
 198 MANZ            Compress manual pages at installation time.
 199
 200 SYS_INCLUDE     Copy or symlink kernel include files into /usr/include.
 201                 Possible values are "symlinks" or "copies" (which is
 202                 the same as the variable being unset).
 203
 204 NOPROFILE       Do not build profiled versions of system libraries
 205
 206 NOPIC           Do not build PIC versions of system libraries, and
 207                 do not build shared libraries.  [set if ${MACHINE_ARCH}
 208                 is "mips", "vax", "alpha" or "arm32", unset otherwise.]
 209
 210 NOLINT          Do not build lint libraries. [set, set unconditionally]
 211
 212 bsd.own.mk is generally useful when building your own Makefiles so that
 213 they use the same default owners etc. as the rest of the tree.
 214
 215 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
 216
 217 The include file <bsd.prog.mk> handles building programs from one or
 218 more source files, along with their manual pages.  It has a limited number
 219 of suffixes, consistent with the current needs of the BSD tree.
 220
 221 It has eight targets:
 222
 223         all:
 224                 build the program and its manual page
 225         clean:
 226                 remove the program, any object files and the files a.out,
 227                 Errs, errs, mklog, and core.
 228         cleandir:
 229                 remove all of the files removed by the target clean, as
 230                 well as .depend, tags, and any manual pages.
 231         depend:
 232                 make the dependencies for the source files, and store
 233                 them in the file .depend.
 234         includes:
 235                 install any header files.
 236         install:
 237                 install the program and its manual pages; if the Makefile
 238                 does not itself define the target install, the targets
 239                 beforeinstall and afterinstall may also be used to cause
 240                 actions immediately before and after the install target
 241                 is executed.
 242         lint:
 243                 run lint on the source files
 244         tags:
 245                 create a tags file for the source files.
 246
 247 It sets/uses the following variables:
 248
 249 BINGRP          Binary group.
 250
 251 BINOWN          Binary owner.
 252
 253 BINMODE         Binary mode.
 254
 255 CLEANFILES      Additional files to remove for the clean and cleandir targets.
 256
 257 COPTS           Additional flags to the compiler when creating C objects.
 258
 259 HIDEGAME        If HIDEGAME is defined, the binary is installed in
 260                 /usr/games/hide, and a symbolic link is created to
 261                 /usr/games/dm.
 262
 263 LDADD           Additional loader objects.  Usually used for libraries.
 264                 For example, to load with the compatibility and utility
 265                 libraries, use:
 266
 267                         LDADD+=-lutil -lcompat
 268
 269 LDFLAGS         Additional loader flags.
 270
 271 LINKS           The list of binary links; should be full pathnames, the
 272                 linked-to file coming first, followed by the linked
 273                 file.  The files are hard-linked.  For example, to link
 274                 /bin/test and /bin/[, use:
 275
 276                         LINKS=  ${DESTDIR}/bin/test ${DESTDIR}/bin/[
 277
 278 MAN             Manual pages (should end in .1 - .9).  If no MAN variable is
 279                 defined, "MAN=${PROG}.1" is assumed.
 280
 281 PROG            The name of the program to build.  If not supplied, nothing
 282                 is built.
 283
 284 SRCS            List of source files to build the program.  If PROG is not
 285                 defined, it's assumed to be ${PROG}.c.
 286
 287 DPADD           Additional dependencies for the program.  Usually used for
 288                 libraries.  For example, to depend on the compatibility and
 289                 utility libraries use:
 290
 291                         DPADD+=${LIBCOMPAT} ${LIBUTIL}
 292
 293                 The following libraries are predefined for DPADD:
 294
 295                         LIBC            /lib/libc.a
 296                         LIBCOMPAT       /usr/lib/libcompat.a
 297                         LIBCRYPT        /usr/lib/libcrypt.a
 298                         LIBCURSES       /usr/lib/libcurses.a
 299                         LIBDBM          /usr/lib/libdbm.a
 300                         LIBDES          /usr/lib/libdes.a
 301                         LIBL            /usr/lib/libl.a
 302                         LIBKDB          /usr/lib/libkdb.a
 303                         LIBKRB          /usr/lib/libkrb.a
 304                         LIBKVM          /usr/lib/libkvm.a
 305                         LIBM            /usr/lib/libm.a
 306                         LIBMP           /usr/lib/libmp.a
 307                         LIBPC           /usr/lib/libpc.a
 308                         LIBPLOT         /usr/lib/libplot.a
 309                         LIBRPC          /usr/lib/sunrpc.a
 310                         LIBTERM         /usr/lib/libterm.a
 311                         LIBUTIL         /usr/lib/libutil.a
 312
 313 SHAREDSTRINGS   If defined, a new .c.o rule is used that results in shared
 314                 strings, using xstr(1). Note that this will not work with
 315                 parallel makes.
 316
 317 STRIP           The flag passed to the install program to cause the binary
 318                 to be stripped.
 319
 320 SUBDIR          A list of subdirectories that should be built as well.
 321                 Each of the targets will execute the same target in the
 322                 subdirectories.
 323
 324 The include file <bsd.prog.mk> includes the file named "../Makefile.inc"
 325 if it exists, as well as the include file <bsd.man.mk>.
 326
 327 Some simple examples:
 328
 329 To build foo from foo.c with a manual page foo.1, use:
 330
 331         PROG=   foo
 332
 333         .include <bsd.prog.mk>
 334
 335 To build foo from foo.c with a manual page foo.2, add the line:
 336
 337         MAN=    foo.2
 338
 339 If foo does not have a manual page at all, add the line:
 340
 341         NOMAN=  noman
 342
 343 If foo has multiple source files, add the line:
 344
 345         SRCS=   a.c b.c c.c d.c
 346
 347 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
 348
 349 The include file <bsd.subdir.mk> contains the default targets for building
 350 subdirectories.  It has the same eight targets as <bsd.prog.mk>: all,
 351 clean, cleandir, depend, includes, install, lint, and tags.  For all of
 352 the directories listed in the variable SUBDIRS, the specified directory
 353 will be visited and the target made.  There is also a default target which
 354 allows the command "make subdir" where subdir is any directory listed in
 355 the variable SUBDIRS.
 356
 357 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
 358
 359 The include file <bsd.sys.mk> is used by <bsd.prog.mk> and
 360 <bsd.lib.mk>.  It contains overrides that are used when building
 361 the NetBSD source tree.  For instance, if "PARALLEL" is defined by
 362 the program/library Makefile, it includes a set of rules for lex and
 363 yacc that allow multiple lex and yacc targets to be built in parallel.
 364
 365 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
 366
 367 The include file <bsd.lib.mk> has support for building libraries.  It has
 368 the same eight targets as <bsd.prog.mk>: all, clean, cleandir, depend,
 369 includes, install, lint, and tags.  It has a limited number of suffixes,
 370 consistent with the current needs of the BSD tree.
 371
 372 It sets/uses the following variables:
 373
 374 LIB             The name of the library to build.
 375
 376 LIBDIR          Target directory for libraries.
 377
 378 LINTLIBDIR      Target directory for lint libraries.
 379
 380 LIBGRP          Library group.
 381
 382 LIBOWN          Library owner.
 383
 384 LIBMODE         Library mode.
 385
 386 LDADD           Additional loader objects.
 387
 388 MAN             The manual pages to be installed (use a .1 - .9 suffix).
 389
 390 SRCS            List of source files to build the library.  Suffix types
 391                 .s, .c, and .f are supported.  Note, .s files are preferred
 392                 to .c files of the same name.  (This is not the default for
 393                 versions of make.)
 394
 395 The include file <bsd.lib.mk> includes the file named "../Makefile.inc"
 396 if it exists, as well as the include file <bsd.man.mk>.
 397
 398 It has rules for building profiled objects; profiled libraries are
 399 built by default.
 400
 401 Libraries are ranlib'd when made.