share/mk/bsd.README

   1 #       @(#)bsd.README  8.2 (Berkeley) 4/2/94
   2 # $FreeBSD$
   3
   4 This is the README file for the "include" files for the FreeBSD
   5 source tree.  The files are installed in /usr/share/mk, and are by
   6 convention, named with the suffix ".mk".  These files store several
   7 build options and should be handled with caution.
   8
   9 Note, this file is not intended to replace reading through the .mk
  10 files for anything tricky.
  11
  12 There are two main types of make include files.  One type is the generally
  13 usable make include files, such as bsd.prog.mk and bsd.lib.mk.  The other is
  14 the internal make include files, such as bsd.files.mk and bsd.man.mk, which
  15 can not/should not be used directly but are used by the other make include
  16 files.  In most cases it is only interesting to include bsd.prog.mk or
  17 bsd.lib.mk.
  18
  19 bsd.arch.inc.mk         - includes arch-specific Makefile.$arch
  20 bsd.compiler.mk         - defined based on current compiler
  21 bsd.cpu.mk              - sets CPU/arch-related variables (included from sys.mk)
  22 bsd.dep.mk              - handle Makefile dependencies
  23 bsd.doc.mk              - building troff system documents
  24 bsd.files.mk            - install of general purpose files
  25 bsd.incs.mk             - install of include files
  26 bsd.info.mk             - building GNU Info hypertext system (deprecated)
  27 bsd.init.mk             - initialization for the make include files
  28 bsd.kmod.mk             - building loadable kernel modules
  29 bsd.lib.mk              - support for building libraries
  30 bsd.libnames.mk         - define library names
  31 bsd.links.mk            - install of links (sym/hard)
  32 bsd.man.mk              - install of manual pages and their links
  33 bsd.nls.mk              - build and install of NLS catalogs
  34 bsd.obj.mk              - creating 'obj' directories and cleaning up
  35 bsd.own.mk              - define common variables
  36 bsd.port.mk             - building ports
  37 bsd.port.post.mk        - building ports
  38 bsd.port.pre.mk         - building ports
  39 bsd.port.subdir.mk      - targets for building subdirectories for ports
  40 bsd.prog.mk             - building programs from source files
  41 bsd.progs.mk            - build multiple programs from sources (deprecated)
  42 bsd.snmpmod.mk          - building modules for the SNMP daemon bsnmpd
  43 bsd.subdir.mk           - targets for building subdirectories
  44 bsd.sys.mk              - common settings used for building FreeBSD sources
  45 bsd.test.mk             - building test programs from source files
  46 sys.mk                  - default rules for all makes
  47
  48 This file does not document bsd.port*.mk.  They are documented in ports(7).
  49
  50 See also make(1), mkdep(1), style.Makefile(5) and `PMake - A
  51 Tutorial', located in /usr/share/doc/psd/12.make.
  52
  53 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
  54
  55 Random things worth knowing about this document:
  56
  57 If appropriate when documenting the variables the default value is
  58 indicated using square brackets e.g. [gzip].
  59 In some cases the default value depend on other values (e.g. system
  60 architecture).  In these cases the most common value is indicated.
  61
  62 This document contains some simple examples of the usage of the BSD make
  63 include files.  For more examples look at the makefiles in the FreeBSD
  64 source tree.
  65
  66 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
  67
  68 RANDOM THINGS WORTH KNOWING:
  69
  70 The files are like C-style #include files, and pretty much behave like
  71 you'd expect.  The syntax is slightly different in that a single '.' is
  72 used instead of the hash mark, i.e. ".include <bsd.prog.mk>".
  73
  74 One difference that will save you lots of debugging time is that inclusion
  75 of the file is normally done at the *end* of the Makefile.  The reason for
  76 this is because .mk files often modify variables and behavior based on the
  77 values of variables set in the Makefile.  To make this work, remember that
  78 the FIRST target found is the target that is used, i.e. if the Makefile has:
  79
  80         a:
  81                 echo a
  82         a:
  83                 echo a number two
  84
  85 the command "make a" will echo "a".  To make things confusing, the SECOND
  86 variable assignment is the overriding one, i.e. if the Makefile has:
  87
  88         a=      foo
  89         a=      bar
  90
  91         b:
  92                 echo ${a}
  93
  94 the command "make b" will echo "bar".  This is for compatibility with the
  95 way the V7 make behaved.
  96
  97 It's fairly difficult to make the BSD .mk files work when you're building
  98 multiple programs in a single directory.  It's a lot easier to split up
  99 the programs than to deal with the problem.  Most of the agony comes from
 100 making the "obj" directory stuff work right, not because we switch to a new
 101 version of make.  So, don't get mad at us, figure out a better way to handle
 102 multiple architectures so we can quit using the symbolic link stuff.
 103 (Imake doesn't count.)
 104
 105 The file .depend in the source directory is expected to contain dependencies
 106 for the source files.  This file is read automatically by make after reading
 107 the Makefile.
 108
 109 The variable DESTDIR works as before.  It's not set anywhere but will change
 110 the tree where the file gets installed.
 111
 112 The profiled libraries are no longer built in a different directory than
 113 the regular libraries.  A new suffix, ".po", is used to denote a profiled
 114 object.
 115
 116 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
 117
 118 The following variables are common:
 119
 120 CFLAGS.${COMPILER_TYPE}
 121                 Flags dependent on compiler added to CXXFLAGS.
 122 CFLAGS.${MACHINE_ARCH}
 123                 Architectural flags added to CFLAGS.
 124 CFLAGS_NO_SIMD  Add this to CFLAGS for programs that don't want any SIMD
 125                 instructions generated. It is setup in bsd.cpu.mk to an
 126                 appropriate value for the compiler and target.
 127 CXXFLAGS.${COMPILER_TYPE}
 128                 Flags dependent on compiler added to CXXFLAGS.
 129 CXXFLAGS.${MACHINE_ARCH}
 130                 Architectural flags added to CXXFLAGS.
 131 COMPILER_FEATURES
 132                 A list of features that the compiler supports. Zero or
 133                 more of:
 134                         c++11   Supports full C++ 11 standard.
 135
 136 COMPILER_TYPE   Type of compiler, either clang or gcc, though other
 137                 values are possible. Don't assume != clang == gcc.
 138
 139 COMPILER_VERSION
 140                 A numeric constant equal to:
 141                      major * 10000 + minor * 100 + tiny
 142                 for the compiler's self-reported version.
 143
 144 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
 145
 146 The include file <sys.mk> has the default rules for all makes, in the BSD
 147 environment or otherwise.  You probably don't want to touch this file.
 148
 149 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
 150
 151 The include file <bsd.arch.inc.mk> includes other Makefiles for specific
 152 architectures, if they exist. It will include the first of the following
 153 files that it finds: Makefile.${MACHINE}, Makefile.${MACHINE_ARCH},
 154 Makefile.${MACHINE_CPUARCH}
 155
 156 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
 157
 158 The include file <bsd.man.mk> handles installing manual pages and their
 159 links.
 160
 161 It has three targets:
 162
 163         all-man:
 164                 build manual pages.
 165         maninstall:
 166                 install the manual pages and their links.
 167         manlint:
 168                 verify the validity of manual pages.
 169
 170 It sets/uses the following variables:
 171
 172 MANDIR          Base path for manual installation.
 173
 174 MANGRP          Manual group.
 175
 176 MANOWN          Manual owner.
 177
 178 MANMODE         Manual mode.
 179
 180 MANSUBDIR       Subdirectory under the manual page section, i.e. "/vax"
 181                 or "/tahoe" for machine specific manual pages.
 182
 183 MAN             The manual pages to be installed (use a .1 - .9 suffix).
 184
 185 MLINKS          List of manual page links (using a .1 - .9 suffix).  The
 186                 linked-to file must come first, the linked file second,
 187                 and there may be multiple pairs.  The files are hard-linked.
 188
 189 The include file <bsd.man.mk> includes a file named "../Makefile.inc" if
 190 it exists.
 191
 192 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
 193
 194 The include file <bsd.own.mk> contains the owners, groups, etc. for both
 195 manual pages and binaries.
 196
 197 It has no targets.
 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 MANDIR          Base path for manual installation.
 208
 209 MANGRP          Manual group.
 210
 211 MANOWN          Manual owner.
 212
 213 MANMODE         Manual mode.
 214
 215 This file is generally useful when building your own Makefiles so that
 216 they use the same default owners etc. as the rest of the tree.
 217
 218 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
 219
 220 The include file <bsd.prog.mk> handles building programs from one or
 221 more source files, along with their manual pages.  It has a limited number
 222 of suffixes, consistent with the current needs of the BSD tree.
 223
 224 It has seven targets:
 225
 226         all:
 227                 build the program and its manual page
 228         clean:
 229                 remove the program and any object files.
 230         cleandir:
 231                 remove all of the files removed by the target clean, as
 232                 well as .depend, tags, and any manual pages.
 233         depend:
 234                 make the dependencies for the source files, and store
 235                 them in the file .depend.
 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 and
 256 CLEANDIRS       additional directories to remove during clean and cleandir
 257                 targets.  "rm -f" and "rm -rf" used respectively.
 258
 259 CFLAGS          Flags to the compiler when creating C objects.
 260
 261 FILES           A list of non-executable files.
 262                 The installation is controlled by the FILESNAME, FILESOWN,
 263                 FILESGRP, FILESMODE, FILESDIR variables that can be
 264                 further specialized by FILES<VAR>_<file>.
 265
 266 LDADD           Additional loader objects.  Usually used for libraries.
 267                 For example, to load with the compatibility and utility
 268                 libraries, use:
 269
 270                         LDADD=-lutil -lcompat
 271
 272 LDFLAGS         Additional loader flags. Passed to the loader via CC,
 273                 since that's used to link programs as well, so loader
 274                 specific flags need to be prefixed with -Wl, to work.
 275
 276 LINKS           The list of binary links; should be full pathnames, the
 277                 linked-to file coming first, followed by the linked
 278                 file.  The files are hard-linked.  For example, to link
 279                 /bin/test and /bin/[, use:
 280
 281                         LINKS=  ${DESTDIR}/bin/test ${DESTDIR}/bin/[
 282
 283 MAN             Manual pages (should end in .1 - .9).  If no MAN variable
 284                 is defined, "MAN=${PROG}.1" is assumed.
 285
 286 PROG            The name of the program to build.  If not supplied, nothing
 287                 is built.
 288
 289 PROG_CXX        If defined, the name of the program to build.  Also
 290                 causes <bsd.prog.mk> to link the program with the
 291                 standard C++ library.  PROG_CXX overrides the value
 292                 of PROG if PROG is also set.
 293
 294 PROGNAME        The name that the above program will be installed as, if
 295                 different from ${PROG}.
 296
 297 SRCS            List of source files to build the program.  If SRCS is not
 298                 defined, it's assumed to be ${PROG}.c or, if PROG_CXX is
 299                 defined, ${PROG_CXX}.cc.
 300
 301 DPADD           Additional dependencies for the program.  Usually used for
 302                 libraries.  For example, to depend on the compatibility and
 303                 utility libraries use:
 304
 305                         DPADD=${LIBCOMPAT} ${LIBUTIL}
 306
 307                 There is a predefined identifier for each (non-profiled,
 308                 non-shared) library and object.  Library file names are
 309                 transformed to identifiers by removing the extension and
 310                 converting to upper case.
 311
 312                 There are no special identifiers for profiled or shared
 313                 libraries or objects.  The identifiers for the standard
 314                 libraries are used in DPADD.  This works correctly iff all
 315                 the libraries are built at the same time.  Unfortunately,
 316                 it causes unnecessary relinks to shared libraries when
 317                 only the static libraries have changed.  Dependencies on
 318                 shared libraries should be only on the library version
 319                 numbers.
 320
 321 STRIP           The flag passed to the install program to cause the binary
 322                 to be stripped.  This is to be used when building your
 323                 own install script so that the entire system can be made
 324                 stripped/not-stripped using a single nob.
 325
 326 SUBDIR          A list of subdirectories that should be built as well.
 327                 Each of the targets will execute the same target in the
 328                 subdirectories.
 329
 330 SCRIPTS         A list of interpreter scripts [file.{sh,csh,pl,awk,...}].
 331                 The installation is controlled by the SCRIPTSNAME, SCRIPTSOWN,
 332                 SCRIPTSGRP, SCRIPTSMODE, SCRIPTSDIR variables that can be
 333                 further specialized by SCRIPTS<VAR>_<script>.
 334
 335 The include file <bsd.prog.mk> includes the file named "../Makefile.inc"
 336 if it exists, as well as the include file <bsd.man.mk>.
 337
 338 Some simple examples:
 339
 340 To build foo from foo.c with a manual page foo.1, use:
 341
 342         PROG=   foo
 343
 344         .include <bsd.prog.mk>
 345
 346 To build foo from foo.c with a manual page foo.2, add the line:
 347
 348         MAN=    foo.2
 349
 350 If foo does not have a manual page at all, add the line:
 351
 352         MAN=
 353
 354 If foo has multiple source files, add the line:
 355
 356         SRCS=   a.c b.c c.c d.c
 357
 358 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
 359
 360 The include file <bsd.subdir.mk> contains the default targets for building
 361 subdirectories.  It has the same seven targets as <bsd.prog.mk>: all, clean,
 362 cleandir, depend, install, lint, and tags.  For all of the directories
 363 listed in the variable SUBDIRS, the specified directory will be visited
 364 and the target made.  There is also a default target which allows the
 365 command "make subdir" where subdir is any directory listed in the variable
 366 SUBDIRS.
 367
 368 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
 369
 370 The include file <bsd.lib.mk> has support for building libraries.  It has
 371 the same seven targets as <bsd.prog.mk>: all, clean, cleandir, depend,
 372 install, lint, and tags.  It has a limited number of suffixes, consistent
 373 with the current needs of the BSD tree.
 374
 375 It sets/uses the following variables:
 376
 377 LIB             The name of the library to build.
 378
 379 LIB_CXX         The name of the library to build. It also causes
 380                 <bsd.lib.mk> to link the library with the
 381                 standard C++ library.  LIB_CXX overrides the value
 382                 of LIB if LIB is also set.
 383
 384 LIBDIR          Target directory for libraries.
 385
 386 LINTLIBDIR      Target directory for lint libraries.
 387
 388 LIBGRP          Library group.
 389
 390 LIBOWN          Library owner.
 391
 392 LIBMODE         Library mode.
 393
 394 LDADD           Additional loader objects.
 395
 396 MAN             The manual pages to be installed (use a .1 - .9 suffix).
 397
 398 SRCS            List of source files to build the library.  Suffix types
 399                 .s, .c, and .f are supported.  Note, .s files are preferred
 400                 to .c files of the same name.  (This is not the default for
 401                 versions of make.)
 402
 403 SHLIB_LDSCRIPT  Template file to generate shared library linker script.
 404                 Unless used, a simple symlink is created to the real
 405                 shared object.
 406
 407 LIBRARIES_ONLY  Do not build or install files other than the library.
 408
 409 The include file <bsd.lib.mk> includes the file named "../Makefile.inc"
 410 if it exists, as well as the include file <bsd.man.mk>.
 411
 412 It has rules for building profiled objects; profiled libraries are
 413 built by default.
 414
 415 Libraries are ranlib'd before installation.
 416
 417 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
 418
 419 The include file <bsd.test.mk> handles building one or more test programs
 420 intended to be used in the FreeBSD Test Suite under /usr/tests/.
 421
 422 It has seven targets:
 423
 424         all:
 425                 build the test programs.
 426         clean:
 427                 remove the test programs and any object files.
 428         cleandir:
 429                 remove all of the files removed by the target clean, as
 430                 well as .depend and tags.
 431         depend:
 432                 make the dependencies for the source files, and store
 433                 them in the file .depend.
 434         install:
 435                 install the test programs and their data files; if the
 436                 Makefile does not itself define the target install, the
 437                 targets beforeinstall and afterinstall may also be used
 438                 to cause actions immediately before and after the
 439                 install target is executed.
 440         lint:
 441                 run lint on the source files.
 442         tags:
 443                 create a tags file for the source files.
 444         test:
 445                 runs the test programs from the object directory; if the
 446                 Makefile does not itself define the target test, the
 447                 targets beforetest and aftertest may also be used to
 448                 cause actions immediately before and after the test
 449                 target is executed.
 450
 451 It sets/uses the following variables, among many others:
 452
 453 TESTDIR         Path to the installed tests.  Must be a subdirectory of
 454                 TESTSBASE and the subpath should match the relative
 455                 location of the tests within the src tree.
 456
 457 KYUAFILE        If 'auto' (the default), generate a Kyuafile out of the
 458                 test programs defined in the Makefile.  If 'yes', then a
 459                 manually-crafted Kyuafile must be supplied with the
 460                 sources.  If 'no', no Kyuafile is installed (useful for
 461                 subdirectories providing helper programs or data files
 462                 only).
 463
 464 ATF_TESTS_C     The names of the ATF C test programs to build.
 465
 466 ATF_TESTS_CXX   The names of the ATF C++ test programs to build.
 467
 468 ATF_TESTS_SH    The names of the ATF sh test programs to build.
 469
 470 PLAIN_TESTS_C   The names of the plain (legacy) programs to build.
 471
 472 PLAIN_TESTS_CXX The names of the plain (legacy) test programs to build.
 473
 474 PLAIN_TESTS_SH  The names of the plain (legacy) test programs to build.
 475
 476 TAP_PERL_INTERPRETER
 477                 Path to the Perl interpreter to be used for
 478                 TAP-compliant test programs that are written in Perl.
 479                 Refer to TAP_TESTS_PERL for details.
 480
 481 TAP_TESTS_C     The names of the TAP-compliant C test programs to build.
 482
 483 TAP_TESTS_CXX   The names of the TAP-compliant C++ test programs to
 484                 build.
 485
 486 TAP_TESTS_PERL  The names of the TAP-compliant Perl test programs to
 487                 build.  The corresponding source files should end with
 488                 the .pl extension; the test program is marked as
 489                 requiring Perl; and TAP_PERL_INTERPRETER is used in the
 490                 built scripts as the interpreter of choice.
 491
 492 TAP_TESTS_SH    The names of the TAP-compliant sh test programs to
 493                 build.
 494
 495 TESTS_SUBDIRS   List of subdirectories containing tests into which to
 496                 recurse.  Differs from SUBDIR in that these directories
 497                 get registered into the automatically-generated
 498                 Kyuafile (if any).
 499
 500 NOT_FOR_TEST_SUITE
 501                 If defined, none of the built test programs get
 502                 installed under /usr/tests/ and no Kyuafile is
 503                 automatically generated.  Should not be used within the
 504                 FreeBSD source tree but is provided for the benefit of
 505                 third-parties.
 506
 507 The actual building of the test programs is performed by <bsd.prog.mk>.
 508 Please see the documentation above for this other file for additional
 509 details on the behavior of <bsd.test.mk>.