[BACK]Return to BUILDING.mdoc CVS log [TXT][DIR] Up to [cvs.NetBSD.org] / src / doc

Annotation of src/doc/BUILDING.mdoc, Revision 1.107

1.107   ! apb         1: .\"    $NetBSD: BUILDING.mdoc,v 1.106 2014/11/06 06:41:23 uebayasi Exp $
1.1       lukem       2: .\"
1.82      apb         3: .\" Copyright (c) 2001-2011 The NetBSD Foundation, Inc.
1.1       lukem       4: .\" All rights reserved.
                      5: .\"
                      6: .\" This code is derived from software contributed to The NetBSD Foundation
1.9       lukem       7: .\" by Todd Vierling and Luke Mewburn.
1.1       lukem       8: .\"
                      9: .\" Redistribution and use in source and binary forms, with or without
                     10: .\" modification, are permitted provided that the following conditions
                     11: .\" are met:
                     12: .\" 1. Redistributions of source code must retain the above copyright
                     13: .\"    notice, this list of conditions and the following disclaimer.
                     14: .\" 2. Redistributions in binary form must reproduce the above copyright
                     15: .\"    notice, this list of conditions and the following disclaimer in the
                     16: .\"    documentation and/or other materials provided with the distribution.
                     17: .\"
                     18: .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
                     19: .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
                     20: .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
                     21: .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
                     22: .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
                     23: .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
                     24: .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
                     25: .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
                     26: .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
                     27: .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
                     28: .\" POSSIBILITY OF SUCH DAMAGE.
                     29: .\"
1.84      apb        30: .\" NOTE: After changing this file, run "make regen" in the src/doc
                     31: .\" directory, and check in both src/BUILDING and src/doc/BUILDING.mdoc.
1.1       lukem      32: .\"
1.13      lukem      33: .\" Toolchain prefix for commands
                     34: .ds toolprefix nb
                     35: .
1.103     apb        36: .Dd August 7, 2014
1.1       lukem      37: .Dt BUILDING 8
                     38: .Os NetBSD
                     39: .
                     40: .Sh NAME
                     41: .
                     42: .Nm BUILDING
                     43: .Nd Procedure for building
                     44: .Nx
                     45: from source code.
                     46: .
                     47: .Sh REQUIREMENTS
                     48: .
                     49: .Nx
                     50: is designed to be buildable on most POSIX-compliant host systems.
                     51: The basic build procedure is the same whether compiling
                     52: .Em natively
                     53: (on the same
                     54: .Nx
                     55: architecture) or
                     56: .Em cross compiling
                     57: (on another architecture or OS).
                     58: .Pp
                     59: This source tree contains a special subtree,
                     60: .Dq tools ,
                     61: which uses the host system to create a build toolchain for the target
1.6       wiz        62: architecture.
                     63: The host system must have at least C and C++
1.1       lukem      64: compilers in order to create the toolchain
                     65: .Nm ( make
                     66: is not required); all other tools are created as part of the
                     67: .Nx
                     68: build process.
1.38      reed       69: (See the environment variables section below if you need
                     70: to override or manually select your compilers.)
1.1       lukem      71: .
                     72: .Sh FILES
                     73: .
                     74: .Ss Source tree layout
                     75: .
                     76: .Bl -tag -width "BUILDING.mdoc"
1.99      wiz        77: .It Pa doc/BUILDING.mdoc
1.1       lukem      78: This document (in -mdoc troff format; the original copy).
1.99      wiz        79: .It Pa BUILDING
1.1       lukem      80: This document (in plaintext).
1.99      wiz        81: .It Pa tools/compat/README
1.33      jmc        82: Special notes for cross-hosting a NetBSD build on non-NetBSD platforms.
1.99      wiz        83: .It Pa Makefile
1.1       lukem      84: The main Makefile for
                     85: .Nx ;
                     86: should only be run for native builds with an appropriately up-to-date
                     87: version of
                     88: .Nx
                     89: .Xr make 1 .
                     90: (For building from out-of-date systems or on a non-native host, see the
                     91: .Nm build.sh
                     92: shell script.)
1.99      wiz        93: .It Pa UPDATING
1.1       lukem      94: Special notes for updating from an earlier revision of
                     95: .Nx .
                     96: It is important to read this file before every build of an updated
                     97: source tree.
1.99      wiz        98: .It Pa build.sh
1.1       lukem      99: Bourne-compatible shell script used for building the host build tools
                    100: and the
                    101: .Nx
1.6       wiz       102: system from scratch.
                    103: Can be used for both native and cross builds, and should be used instead of
1.1       lukem     104: .Xr make 1
                    105: for any source tree that is updated and recompiled regularly.
1.99      wiz       106: .It Pa crypto/dist/ , dist/ , gnu/dist/
1.1       lukem     107: Sources imported verbatim from third parties, without mangling the
1.6       wiz       108: existing build structure.
                    109: Other source trees in
1.1       lukem     110: .Sy bin
                    111: through
                    112: .Sy usr.sbin
                    113: use the
                    114: .Nx
                    115: .Xr make 1
                    116: .Dq reachover
                    117: Makefile semantics when building these programs for a native host.
1.99      wiz       118: .It Pa external , sys/external
1.96      martin    119: Sources and build infrastructure for components imported (mostly) unchanged
                    120: from upstream maintainers, sorted by applicable license.
1.99      wiz       121: This is (slowly) replacing the
                    122: .Pa crypto/dist ,
                    123: .Pa dist ,
                    124: and
                    125: .Pa gnu/dist
                    126: directories.
                    127: .It Pa distrib/ , etc/
1.1       lukem     128: Sources for items used when making a full release snapshot, such as
                    129: files installed in
1.14      lukem     130: .Sy DESTDIR Ns Pa /etc
1.1       lukem     131: on the destination system, boot media, and release notes.
1.99      wiz       132: .It Pa tests/ , regress/
1.6       wiz       133: Regression test harness.
                    134: Can be cross-compiled, but only run natively.
1.57      dholland  135: .Pa tests/
                    136: uses the
                    137: .Xr atf 7
                    138: test framework;
                    139: .Pa regress/
                    140: contains older tests that have not yet been migrated to
                    141: .Xr atf 7 .
1.99      wiz       142: .It Pa sys/
1.1       lukem     143: .Nx
                    144: kernel sources.
1.99      wiz       145: .It Pa tools/
1.1       lukem     146: .Dq Reachover
1.6       wiz       147: build structure for the host build tools.
                    148: This has a special method of determining out-of-date status.
1.99      wiz       149: .It Pa bin/ ... usr.sbin/
1.1       lukem     150: Sources to the
                    151: .Nx
1.6       wiz       152: userland (non-kernel) programs.
                    153: If any of these directories are missing, they will be skipped during the build.
1.99      wiz       154: .It Pa x11/
1.34      lukem     155: .Dq Reachover
                    156: build structure for X11R6; the source is in
                    157: .Sy X11SRCDIR .
1.107   ! apb       158: .It Pa extsrc/
        !           159: .Dq Reachover
        !           160: build structure for externally added programs and libraries;
        !           161: the source is in
        !           162: .Sy EXTSRCSRCDIR .
1.1       lukem     163: .El
                    164: .
                    165: .Ss Build tree layout
                    166: .
                    167: The
                    168: .Nx
                    169: build tree is described in
                    170: .Xr hier 7 ,
                    171: and the release layout is described in
                    172: .Xr release 7 .
                    173: .
                    174: .Sh CONFIGURATION
                    175: .
                    176: .Ss Environment variables
1.94      wiz       177: .
1.1       lukem     178: Several environment variables control the behaviour of
                    179: .Nx
                    180: builds.
                    181: .
                    182: .Bl -tag -width "MAKEOBJDIRPREFIX"
                    183: .
1.38      reed      184: .
1.44      apb       185: .It Sy HOST_SH
1.85      apb       186: Path name to a shell available on the host system
                    187: and suitable for use during the build.
                    188: The
                    189: .Nx
                    190: build system requires a modern Bourne-like shell
                    191: with POSIX-compliant features,
                    192: and also requires support for the
                    193: .Dq local
                    194: keyword to declare local variables in shell functions
                    195: (which is a widely-implemented but non-standardised feature).
                    196: .Pp
                    197: Depending on the host system, a suitable shell may be
                    198: .Pa /bin/sh ,
                    199: .Pa /usr/xpg4/bin/sh ,
                    200: .Pa /bin/ksh
                    201: (provided it is a variant of ksh that supports the
                    202: .Dq local
                    203: keyword,
                    204: such as ksh88, but not ksh93),
                    205: or
                    206: .Pa /usr/local/bin/bash .
                    207: .Pp
                    208: Most parts of the build require
                    209: .Sy HOST_SH
                    210: to be an absolute path; however,
1.44      apb       211: .Nm build.sh
1.85      apb       212: allows it to be a simple command name, which will be converted
                    213: to an absolute path by searching the
1.44      apb       214: .Sy PATH .
                    215: .
1.38      reed      216: .It Sy HOST_CC
                    217: Path name to C compiler used to create the toolchain.
                    218: .
                    219: .It Sy HOST_CXX
                    220: Path name to C++ compiler used to create the toolchain.
                    221: .
1.1       lukem     222: .It Sy MACHINE
1.57      dholland  223: Machine type, e.g.,
                    224: .Dq macppc .
1.1       lukem     225: .
                    226: .It Sy MACHINE_ARCH
1.57      dholland  227: Machine architecture, e.g.,
                    228: .Dq powerpc .
1.1       lukem     229: .
                    230: .It Sy MAKE
                    231: Path name to invoke
                    232: .Xr make 1
                    233: as.
                    234: .
                    235: .It Sy MAKEFLAGS
                    236: Flags to invoke
                    237: .Xr make 1
                    238: with.
1.82      apb       239: Note that
                    240: .Sy build.sh
                    241: ignores the value of
                    242: .Sy MAKEFLAGS
                    243: passed in the environment, but allows
                    244: .Sy MAKEFLAGS
                    245: to be set via the
                    246: .Fl V
                    247: option.
1.1       lukem     248: .
                    249: .It Sy MAKEOBJDIR
                    250: Directory to use as the
                    251: .Sy .OBJDIR
                    252: for the current directory.
1.46      apb       253: The value is subjected to variable expansion by
                    254: .Xr make 1 .
1.61      apb       255: Typical usage is to set this variable to a value involving the use of
                    256: .Sq ${.CURDIR:S...}
                    257: or
                    258: .Sq ${.CURDIR:C...} ,
                    259: to derive the value of
                    260: .Sy .OBJDIR
                    261: from the value of
                    262: .Sy .CURDIR .
1.1       lukem     263: Used only if
                    264: .Sy MAKEOBJDIRPREFIX
                    265: is not defined.
                    266: .Sy MAKEOBJDIR
1.61      apb       267: can be provided only in the environment or via the
1.28      lukem     268: .Fl O
1.23      lukem     269: flag of
1.61      apb       270: .Nm build.sh ;
1.71      mrg       271: it cannot usefully be set inside a Makefile, including
                    272: .Pa mk.conf
                    273: or
                    274: .Sy ${MAKECONF} .
1.1       lukem     275: .
                    276: .It Sy MAKEOBJDIRPREFIX
                    277: Top level directory of the object directory tree.
1.77      apb       278: The value is subjected to variable expansion by
                    279: .Xr make 1 .
                    280: .Sy build.sh
                    281: will create the
                    282: ${MAKEOBJDIRPREFIX}
                    283: directory if necessary, but if
                    284: .Xr make 1
                    285: is used without
                    286: .Sy build.sh ,
                    287: then rules in
                    288: .Aq bsd.obj.mk
                    289: will abort the build if the
                    290: ${MAKEOBJDIRPREFIX}
                    291: directory does not exist.
                    292: If the value is defined and valid, then
1.1       lukem     293: ${MAKEOBJDIRPREFIX}/${.CURDIR}
                    294: is used as the
                    295: .Sy .OBJDIR
                    296: for the current directory.
                    297: The current directory may be read only.
                    298: .Sy MAKEOBJDIRPREFIX
1.61      apb       299: can be provided only in the environment or via the
1.23      lukem     300: .Fl M
                    301: flag of
1.61      apb       302: .Nm build.sh ;
1.91      abs       303: it cannot usefully be set inside a Makefile, including
1.71      mrg       304: .Pa mk.conf
                    305: or
                    306: .Sy ${MAKECONF} .
1.1       lukem     307: .
                    308: .El
                    309: .
                    310: .Ss \*qmake\*q variables
                    311: .
                    312: .de YorN
                    313: Can be set to
                    314: .Dq yes
                    315: or
                    316: .Dq no .
                    317: ..
                    318: .de DFLT
                    319: .Pp
                    320: .Em Default :
                    321: ..
                    322: .de DFLTu
                    323: .DFLT
                    324: Unset.
                    325: ..
                    326: .de DFLTy
                    327: .DFLT
                    328: .Dq yes
                    329: ..
                    330: .de DFLTn
                    331: .DFLT
                    332: .Dq no
                    333: ..
                    334: Several variables control the behavior of
                    335: .Nx
1.6       wiz       336: builds.
                    337: Unless otherwise specified, these variables may be set in
1.1       lukem     338: either the process environment or the
                    339: .Xr make 1
                    340: configuration file specified by
                    341: .Sy MAKECONF .
                    342: .
                    343: .Bl -tag -width "MKCATPAGES"
                    344: .
                    345: .It Sy BUILDID
1.6       wiz       346: Identifier for the build.
1.100     apb       347: If set, this should be a short string that is suitable for use as
                    348: part of a file or directory name.
1.6       wiz       349: The identifier will be appended to
1.1       lukem     350: object directory names, and can be consulted in the
                    351: .Xr make 1
                    352: configuration file in order to set additional build parameters,
                    353: such as compiler flags.
1.100     apb       354: It will also be used as part of the kernel version string,
                    355: which can be printed by
                    356: .Dq Li uname \-v .
                    357: .DFLTu
1.1       lukem     358: .
1.101     apb       359: .It Sy BUILDINFO
                    360: This may be a multi-line string containing information about the build.
                    361: This will appear in
                    362: .Sy DESTDIR Ns Pa /etc/release ,
                    363: and it will be stored in the
                    364: .Va buildinfo
                    365: variable in any kernels that are built.
                    366: When such kernels are booted, the
                    367: .Xr sysctl 7
                    368: .Va kern.buildinfo
                    369: variable will report this value.
                    370: The string may contain backslash escape sequences, such as
                    371: .Dq "\e\e"
                    372: (representing a backslash character)
                    373: and
                    374: .Dq "\en"
                    375: (representing a newline).
                    376: .DFLTu
                    377: .
1.60      perry     378: .It Sy BUILDSEED
                    379: GCC uses random numbers when compiling C++ code.
                    380: This variable seeds the gcc random number generator using
                    381: the -frandom-seed flag with this value.
                    382: By default, it is set to NetBSD-(majorversion).
                    383: Using a fixed value causes C++ binaries to be the same when
1.74      hubertf   384: built from the same sources, resulting in identical (reproducible) builds.
1.60      perry     385: Additional information is available in the GCC
                    386: documentation of -frandom-seed.
                    387: .
1.1       lukem     388: .It Sy DESTDIR
                    389: Directory to contain the built
                    390: .Nx
1.6       wiz       391: system.
                    392: If set, special options are passed to the compilation tools to
1.1       lukem     393: prevent their default use of the host system's
1.99      wiz       394: .Pa /usr/include , /usr/lib ,
1.6       wiz       395: and so forth.
1.46      apb       396: This pathname must be an absolute path, and should
1.1       lukem     397: .Em not
                    398: end with a slash
                    399: .Pq /
1.46      apb       400: character.
                    401: (For installation into the system's root directory, set
1.1       lukem     402: .Sy DESTDIR
1.46      apb       403: to an empty string, not to
                    404: .Dq / ) .
1.1       lukem     405: The directory must reside on a file system which supports long file
                    406: names and hard links.
                    407: .DFLT
                    408: Empty string if
                    409: .Sy USETOOLS
                    410: is
                    411: .Dq yes ;
                    412: unset otherwise.
1.17      lukem     413: .Pp
                    414: .Em Note :
                    415: .Sy build.sh
                    416: will provide a default of
                    417: .Pa destdir. Ns Sy MACHINE
                    418: (in the top-level
                    419: .Sy .OBJDIR )
                    420: unless run in
                    421: .Sq expert
1.57      dholland  422: mode.
1.1       lukem     423: .
1.107   ! apb       424: .It Sy EXTSRCSRCDIR
        !           425: Directory containing sources of externally added programs
        !           426: and libraries.
        !           427: If specified, must be an absolute path.
        !           428: .DFLT
        !           429: .Sy NETBSDRCDIR Ns Pa /../extsrc ,
        !           430: if that exists; otherwise
        !           431: .Pa /usr/extsrc .
        !           432: .
1.1       lukem     433: .It Sy MAKECONF
                    434: The name of the
                    435: .Xr make 1
                    436: configuration file.
                    437: .Em Only settable in the process environment.
                    438: .DFLT
                    439: .Dq /etc/mk.conf
                    440: .
1.30      lukem     441: .It Sy MAKEVERBOSE
                    442: Level of verbosity of status messages.
                    443: Supported values:
                    444: .Bl -tag -width xxx
                    445: .It 0
1.69      apb       446: No descriptive messages or commands executed by
                    447: .Xr make 1
                    448: are shown.
1.30      lukem     449: .It 1
1.69      apb       450: Brief messages are shown describing what is being done,
                    451: but the actual commands executed by
                    452: .Xr make 1
                    453: are not displayed.
1.30      lukem     454: .It 2
1.69      apb       455: Descriptive messages are shown as above (prefixed with a
                    456: .Sq # ) ,
                    457: and ordinary commands performed by
                    458: .Xr make 1
                    459: are displayed.
                    460: .It 3
                    461: In addition to the above, all commands performed by
                    462: .Xr make 1
                    463: are displayed, even if they would ordinarily have been hidden
                    464: through use of the
                    465: .Dq \&@
                    466: prefix in the relevant makefile.
                    467: .It 4
                    468: In addition to the above, commands executed by
                    469: .Xr make 1
                    470: are traced through use of the
                    471: .Xr sh 1
                    472: .Dq Fl x
                    473: flag.
1.30      lukem     474: .El
                    475: .DFLT
                    476: 2
                    477: .
1.1       lukem     478: .It Sy MKCATPAGES
                    479: .YorN
                    480: Indicates whether preformatted plaintext manual pages will be created
                    481: during a build.
1.93      dholland  482: .DFLTn
1.1       lukem     483: .
1.98      martin    484: .It Sy MKCROSSGDB
                    485: .YorN
                    486: Create a cross-gdb as a host tool.
                    487: .DFLTn
                    488: .
1.1       lukem     489: .It Sy MKCRYPTO
                    490: .YorN
                    491: Indicates whether cryptographic code will be included in a build;
                    492: provided for the benefit of countries that do not allow strong
1.6       wiz       493: cryptography.
                    494: Will not affect use of the standard low-security password encryption system,
1.1       lukem     495: .Xr crypt 3 .
                    496: .DFLTy
                    497: .
1.97      martin    498: .It Sy MKDEBUG
                    499: .YorN
                    500: Indicates whether debug information should be generated for all userland
                    501: binaries compiled.
                    502: The result is collected as an additional
                    503: .Sy debug.tgz
                    504: and
                    505: .Sy xdebug.tgz
                    506: set and installed in
                    507: .Pa /usr/libdata/debug .
                    508: .DFLTn
                    509: .
                    510: .It Sy MKDEBUGLIB
                    511: .YorN
1.99      wiz       512: Indicates whether debug information (see
1.97      martin    513: .Sy MKDEBUG )
                    514: should also be generated for all libraries build.
                    515: .DFLTn
                    516: .
1.1       lukem     517: .It Sy MKDOC
                    518: .YorN
                    519: Indicates whether system documentation destined for
1.14      lukem     520: .Sy DESTDIR Ns Pa /usr/share/doc
1.1       lukem     521: will be installed during a build.
                    522: .DFLTy
                    523: .
1.107   ! apb       524: .It Sy MKEXTSRC
        !           525: .YorN
        !           526: Indicates whether extsrc is built from
        !           527: .Sy EXTSRCSRCDIR .
        !           528: .DFLTn
        !           529: .
1.65      lukem     530: .It Sy MKHTML
                    531: .YorN
                    532: Indicates whether preformatted HTML manual pages will be built
                    533: and installed
                    534: .DFLTy
                    535: .
1.1       lukem     536: .It Sy MKHOSTOBJ
                    537: .YorN
                    538: If set to
                    539: .Dq yes ,
                    540: then for programs intended to be run on the compile host,
                    541: the name, release, and architecture of the host operating system
                    542: will be suffixed to the name of the object directory created by
                    543: .Dq make obj .
                    544: (This allows multiple host systems to compile NetBSD for a single target.)
                    545: If set to
                    546: .Dq no ,
                    547: then programs built to be run on the compile host will use the same
                    548: object directory names as programs built to be run on the target.
                    549: .DFLTn
                    550: .
                    551: .It Sy MKINFO
                    552: .YorN
                    553: Indicates whether GNU Info files, used for the documentation for
                    554: most of the compilation tools, will be created and installed during a
                    555: build.
                    556: .DFLTy
                    557: .
1.98      martin    558: .It Sy MKKDEBUG
                    559: .YorN
                    560: Force generation of full-debug symbol versions of all kernels compiled.
                    561: Alongside of the
                    562: .Pa netbsd
                    563: kernel file, an unstripped version
                    564: .Pa netbsd.gdb
                    565: is created.
1.99      wiz       566: This is useful if a cross-gdb is built as well (see
1.98      martin    567: .Sy MKCROSSGDB ) .
                    568: .DFLTn
                    569: .
1.83      apb       570: .It Sy MKKMOD
                    571: .YorN
                    572: Indicates whether kernel modules are built and installed.
                    573: .DFLTy
                    574: .
1.1       lukem     575: .It Sy MKLINT
                    576: .YorN
                    577: Indicates whether
                    578: .Xr lint 1
                    579: will be run against portions of the
                    580: .Nx
                    581: source code during the build, and whether lint libraries will be
                    582: installed into
1.14      lukem     583: .Sy DESTDIR Ns Pa /usr/libdata/lint .
1.1       lukem     584: .DFLTy
                    585: .
                    586: .It Sy MKMAN
                    587: .YorN
                    588: Indicates whether manual pages will be installed during a build.
                    589: .DFLTy
                    590: .
                    591: .It Sy MKNLS
                    592: .YorN
                    593: Indicates whether Native Language System locale zone files will be
                    594: compiled and installed during a build.
                    595: .DFLTy
                    596: .
                    597: .It Sy MKOBJ
                    598: .YorN
                    599: Indicates whether object directories will be created when running
                    600: .Dq make obj .
                    601: If set to
                    602: .Dq no ,
                    603: then all built files will be located inside the regular source tree.
                    604: .DFLTy
1.57      dholland  605: .Pp
                    606: Note that setting
                    607: .Sy MKOBJ
                    608: to
                    609: .Dq no
                    610: is not recommended and may cause problems when updating the tree with
                    611: .Xr cvs 1 .
1.1       lukem     612: .
                    613: .It Sy MKPIC
                    614: .YorN
                    615: Indicates whether shared objects and libraries will be created and
1.6       wiz       616: installed during a build.
                    617: If set to
1.1       lukem     618: .Dq no ,
                    619: the entire built system will be statically linked.
                    620: .DFLT
1.6       wiz       621: Platform dependent.
                    622: As of this writing, all platforms except
1.1       lukem     623: .Sy sh3
                    624: default to
                    625: .Dq yes .
                    626: .
                    627: .It Sy MKPICINSTALL
                    628: .YorN
                    629: Indicates whether the
                    630: .Xr ar 1
                    631: format libraries
                    632: .Sy ( lib*_pic.a ) ,
                    633: used to generate shared libraries, are installed during a build.
                    634: .DFLTy
                    635: .
                    636: .It Sy MKPROFILE
                    637: .YorN
                    638: Indicates whether profiled libraries
                    639: .Sy ( lib*_p.a )
                    640: will be built and installed during a build.
                    641: .DFLT
                    642: .Dq yes ;
                    643: however, some platforms turn off
                    644: .Sy MKPROFILE
                    645: by default at times due to toolchain problems with profiled code.
                    646: .
1.89      wiz       647: .It Sy MKREPRO
                    648: .YorN
                    649: Create reproducable builds.
                    650: This enables different switches to make two builds from the same
                    651: source tree result in the same build results.
                    652: .DFLTn
                    653: .
1.1       lukem     654: .It Sy MKSHARE
                    655: .YorN
                    656: Indicates whether files destined to reside in
1.14      lukem     657: .Sy DESTDIR Ns Pa /usr/share
1.6       wiz       658: will be built and installed during a build.
                    659: If set to
1.1       lukem     660: .Dq no ,
                    661: then all of
                    662: .Sy MKCATPAGES , MKDOC , MKINFO , MKMAN ,
                    663: and
                    664: .Sy MKNLS
                    665: will be set to
                    666: .Dq no
                    667: unconditionally.
                    668: .DFLTy
                    669: .
1.66      joerg     670: .It Sy MKSTRIPIDENT
                    671: .YorN
1.90      abs       672: Indicates whether RCS IDs, for use with
                    673: .Xr ident 1 ,
                    674: should be stripped from program binaries and shared libraries.
1.66      joerg     675: .DFLTn
                    676: .
1.25      lukem     677: .It Sy MKUNPRIVED
                    678: .YorN
                    679: Indicates whether an unprivileged install will occur.
1.1       lukem     680: The user, group, permissions, and file flags, will not be set on
1.37      jmc       681: the installed items; instead the information will be appended to
1.1       lukem     682: a file called
                    683: .Pa METALOG
                    684: in
                    685: .Sy DESTDIR .
                    686: The contents of
                    687: .Pa METALOG
1.37      jmc       688: are used during the generation of the distribution tar files to ensure
1.1       lukem     689: that the appropriate file ownership is stored.
1.25      lukem     690: .DFLTn
1.1       lukem     691: .
1.25      lukem     692: .It Sy MKUPDATE
                    693: .YorN
                    694: Indicates whether all install operations intended to write to
1.1       lukem     695: .Sy DESTDIR
                    696: will compare file timestamps before installing, and skip the install
1.6       wiz       697: phase if the destination files are up-to-date.
                    698: This also has implications on full builds (see next subsection).
1.25      lukem     699: .DFLTn
                    700: .
1.34      lukem     701: .It Sy MKX11
                    702: .YorN
1.68      mrg       703: Indicates whether X11 is built from
1.34      lukem     704: .Sy X11SRCDIR .
                    705: .DFLTn
                    706: .
1.25      lukem     707: .It Sy TOOLDIR
                    708: Directory to hold the host tools, once built.
1.46      apb       709: If specified, must be an absolute path.
1.25      lukem     710: This directory should be unique to a given host system and
                    711: .Nx
                    712: source tree.
                    713: (However, multiple targets may share the same
                    714: .Sy TOOLDIR ;
                    715: the target-dependent files have unique names.)  If unset, a default based
                    716: on the
                    717: .Xr uname 1
                    718: information of the host platform will be created in the
                    719: .Sy .OBJDIR
                    720: of
1.26      lukem     721: .Pa src .
1.1       lukem     722: .DFLTu
                    723: .
                    724: .It Sy USETOOLS
                    725: Indicates whether the tools specified by
                    726: .Sy TOOLDIR
1.6       wiz       727: should be used as part of a build in progress.
                    728: Must be set to
1.1       lukem     729: .Dq yes
                    730: if cross-compiling.
                    731: .Bl -tag -width "never"
                    732: .It Sy yes
                    733: Use the tools from
                    734: .Sy TOOLDIR .
                    735: .It Sy no
                    736: Do not use the tools from
                    737: .Sy TOOLDIR ,
                    738: but refuse to build native compilation tool components that are
                    739: version-specific for that tool.
                    740: .It Sy never
                    741: Do not use the tools from
                    742: .Sy TOOLDIR ,
1.6       wiz       743: even when building native tool components.
                    744: This is similar to the traditional
1.1       lukem     745: .Nx
                    746: build method, but does
                    747: .Em not
                    748: verify that the compilation tools in use are up-to-date enough in order
1.6       wiz       749: to build the tree successfully.
                    750: This may cause build or runtime problems when building the whole
1.1       lukem     751: .Nx
                    752: source tree.
                    753: .El
1.58      dholland  754: .DFLT
                    755: .Dq yes ,
                    756: unless
                    757: .Sy TOOLCHAIN_MISSING
                    758: is set to
                    759: .Dq yes .
                    760: .Pp
                    761: .Sy USETOOLS
                    762: is also set to
                    763: .Dq no
                    764: when using
                    765: .Aq bsd.*.mk
                    766: outside the
                    767: .Nx
                    768: source tree.
1.1       lukem     769: .
1.34      lukem     770: .It Sy X11SRCDIR
                    771: Directory containing the X11R6 source.
1.46      apb       772: If specified, must be an absolute path.
1.34      lukem     773: The main X11R6 source is found in
                    774: .Sy X11SRCDIR Ns Pa /xfree/xc .
                    775: .DFLT
1.80      apb       776: .Sy NETBSDRCDIR Ns Pa /../xsrc ,
                    777: if that exists; otherwise
                    778: .Pa /usr/xsrc .
1.34      lukem     779: .
1.68      mrg       780: .It Sy X11FLAVOUR
                    781: The style of X11 cross-built, set to either
                    782: .Dq Xorg
                    783: or
                    784: .Dq XFree86 .
                    785: .DFLT
                    786: .Dq Xorg
1.70      mrg       787: on amd64, i386, macppc, shark and sparc64 platforms,
1.68      mrg       788: .Dq XFree86
                    789: on everything else.
                    790: .
1.1       lukem     791: .El
                    792: .
                    793: .Ss \*qmake\*q variables for full builds
                    794: These variables only affect the top level
                    795: .Dq Makefile
                    796: and do not affect manually building subtrees of the
                    797: .Nx
                    798: source code.
                    799: .
1.7       lukem     800: .Bl -tag -width "INSTALLWORLDDIR"
                    801: .
                    802: .It Sy INSTALLWORLDDIR
                    803: Location for the
                    804: .Dq make installworld
                    805: target to install to.
1.46      apb       806: If specified, must be an absolute path.
1.7       lukem     807: .DFLT
                    808: .Dq /
1.1       lukem     809: .
                    810: .It Sy MKOBJDIRS
                    811: .YorN
                    812: Indicates whether object directories will be created automatically
                    813: (via a
                    814: .Dq make obj
                    815: pass) at the start of a build.
1.21      lukem     816: .DFLTn
1.57      dholland  817: .Pp
                    818: If using
                    819: .Sy build.sh ,
                    820: the default is
                    821: .Dq yes .
                    822: This may be set back to
                    823: .Dq no
                    824: by giving
                    825: .Sy build.sh
                    826: the
                    827: .Fl o
                    828: option.
1.1       lukem     829: .
1.25      lukem     830: .It Sy MKUPDATE
                    831: .YorN
                    832: If set, then in addition to the effects described for
                    833: .Sy MKUPDATE=yes
                    834: above, this implies the effects of
                    835: .Sy NOCLEANDIR
1.91      abs       836: (i.e.,
1.25      lukem     837: .Dq make cleandir
                    838: is avoided).
                    839: .DFLTn
1.57      dholland  840: .Pp
                    841: If using
                    842: .Sy build.sh ,
                    843: this may be set by giving the
                    844: .Fl u
                    845: option.
1.25      lukem     846: .
1.1       lukem     847: .It Sy NBUILDJOBS
1.6       wiz       848: Now obsolete.
1.91      abs       849: Use the
1.1       lukem     850: .Xr make 1
                    851: option
1.4       lukem     852: .Fl j ,
1.57      dholland  853: instead.
                    854: See below.
1.1       lukem     855: .DFLTu
                    856: .
                    857: .It Sy NOCLEANDIR
                    858: If set, avoids the
                    859: .Dq make cleandir
1.6       wiz       860: phase of a full build.
                    861: This has the effect of allowing only changed
                    862: files in a source tree to be recompiled.
                    863: This can speed up builds when updating only a few files in the tree.
1.1       lukem     864: .DFLTu
1.57      dholland  865: .Pp
                    866: See also
                    867: .Sy MKUPDATE .
1.1       lukem     868: .
                    869: .It Sy NODISTRIBDIRS
                    870: If set, avoids the
                    871: .Dq make distrib-dirs
1.6       wiz       872: phase of a full build.
                    873: This skips running
1.1       lukem     874: .Xr mtree 8
                    875: on
                    876: .Sy DESTDIR ,
                    877: useful on systems where building as an unprivileged user, or where it is
                    878: known that the system-wide mtree files have not changed.
                    879: .DFLTu
                    880: .
                    881: .It Sy NOINCLUDES
                    882: If set, avoids the
                    883: .Dq make includes
1.6       wiz       884: phase of a full build.
                    885: This has the effect of preventing
1.1       lukem     886: .Xr make 1
                    887: from thinking that some programs are out-of-date simply because the
1.6       wiz       888: system include files have changed.
                    889: However, this option should not be used when updating the entire
1.1       lukem     890: .Nx
                    891: source tree arbitrarily; it is suggested to use
1.25      lukem     892: .Sy MKUPDATE=yes
1.57      dholland  893: instead in that case.
1.1       lukem     894: .DFLTu
                    895: .
                    896: .It Sy RELEASEDIR
                    897: If set, specifies the directory to which a
                    898: .Xr release 7
                    899: layout will be written at the end of a
                    900: .Dq make release .
1.46      apb       901: If specified, must be an absolute path.
1.1       lukem     902: .DFLTu
1.17      lukem     903: .Pp
                    904: .Em Note :
                    905: .Sy build.sh
                    906: will provide a default of
                    907: .Pa releasedir
                    908: (in the top-level
                    909: .Sy .OBJDIR )
                    910: unless run in
                    911: .Sq expert
1.57      dholland  912: mode.
1.1       lukem     913: .
                    914: .El
                    915: .
                    916: .Sh BUILDING
                    917: .
                    918: .Ss \*qmake\*q command line options
1.37      jmc       919: This is not a summary of all the options available to
1.1       lukem     920: .Xr make 1 ;
                    921: only the options used most frequently with
                    922: .Nx
                    923: builds are listed here.
                    924: .
                    925: .Bl -tag -width "var=value"
                    926: .
1.4       lukem     927: .It Fl j Ar njob
1.1       lukem     928: Run up to
1.4       lukem     929: .Ar njob
1.91      abs       930: .Xr make 1
1.1       lukem     931: subjobs in parallel.
1.91      abs       932: Makefiles should use .WAIT or have explicit dependencies
1.1       lukem     933: as necessary to enforce build ordering.
                    934: .
1.4       lukem     935: .It Fl m Ar dir
1.1       lukem     936: Specify the default directory for searching for system Makefile
                    937: segments, mainly the
                    938: .Aq bsd.*.mk
1.6       wiz       939: files.
                    940: When building any full
1.1       lukem     941: .Nx
                    942: source tree, this should be set to the
1.99      wiz       943: .Dq Pa share/mk
1.6       wiz       944: directory in the source tree.
1.57      dholland  945: This is set automatically when building from the top level, or when using
                    946: .Sy build.sh .
1.1       lukem     947: .
1.4       lukem     948: .It Fl n
1.1       lukem     949: Display the commands that would have been executed, but do not
1.6       wiz       950: actually execute them.
                    951: This will still cause recursion to take place.
1.1       lukem     952: .
1.32      zuntum    953: .It Fl V Ar var
1.1       lukem     954: Print
                    955: .Xr make 1 Ns 's
                    956: idea of the value of
1.4       lukem     957: .Ar var .
1.1       lukem     958: Does not build any targets.
                    959: .
                    960: .It Em var=value
                    961: Set the variable
                    962: .Em var
                    963: to
                    964: .Em value ,
                    965: overriding any setting specified by the process environment, the
                    966: .Sy MAKECONF
                    967: configuration file, or the system Makefile segments.
                    968: .
                    969: .El
                    970: .
                    971: .Ss \*qmake\*q targets
                    972: .
                    973: These default targets may be built by running
                    974: .Xr make 1
                    975: in any subtree of the
                    976: .Nx
1.6       wiz       977: source code.
                    978: It is recommended that none of these be used from the top
1.1       lukem     979: level Makefile; as a specific exception,
                    980: .Dq make obj
                    981: and
                    982: .Dq make cleandir
                    983: are useful in that context.
                    984: .
                    985: .Bl -tag -width "dependall"
                    986: .
                    987: .It Sy all
                    988: Build programs, libraries, and preformatted documentation.
                    989: .
                    990: .It Sy clean
                    991: Remove program and library object code files.
                    992: .
                    993: .It Sy cleandir
                    994: Same as
                    995: .Sy clean ,
                    996: but also remove preformatted documentation, dependency files generated
                    997: by
                    998: .Dq make depend ,
                    999: and any other files known to be created at build time.
                   1000: .
                   1001: .It Sy depend
                   1002: Create dependency files
                   1003: .Sy ( .depend )
                   1004: containing more detailed information about the dependencies of source
1.6       wiz      1005: code on header files.
                   1006: Allows programs to be recompiled automatically when a dependency changes.
1.1       lukem    1007: .
                   1008: .It Sy dependall
                   1009: Does a
                   1010: .Dq make depend
                   1011: immediately followed by a
                   1012: .Dq make all .
                   1013: This improves cache locality of the build since both passes read the source
                   1014: files in their entirety.
                   1015: .
1.34      lukem    1016: .It Sy distclean
                   1017: Synonym for
                   1018: .Sy cleandir .
                   1019: .
1.1       lukem    1020: .It Sy includes
1.6       wiz      1021: Build and install system header files.
                   1022: Typically needed before any system libraries or programs can be built.
1.1       lukem    1023: .
                   1024: .It Sy install
                   1025: Install programs, libraries, and documentation into
                   1026: .Sy DESTDIR .
                   1027: Few files will be installed to
1.14      lukem    1028: .Sy DESTDIR Ns Pa /dev ,
                   1029: .Sy DESTDIR Ns Pa /etc ,
                   1030: .Sy DESTDIR Ns Pa /root
1.1       lukem    1031: or
1.14      lukem    1032: .Sy DESTDIR Ns Pa /var
1.1       lukem    1033: in order to prevent user supplied configuration data from being overwritten.
                   1034: .It Sy lint
                   1035: Run
                   1036: .Xr lint 1
                   1037: against the C source code, where appropriate, and generate
                   1038: system-installed lint libraries.
                   1039: .
                   1040: .It Sy obj
                   1041: Create object directories to be used for built files, instead of
                   1042: building directly in the source tree.
                   1043: .
                   1044: .It Sy tags
                   1045: Create
                   1046: .Xr ctags 1
                   1047: searchable function lists usable by the
                   1048: .Xr ex 1
                   1049: and
                   1050: .Xr vi 1
                   1051: text editors.
                   1052: .
                   1053: .El
                   1054: .
                   1055: .Ss \*qmake\*q targets for the top level
                   1056: .
                   1057: Additional
                   1058: .Xr make 1
                   1059: targets are usable specifically from the top source level to facilitate
                   1060: building the entire
                   1061: .Nx
                   1062: source tree.
                   1063: .
1.7       lukem    1064: .Bl -tag -width "distribution"
1.1       lukem    1065: .
                   1066: .It Sy build
                   1067: Build the entire
                   1068: .Nx
1.55      reed     1069: system (except the kernel).
1.6       wiz      1070: This orders portions of the source tree such that prerequisites
1.1       lukem    1071: will be built in the proper order.
                   1072: .
1.7       lukem    1073: .It Sy distribution
                   1074: Do a
                   1075: .Dq make build ,
1.55      reed     1076: and then install a full distribution (which does not include a kernel) into
1.9       lukem    1077: .Sy DESTDIR ,
                   1078: including files in
1.14      lukem    1079: .Sy DESTDIR Ns Pa /dev ,
                   1080: .Sy DESTDIR Ns Pa /etc ,
                   1081: .Sy DESTDIR Ns Pa /root
1.9       lukem    1082: and
1.14      lukem    1083: .Sy DESTDIR Ns Pa /var .
1.7       lukem    1084: .
                   1085: .It Sy buildworld
                   1086: As per
                   1087: .Dq make distribution ,
                   1088: except that it ensures that
                   1089: .Sy DESTDIR
                   1090: is not the root directory.
                   1091: .
                   1092: .It Sy installworld
                   1093: Install the distribution from
                   1094: .Sy DESTDIR
                   1095: to
1.57      dholland 1096: .Sy INSTALLWORLDDIR ,
                   1097: which defaults to the root directory.
1.7       lukem    1098: Ensures that
                   1099: .Sy INSTALLWORLDDIR
1.37      jmc      1100: is not the root directory if cross compiling.
1.7       lukem    1101: .Pp
1.48      apb      1102: The
                   1103: .Sy INSTALLSETS
1.83      apb      1104: environment variable may be set to a space-separated list of
1.48      apb      1105: distribution sets to be installed.
                   1106: By default, all sets except
                   1107: .Dq etc
                   1108: and
                   1109: .Dq xetc
1.57      dholland 1110: are installed, so most files in
1.48      apb      1111: .Sy INSTALLWORLDDIR Ns Pa /etc
1.57      dholland 1112: will not be installed or modified.
1.48      apb      1113: .Pp
1.7       lukem    1114: .Em Note :
1.48      apb      1115: Before performing this operation with
                   1116: .Sy INSTALLWORLDDIR Ns = Ns Pa / ,
                   1117: it is highly recommended that you upgrade your kernel and reboot.
                   1118: After performing this operation,
                   1119: it is recommended that you use
                   1120: .Xr etcupdate 8
                   1121: to update files in
1.92      abs      1122: .Sy INSTALLWORLDDIR Ns Pa /etc ,
                   1123: and
1.48      apb      1124: .Xr postinstall 8
1.92      abs      1125: to check for or fix inconsistencies.
1.12      lukem    1126: .It Sy sets
                   1127: Create distribution sets from
                   1128: .Sy DESTDIR
                   1129: into
1.56      lukem    1130: .Sy RELEASEDIR/RELEASEMACHINEDIR Ns Pa /binary/sets .
1.12      lukem    1131: Should be run after
1.57      dholland 1132: .Dq make distribution ,
                   1133: as
1.12      lukem    1134: .Dq make build
1.57      dholland 1135: alone does not install all of the required files.
1.12      lukem    1136: .
1.18      lukem    1137: .It Sy sourcesets
                   1138: Create source sets of the source tree into
                   1139: .Sy RELEASEDIR Ns Pa /source/sets .
                   1140: .
1.40      apb      1141: .It Sy syspkgs
                   1142: Create syspkgs from
                   1143: .Sy DESTDIR
                   1144: into
1.56      lukem    1145: .Sy RELEASEDIR/RELEASEMACHINEDIR Ns Pa /binary/syspkgs .
1.40      apb      1146: Should be run after
1.57      dholland 1147: .Dq make distribution ,
                   1148: as
1.40      apb      1149: .Dq make build
1.57      dholland 1150: alone does not install all of the required files.
1.40      apb      1151: .
1.1       lukem    1152: .It Sy release
                   1153: Do a
1.9       lukem    1154: .Dq make distribution ,
1.12      lukem    1155: build kernels, distribution media, and install sets
                   1156: (this as per
                   1157: .Dq make sets ) ,
                   1158: and
1.1       lukem    1159: then package the system into a standard release layout as described by
                   1160: .Xr release 7 .
                   1161: This requires that
                   1162: .Sy RELEASEDIR
                   1163: be set (see above).
                   1164: .
1.57      dholland 1165: .It Sy iso-image
1.49      apb      1166: Create a
                   1167: .Nx
                   1168: installation CD-ROM image in the
1.105     snj      1169: .Sy RELEASEDIR Ns Pa /images
1.49      apb      1170: directory.
                   1171: The CD-ROM file system will have a layout as described in
                   1172: .Xr release 7 .
                   1173: .Pp
                   1174: For most machine types, the CD-ROM will be bootable, and will automatically
                   1175: run the
                   1176: .Xr sysinst 8
                   1177: menu-based installation program, which can be used to install or upgrade a
                   1178: .Nx
                   1179: system.
                   1180: Bootable CD-ROMs also contain tools that may be useful in
                   1181: repairing a damaged
                   1182: .Nx
                   1183: installation.
                   1184: .Pp
                   1185: Before
                   1186: .Dq make iso-image
                   1187: is attempted, RELEASEDIR must be populated by
1.42      apb      1188: .Dq make release
                   1189: or equivalent.
1.49      apb      1190: .Pp
                   1191: Note that other, smaller, CD-ROM images may be created in the
1.56      lukem    1192: .Sy RELEASEDIR/RELEASEMACHINEDIR Ns Pa /installation/cdrom
1.49      apb      1193: directory by
                   1194: .Dq "make release" .
                   1195: These smaller images usually contain the same tools as the larger images in
1.105     snj      1196: .Sy RELEASEDIR Ns Pa /images ,
1.49      apb      1197: but do not contain additional content such as the distribution sets.
                   1198: .Pp
                   1199: Note that the mac68k port still uses an older method of creating
                   1200: CD-ROM images.
1.42      apb      1201: This requires the
                   1202: .Xr mkisofs 1
                   1203: utility, which is not part of
                   1204: .Nx ,
                   1205: but which can be installed from
1.43      apb      1206: .Pa pkgsrc/sysutils/cdrtools .
1.42      apb      1207: .
1.63      lukem    1208: .It Sy iso-image-source
1.51      jnemeth  1209: Create a
                   1210: .Nx
                   1211: installation CD-ROM image in the
1.105     snj      1212: .Sy RELEASEDIR Ns Pa /images
1.51      jnemeth  1213: directory.
                   1214: The CD-ROM file system will have a layout as described in
                   1215: .Xr release 7 .
                   1216: It will have top level directories for the machine type and source.
                   1217: .Pp
                   1218: For most machine types, the CD-ROM will be bootable, and will automatically
                   1219: run the
                   1220: .Xr sysinst 8
                   1221: menu-based installation program, which can be used to install or upgrade a
                   1222: .Nx
                   1223: system.
                   1224: Bootable CD-ROMs also contain tools that may be useful in
                   1225: repairing a damaged
                   1226: .Nx
                   1227: installation.
                   1228: .Pp
                   1229: Before
                   1230: .Dq make iso-image-source
                   1231: is attempted, RELEASEDIR must be populated by
                   1232: .Dq make sourcesets release
                   1233: or equivalent.
                   1234: .Pp
                   1235: Note that other, smaller, CD-ROM images may be created in the
1.56      lukem    1236: .Sy RELEASEDIR/RELEASEMACHINEDIR Ns Pa /installation/cdrom
1.51      jnemeth  1237: directory by
                   1238: .Dq make release .
                   1239: These smaller images usually contain the same tools as the larger images in
1.105     snj      1240: .Sy RELEASEDIR Ns Pa /images ,
1.51      jnemeth  1241: but do not contain additional content such as the distribution sets.
                   1242: .Pp
                   1243: Note that the mac68k port still uses an older method of creating
                   1244: CD-ROM images.
                   1245: This requires the
                   1246: .Xr mkisofs 1
                   1247: utility, which is not part of
                   1248: .Nx ,
                   1249: but which can be installed from
                   1250: .Pa pkgsrc/sysutils/cdrtools .
                   1251: .
1.86      apb      1252: .It Sy install-image
                   1253: Create a bootable
                   1254: .Nx
                   1255: installation disk image in the
                   1256: .Sy RELEASEDIR/RELEASEMACHINEDIR Ns Pa /installation/installimage
                   1257: directory.
1.87      apb      1258: The installation disk image is suitable for copying to
                   1259: bootable USB flash memory sticks, etc., for machines which
                   1260: are able to boot from such devices.
                   1261: The file system in the bootable disk image will have a layout
1.86      apb      1262: as described in
                   1263: .Xr release 7 .
                   1264: .Pp
                   1265: The installation image is bootable, and will automatically
                   1266: run the
                   1267: .Xr sysinst 8
                   1268: menu-based installation program, which can be used to install or upgrade a
                   1269: .Nx
                   1270: system.
1.87      apb      1271: The image also contains tools that may be
1.86      apb      1272: useful in repairing a damaged
                   1273: .Nx
                   1274: installation.
                   1275: .Pp
                   1276: Before
                   1277: .Dq make install-image
1.87      apb      1278: is attempted,
                   1279: .Sy RELEASEDIR
                   1280: must be populated by
1.86      apb      1281: .Dq make release
1.87      apb      1282: or equivalent.
                   1283: The build must have been performed with
1.91      abs      1284: .Sy MKUNPRIVED=yes
1.87      apb      1285: because
                   1286: .Dq make install-image
                   1287: relies on information in
                   1288: .Sy DESTDIR Ns Pa /METALOG .
1.86      apb      1289: .
                   1290: .It live-image
                   1291: Create
                   1292: .Nx
                   1293: live images in the
                   1294: .Sy RELEASEDIR/RELEASEMACHINEDIR Ns Pa /installation/liveimage
                   1295: directory.
                   1296: The live image contains all necessary files
                   1297: to boot
                   1298: .Nx
1.87      apb      1299: up to multi-user mode, including all files
1.86      apb      1300: which should be extracted during installation,
                   1301: .Nx
1.87      apb      1302: disklabel, bootloaders, etc.
1.86      apb      1303: .Pp
1.87      apb      1304: The live image is suitable for use as a disk image in
                   1305: virtual machine environments such as QEMU,
                   1306: and also useful to boot
1.86      apb      1307: .Nx
1.87      apb      1308: from a USB flash memory stick
                   1309: on a real machine, without the need for installation.
1.86      apb      1310: .Pp
                   1311: Before
                   1312: .Dq make live-image
                   1313: is attempted, RELEASEDIR must be populated by
                   1314: .Dq make release
1.88      tsutsui  1315: or equivalent.
1.87      apb      1316: The build must have been performed with
1.91      abs      1317: .Sy MKUNPRIVED=yes
1.87      apb      1318: because
                   1319: .Dq make install-image
                   1320: relies on information in
                   1321: .Sy DESTDIR Ns Pa /METALOG .
1.86      apb      1322: .
1.1       lukem    1323: .It Sy regression-tests
                   1324: Can only be run after building the regression tests in the directory
                   1325: .Dq regress .
1.57      dholland 1326: Runs those compiled regression tests on the local host.
                   1327: Note that most tests are now managed instead using
                   1328: .Xr atf 7 ;
                   1329: this target should probably run those as well but currently does not.
1.1       lukem    1330: .
                   1331: .El
                   1332: .
                   1333: .Ss The \*qbuild.sh\*q script
                   1334: .
1.85      apb      1335: This script file is a shell script designed to build the
1.1       lukem    1336: entire
                   1337: .Nx
1.85      apb      1338: system on any host with a suitable modern shell and some common
                   1339: utilities.
                   1340: The required shell features are described under the
                   1341: .Sy HOST_SH
                   1342: variable.
                   1343: .Pp
                   1344: If a host system's default shell does support the required
                   1345: features, then we suggest that you explicitly specify
                   1346: a suitable shell using a command like
                   1347: .Bd -unfilled -offset indent
                   1348: .Li /path/to/suitable/shell build.sh Op Ar options
                   1349: .Ed
                   1350: .Pp
                   1351: The above command will usually enable
                   1352: .Nm build.sh
                   1353: to automatically set
                   1354: .Sy HOST_SH Ns Cm = Ns Pa /path/to/suitable/shell ,
                   1355: but if that fails, then the following set of commands may be used instead:
                   1356: .Bd -unfilled -offset indent
                   1357: .Li HOST_SH= Ns Va /path/to/suitable/shell
                   1358: .Li export HOST_SH
                   1359: .Li ${HOST_SH} build.sh Op Ar options
                   1360: .Ed
                   1361: .Pp
                   1362: If
                   1363: .Sy build.sh
                   1364: detects that it is being executed under an unsuitable shell, it attempts
                   1365: to exec a suitable shell instead, or prints an error message.
                   1366: If
                   1367: .Sy HOST_SH
                   1368: is not set explicitly, then
                   1369: .Nm build.sh
                   1370: sets a default using heuristics dependent on the host platform,
                   1371: or from the shell under which
                   1372: .Nm build.sh
                   1373: is executed (if that can be determined),
                   1374: or using the first copy of
                   1375: .Pa sh
                   1376: found in
                   1377: .Sy PATH .
1.1       lukem    1378: .Pp
                   1379: All cross-compile builds, and most native builds, of the entire system
                   1380: should make use of
                   1381: .Sy build.sh
                   1382: rather than just running
                   1383: .Dq make .
                   1384: This way, the
                   1385: .Xr make 1
                   1386: program will be bootstrapped properly, in case the host system has an
                   1387: older or incompatible
                   1388: .Dq make
                   1389: program.
                   1390: .Pp
                   1391: When compiling the entire system via
                   1392: .Sy build.sh ,
                   1393: many
                   1394: .Xr make 1
                   1395: variables are set for you in order to help encapsulate the build
1.6       wiz      1396: process.
                   1397: In the list of options below, variables that are automatically set by
1.1       lukem    1398: .Sy build.sh
                   1399: are noted where applicable.
1.9       lukem    1400: .
1.1       lukem    1401: .Pp
1.9       lukem    1402: The following operations are supported by
1.1       lukem    1403: .Sy build.sh :
                   1404: .
1.9       lukem    1405: .Bl -tag -width "distribution"
                   1406: .
                   1407: .It Sy build
                   1408: Build the system as per
                   1409: .Dq make build .
1.57      dholland 1410: Before the main part of the build commences, this command runs the
1.9       lukem    1411: .Sy obj
1.57      dholland 1412: operation (unless the
                   1413: .Fl o
                   1414: option is given),
                   1415: .Dq make cleandir
                   1416: (unless the
                   1417: .Fl u
                   1418: option is given),
                   1419: and the
1.9       lukem    1420: .Sy tools
1.57      dholland 1421: operation.
1.9       lukem    1422: .
                   1423: .It Sy distribution
                   1424: Build a full distribution as per
                   1425: .Dq make distribution .
1.57      dholland 1426: This command first runs the
1.9       lukem    1427: .Sy build
                   1428: operation.
                   1429: .
                   1430: .It Sy release
                   1431: Build a full release as per
                   1432: .Dq make release .
1.57      dholland 1433: This command first runs the
1.9       lukem    1434: .Sy distribution
                   1435: operation.
                   1436: .
1.10      lukem    1437: .It Sy makewrapper
                   1438: Create the
1.13      lukem    1439: .Sy \*[toolprefix]make-MACHINE
1.10      lukem    1440: wrapper.
                   1441: This operation is automatically performed for any of the other
                   1442: operations.
                   1443: .
1.63      lukem    1444: .It Sy cleandir
                   1445: Perform
                   1446: .Dq make cleandir .
                   1447: .
1.9       lukem    1448: .It Sy obj
                   1449: Perform
                   1450: .Dq make obj .
1.11      lukem    1451: .
1.9       lukem    1452: .It Sy tools
                   1453: Build and install the host tools from
                   1454: .Pa src/tools .
1.57      dholland 1455: This command will first run
                   1456: .Dq make obj
                   1457: and
                   1458: .Dq make cleandir
1.91      abs      1459: in the
1.57      dholland 1460: .Pa tools
                   1461: subdirectory unless the
                   1462: .Fl o
                   1463: or
                   1464: .Fl u
                   1465: options (respectively) are given.
1.22      lukem    1466: .
                   1467: .It Sy install Ns = Ns Ar idir
                   1468: Install the contents of
                   1469: .Sy DESTDIR
                   1470: to
                   1471: .Ar idir ,
                   1472: using
                   1473: .Dq make installworld .
1.48      apb      1474: Note that files that are part of the
                   1475: .Dq etc
                   1476: or
                   1477: .Dq xetc
1.83      apb      1478: sets will not be installed, unless overridden by
                   1479: the INSTALLSETS environment variable.
1.22      lukem    1480: .
1.9       lukem    1481: .It Sy kernel Ns = Ns Ar kconf
                   1482: Build a new kernel.
                   1483: The
                   1484: .Ar kconf
                   1485: argument is the name of a configuration file suitable
                   1486: for use by
1.39      peter    1487: .Xr config 1 .
1.9       lukem    1488: If
                   1489: .Ar kconf
                   1490: does not contain any
                   1491: .Sq /
                   1492: characters, the configuration file is expected to be found in the
                   1493: .Sy KERNCONFDIR
                   1494: directory, which is typically
1.99      wiz      1495: .Pa sys/arch/MACHINE/conf .
1.9       lukem    1496: The new kernel will be built in a subdirectory of
                   1497: .Sy KERNOBJDIR ,
                   1498: which is typically
1.99      wiz      1499: .Pa sys/arch/MACHINE/compile
1.9       lukem    1500: or an associated object directory.
1.57      dholland 1501: .Pp
                   1502: This command does
                   1503: .Em not
                   1504: imply the
                   1505: .Sy tools
                   1506: command; run the
1.9       lukem    1507: .Sy tools
1.57      dholland 1508: command first unless it is
                   1509: .Em certain
                   1510: that the tools already exist and are up to date.
                   1511: .Pp
                   1512: This command will run
                   1513: .Dq make cleandir
                   1514: on the kernel in question first unless the
                   1515: .Fl u
                   1516: option is given.
1.9       lukem    1517: .
1.98      martin   1518: .It Sy kernel.gdb Ns = Ns Ar kconf
                   1519: Build a new kernel with debug information.
                   1520: Similar to the above
                   1521: .Sy kernel Ns = Ns Ar kconf
                   1522: operation, but creates a
                   1523: .Pa netbsd.gdb
                   1524: file alongside of the kernel
                   1525: .Pa netbsd ,
                   1526: which contains a full symbol table and can be used for debugging
1.99      wiz      1527: (for example with a cross-gdb built by
1.98      martin   1528: .Sy MKCROSSGDB ) .
1.106     uebayasi 1529: .It Sy kernels
                   1530: This command will build all kernels defined in port specific release build
                   1531: procedure.
                   1532: .Pp
                   1533: This command internally calls the
                   1534: .Sy kernel Ns = Ns Ar kconf
                   1535: operation for each found kernel configuration file.
1.75      apb      1536: .It Sy modules
                   1537: This command will build kernel modules and install them into
                   1538: .Sy DESTDIR .
                   1539: .
1.22      lukem    1540: .It Sy releasekernel Ns = Ns Ar kconf
                   1541: Install a
                   1542: .Xr gzip 1 Ns ed
1.57      dholland 1543: copy of the kernel previously built by
1.22      lukem    1544: .Sy kernel Ns = Ns Ar kconf
                   1545: into
1.56      lukem    1546: .Sy RELEASEDIR/RELEASEMACHINEDIR Ns Pa /binary/kernel ,
1.22      lukem    1547: usually as
                   1548: .Pa netbsd- Ns Ar kconf Ns Pa .gz ,
                   1549: although the
                   1550: .Dq Pa netbsd
                   1551: prefix is determined from the
                   1552: .Dq Sy config
                   1553: directives in
                   1554: .Ar kconf .
1.9       lukem    1555: .
1.11      lukem    1556: .It Sy sets
                   1557: Perform
                   1558: .Dq make sets .
1.18      lukem    1559: .
                   1560: .It Sy sourcesets
                   1561: Perform
                   1562: .Dq make sourcesets .
                   1563: .
1.40      apb      1564: .It Sy syspkgs
                   1565: Perform
                   1566: .Dq make syspkgs .
                   1567: .
1.42      apb      1568: .It Sy iso-image
                   1569: Perform
                   1570: .Dq make iso-image .
                   1571: .
1.52      jnemeth  1572: .It Sy iso-image-source
                   1573: Perform
                   1574: .Dq make iso-image-source .
                   1575: .
1.86      apb      1576: .It Sy install-image
                   1577: Perform
                   1578: .Dq make install-image .
                   1579: .
                   1580: .It Sy live-image
                   1581: Perform
                   1582: .Dq make live-image .
                   1583: .
1.103     apb      1584: .It Sy list-arch
                   1585: Prints a list of valid
                   1586: .Sy MACHINE
                   1587: and
                   1588: .Sy MACHINE_ARCH
                   1589: settings, the default
                   1590: .Sy MACHINE_ARCH
                   1591: for each
                   1592: .Sy MACHINE ,
                   1593: and aliases for
                   1594: .Sy MACHINE Ns No / Ns Sy MACHINE_ARCH
                   1595: pairs, and then exits.
                   1596: The
                   1597: .Fl m
                   1598: or
                   1599: .Fl a
                   1600: options (or both) may be used to specify glob patterns
                   1601: that will be used to narrow the list of results;
                   1602: for example,
                   1603: .Dq Li build.sh -m 'evm*' -a '*arm*' list-arch
                   1604: will list all known
                   1605: .Sy MACHINE Ns No / Ns Sy MACHINE_ARCH
                   1606: values in which either
                   1607: .Sy MACHINE
                   1608: or
                   1609: .Sy ALIAS
                   1610: matches the pattern
                   1611: .Ql evb* ,
                   1612: and
                   1613: .Sy MACHINE_ARCH
                   1614: matches the pattern
                   1615: .Ql *arm* .
                   1616: .
1.9       lukem    1617: .El
                   1618: .
                   1619: .Pp
                   1620: The following command line options alter the behaviour of the
                   1621: .Sy build.sh
                   1622: operations described above:
                   1623: .
1.1       lukem    1624: .Bl -tag -width "-T tools"
                   1625: .
1.4       lukem    1626: .It Fl a Ar arch
1.1       lukem    1627: Set the value of
                   1628: .Sy MACHINE_ARCH
                   1629: to
1.4       lukem    1630: .Ar arch .
1.103     apb      1631: See the
                   1632: .Fl m
                   1633: option for more information.
1.1       lukem    1634: .
1.4       lukem    1635: .It Fl B Ar buildid
1.1       lukem    1636: Set the value of
                   1637: .Sy BUILDID
                   1638: to
1.4       lukem    1639: .Ar buildid .
1.54      sborrill 1640: This will also append the build identifier to the name of the
1.1       lukem    1641: .Dq make
                   1642: wrapper script so that the resulting name is of the form
1.13      lukem    1643: .Dq Sy \*[toolprefix]make-MACHINE-BUILDID .
1.1       lukem    1644: .
1.54      sborrill 1645: .It Fl C Ar cdextras
1.76      apb      1646: Append
1.91      abs      1647: .Ar cdextras
1.76      apb      1648: to the
1.53      jnemeth  1649: .Sy CDEXTRA
1.76      apb      1650: variable,
                   1651: which is a space-separated list of files or directories that will be
                   1652: added to the CD-ROM image that may be create by the
1.53      jnemeth  1653: .Dq iso-image
                   1654: or
1.76      apb      1655: .Dq iso-image-source
                   1656: operations.
1.54      sborrill 1657: Files will be added to the root of the CD-ROM image, whereas directories
                   1658: will be copied recursively.
                   1659: If relative paths are specified, they will be converted to
                   1660: absolute paths before being used.
1.76      apb      1661: Multiple paths may be specified via multiple
                   1662: .Fl C
                   1663: options, or via a single option whose argument contains multiple
                   1664: space-separated paths.
1.53      jnemeth  1665: .
1.4       lukem    1666: .It Fl D Ar dest
                   1667: Set the value of
                   1668: .Sy DESTDIR
                   1669: to
                   1670: .Ar dest .
1.46      apb      1671: If a relative path is specified, it will be converted to an
                   1672: absolute path before being used.
1.4       lukem    1673: .
1.5       lukem    1674: .It Fl E
                   1675: Set
                   1676: .Sq expert
1.10      lukem    1677: mode.
                   1678: This overrides various sanity checks, and allows:
1.5       lukem    1679: .Sy DESTDIR
1.10      lukem    1680: does not have to be set to a non-root path for builds,
                   1681: and
1.25      lukem    1682: .Sy MKUNPRIVED=yes
1.10      lukem    1683: does not have to be set when building as a non-root user.
                   1684: .Pp
                   1685: .Em Note :
                   1686: It is highly recommended that you know what you are doing when
                   1687: you use this option.
1.7       lukem    1688: .
1.36      wiz      1689: .It Fl h
                   1690: Print a help message.
                   1691: .
1.4       lukem    1692: .It Fl j Ar njob
1.57      dholland 1693: Run up to
                   1694: .Ar njob
1.91      abs      1695: .Xr make 1
1.57      dholland 1696: subjobs in parallel;
1.91      abs      1697: passed through to
1.1       lukem    1698: .Xr make 1 .
1.62      apb      1699: If you see failures for reasons other than running out of memory
                   1700: while using
                   1701: .Sy build.sh
                   1702: with
                   1703: .Fl j ,
1.91      abs      1704: please save complete build logs
1.1       lukem    1705: so the failures can be analyzed.
1.62      apb      1706: .Pp
                   1707: To achieve the fastest builds,
                   1708: .Fl j
                   1709: values between (1 + the number of CPUs) and (2 * the number of CPUs)
                   1710: are recommended.
                   1711: Use lower values on machines with limited memory or I/O bandwidth.
1.1       lukem    1712: .
1.4       lukem    1713: .It Fl M Ar obj
                   1714: Set
                   1715: .Sy MAKEOBJDIRPREFIX
                   1716: to
                   1717: .Ar obj .
1.77      apb      1718: Unsets
                   1719: .Sy MAKEOBJDIR .
                   1720: See
1.95      uwe      1721: .Dq Fl O Ar obj
1.77      apb      1722: for more information.
                   1723: .Pp
1.61      apb      1724: For instance, if the source directory is
                   1725: .Pa /usr/src ,
                   1726: a setting of
                   1727: .Dq Fl M Pa /usr/obj
                   1728: will place build-time files under
                   1729: .Pa /usr/obj/usr/src/bin ,
                   1730: .Pa /usr/obj/usr/src/lib ,
                   1731: .Pa /usr/obj/usr/src/usr.bin ,
                   1732: and so forth.
1.77      apb      1733: .Pp
1.46      apb      1734: If a relative path is specified, it will be converted to an
                   1735: absolute path before being used.
1.77      apb      1736: .Sy build.sh
                   1737: imposes the restriction that the argument to the
                   1738: .Fl M
                   1739: option must not begin with a
                   1740: .Dq \&$
                   1741: (dollar sign)
                   1742: character; otherwise it would be too difficult
                   1743: to determine whether the value is an absolute or a relative path.
                   1744: If the directory does not already exist,
                   1745: .Sy build.sh
                   1746: will create it.
1.4       lukem    1747: .
                   1748: .It Fl m Ar mach
1.1       lukem    1749: Set the value of
                   1750: .Sy MACHINE
                   1751: to
1.47      apb      1752: .Ar mach ,
1.103     apb      1753: unless the
                   1754: .Ar mach
                   1755: argument is an alias that refers to a
                   1756: .Sy MACHINE Ns No / Ns Sy MACHINE_ARCH
                   1757: pair, in which case both
                   1758: .Sy MACHINE
                   1759: and
                   1760: .Sy MACHINE_ARCH
                   1761: are set from the alias.
                   1762: Such aliases are interpreted entirely by
                   1763: .Sy build.sh ;
                   1764: they are not used by any other part of the build system.
                   1765: The
1.1       lukem    1766: .Sy MACHINE_ARCH
1.103     apb      1767: setting implied by
                   1768: .Ar mach
                   1769: will override any value of
                   1770: .Sy MACHINE_ARCH
                   1771: in the process environment, but will not override a value set by the
1.4       lukem    1772: .Fl a
1.103     apb      1773: option.
1.6       wiz      1774: All cross builds require
1.4       lukem    1775: .Fl m ,
1.1       lukem    1776: but if unset on a NetBSD host, the host's value of MACHINE will be
                   1777: detected and used automatically.
1.20      lukem    1778: .Pp
1.103     apb      1779: See the
                   1780: .Cm list-arch
                   1781: operation for a way to get a list of valid
                   1782: .Sy MACHINE
1.20      lukem    1783: and
1.103     apb      1784: .Sy MACHINE_ARCH
                   1785: settings.
1.30      lukem    1786: .
                   1787: .It Fl N Ar noiselevel
                   1788: Set the
                   1789: .Dq noisyness
1.31      lukem    1790: level of the build, by setting
                   1791: .Sy MAKEVERBOSE
                   1792: to
                   1793: .Ar noiselevel .
1.1       lukem    1794: .
1.4       lukem    1795: .It Fl n
1.1       lukem    1796: Show the commands that would be executed by
                   1797: .Sy build.sh ,
1.6       wiz      1798: but do not make any changes.
                   1799: This is similar in concept to
1.1       lukem    1800: .Dq make -n .
                   1801: .
1.4       lukem    1802: .It Fl O Ar obj
1.1       lukem    1803: Create an appropriate transform macro for
                   1804: .Sy MAKEOBJDIR
                   1805: that will place the built object files under
1.4       lukem    1806: .Ar obj .
1.77      apb      1807: Unsets
                   1808: .Sy MAKEOBJDIRPREFIX .
                   1809: .Pp
1.1       lukem    1810: For instance, a setting of
1.61      apb      1811: .Dq Fl O Pa /usr/obj
1.1       lukem    1812: will place build-time files under
1.61      apb      1813: .Pa /usr/obj/bin ,
                   1814: .Pa /usr/obj/lib ,
                   1815: .Pa /usr/obj/usr.bin ,
1.1       lukem    1816: and so forth.
1.77      apb      1817: .Pp
1.61      apb      1818: If a relative path is specified, it will be converted to an
                   1819: absolute path before being used.
1.77      apb      1820: .Sy build.sh
                   1821: imposes the restriction that the argument to the
                   1822: .Fl O
                   1823: option must not contain a
                   1824: .Dq \&$
                   1825: (dollar sign)
                   1826: character.
                   1827: If the directory does not already exist,
                   1828: .Sy build.sh
                   1829: will create it.
1.61      apb      1830: .Pp
                   1831: In normal use, exactly one of the
                   1832: .Fl M
                   1833: or
                   1834: .Fl O
                   1835: options should be specified.
1.67      apb      1836: If neither
1.61      apb      1837: .Fl M
                   1838: nor
                   1839: .Fl O
                   1840: is specified, then a default object directory will be chosen
                   1841: according to rules in
1.67      apb      1842: .Aq bsd.obj.mk .
                   1843: Relying on this default is not recommended because
                   1844: it is determined by complex rules that are influenced
                   1845: by the values of several variables and
                   1846: by the location of the source directory.
1.104     apb      1847: .Pp
                   1848: Note that placing the
                   1849: .Ar obj
                   1850: directory location outside of the default source tree hierarchy makes
                   1851: it easier to manually clear out old files in the event the
                   1852: .Dq make cleandir
                   1853: operation is unable to do so.
                   1854: (See
                   1855: .Sx CAVEATS
                   1856: below.)
                   1857: .Pp
                   1858: Note also that use of one of
                   1859: .Fl M
                   1860: or
                   1861: .Fl O
                   1862: is the only means of building multiple machine architecture userlands
                   1863: from the same source tree without cleaning between builds (in which
                   1864: case, one would specify distinct
                   1865: .Ar obj
                   1866: locations for each).
1.4       lukem    1867: .It Fl o
                   1868: Set the value of
                   1869: .Sy MKOBJDIRS
                   1870: to
                   1871: .Dq no .
1.21      lukem    1872: Otherwise, it will be automatically set to
1.57      dholland 1873: .Dq yes .
                   1874: This default is opposite to the behaviour when not using
                   1875: .Sy build.sh .
1.4       lukem    1876: .
                   1877: .It Fl R Ar rel
1.1       lukem    1878: Set the value of
                   1879: .Sy RELEASEDIR
                   1880: to
1.4       lukem    1881: .Ar rel .
1.46      apb      1882: If a relative path is specified, it will be converted to an
                   1883: absolute path before being used.
1.1       lukem    1884: .
1.4       lukem    1885: .It Fl r
                   1886: Remove the contents of
                   1887: .Sy DESTDIR
                   1888: and
                   1889: .Sy TOOLDIR
1.6       wiz      1890: before building (provides a clean starting point).
                   1891: This will skip deleting
1.4       lukem    1892: .Sy DESTDIR
                   1893: if building on a native system to the root directory.
                   1894: .
1.60      perry    1895: .It Fl S Ar seed
                   1896: Change the value of
                   1897: .Sy BUILDSEED
                   1898: to
                   1899: .Ar seed .
                   1900: This should rarely be necessary.
                   1901: .
1.4       lukem    1902: .It Fl T Ar tools
1.1       lukem    1903: Set the value of
                   1904: .Sy TOOLDIR
                   1905: to
1.4       lukem    1906: .Ar tools .
1.46      apb      1907: If a relative path is specified, it will be converted to an
                   1908: absolute path before being used.
1.1       lukem    1909: If set, the bootstrap
                   1910: .Dq make
1.57      dholland 1911: will only be rebuilt if the source files for
1.1       lukem    1912: .Xr make 1
1.57      dholland 1913: have changed.
1.1       lukem    1914: .
1.4       lukem    1915: .It Fl U
1.25      lukem    1916: Set
                   1917: .Sy MKUNPRIVED=yes .
1.1       lukem    1918: .
1.4       lukem    1919: .It Fl u
1.25      lukem    1920: Set
                   1921: .Sy MKUPDATE=yes .
1.8       lukem    1922: .
                   1923: .It Xo
                   1924: .Fl V
                   1925: .Sm off
                   1926: .Ar var
                   1927: .Li =
                   1928: .Op Ar value
                   1929: .Sm on
                   1930: .Xc
1.27      lukem    1931: Set the environment variable
1.8       lukem    1932: .Ar var
1.27      lukem    1933: to an optional
                   1934: .Ar value .
1.91      abs      1935: This is propagated to the
1.27      lukem    1936: .Sy \*[toolprefix]make
                   1937: wrapper.
1.4       lukem    1938: .
                   1939: .It Fl w Ar wrapper
1.27      lukem    1940: Create the
                   1941: .Sy \*[toolprefix]make
                   1942: wrapper script (see below) in a custom location,
1.4       lukem    1943: specified by
                   1944: .Ar wrapper .
                   1945: This allows, for instance, to place the wrapper in
                   1946: .Sy PATH
1.6       wiz      1947: automatically.
                   1948: Note that
1.4       lukem    1949: .Ar wrapper
                   1950: is the full name of the file, not just a directory name.
1.46      apb      1951: If a relative path is specified, it will be converted to an
                   1952: absolute path before being used.
1.4       lukem    1953: .
1.34      lukem    1954: .It Fl X Ar x11src
                   1955: Set the value of
                   1956: .Sy X11SRCDIR
                   1957: to
                   1958: .Ar x11src .
1.46      apb      1959: If a relative path is specified, it will be converted to an
                   1960: absolute path before being used.
1.34      lukem    1961: .
                   1962: .It Fl x
                   1963: Set
                   1964: .Sy MKX11=yes .
                   1965: .
1.107   ! apb      1966: .It Fl Y Ar extsrcdir
        !          1967: Set the value of
        !          1968: .Sy EXTSRCSRCDIR
        !          1969: to
        !          1970: .Ar extsrcdir .
        !          1971: If a relative path is specified, it will be converted to an
        !          1972: absolute path before being used.
        !          1973: .
        !          1974: .It Fl y
        !          1975: Set
        !          1976: .Sy MKEXTSRC=yes .
        !          1977: .
1.27      lukem    1978: .It Fl Z Ar var
                   1979: Unset ("zap") the environment variable
                   1980: .Ar var .
1.91      abs      1981: This is propagated to the
1.27      lukem    1982: .Sy \*[toolprefix]make
                   1983: wrapper.
                   1984: .
1.1       lukem    1985: .El
                   1986: .
1.13      lukem    1987: .Ss The \*q\*[toolprefix]make-MACHINE\*q wrapper script
1.1       lukem    1988: .
                   1989: If using the
                   1990: .Sy build.sh
                   1991: script to build
                   1992: .Nx ,
                   1993: a
1.13      lukem    1994: .Sy \*[toolprefix]make-MACHINE
1.1       lukem    1995: script will be created in
1.99      wiz      1996: .Sy TOOLDIR Ns Pa /bin
1.1       lukem    1997: upon the first build to assist in building subtrees on a cross-compile
                   1998: host.
                   1999: .Pp
1.13      lukem    2000: .Sy \*[toolprefix]make-MACHINE
1.1       lukem    2001: can be invoked in lieu of
                   2002: .Xr make 1 ,
                   2003: and will instead call the up-to-date version of
1.13      lukem    2004: .Dq \*[toolprefix]make
1.1       lukem    2005: installed into
1.99      wiz      2006: .Sy TOOLDIR Ns Pa /bin
1.1       lukem    2007: with several key variables pre-set, including
                   2008: .Sy MACHINE , MACHINE_ARCH ,
                   2009: and
                   2010: .Sy TOOLDIR .
1.57      dholland 2011: .Sy \*[toolprefix]make-MACHINE
1.27      lukem    2012: will also set variables specified with
                   2013: .Fl V ,
                   2014: and unset variables specified with
                   2015: .Fl Z .
                   2016: .Pp
1.1       lukem    2017: This script can be symlinked into a directory listed in
                   2018: .Sy PATH ,
                   2019: or called with an absolute path.
1.2       lukem    2020: .
                   2021: .Sh EXAMPLES
1.10      lukem    2022: .
1.15      lukem    2023: .Bl -enum
1.9       lukem    2024: .
1.15      lukem    2025: .It
1.67      apb      2026: .Li "% ./build.sh [options] tools kernel=GENERIC"
1.15      lukem    2027: .Pp
1.2       lukem    2028: Build a new toolchain, and use the new toolchain to
                   2029: configure and build a new GENERIC kernel.
1.9       lukem    2030: .
1.15      lukem    2031: .It
1.67      apb      2032: .Li "% ./build.sh [options] -U distribution"
1.15      lukem    2033: .Pp
1.2       lukem    2034: Using unprivileged mode,
1.17      lukem    2035: build a complete distribution to a
                   2036: .Sy DESTDIR
                   2037: directory that
                   2038: .Sy build.sh
                   2039: selects (and will display).
1.9       lukem    2040: .
1.15      lukem    2041: .It
1.67      apb      2042: .Li "# ./build.sh [options] -U install=/"
1.15      lukem    2043: .Pp
1.16      lukem    2044: As root, install to
                   2045: .Pa /
                   2046: the distribution that was built
                   2047: by example 2.
1.15      lukem    2048: Even though this is run as root,
1.9       lukem    2049: .Fl U
                   2050: is required so that the permissions stored in
1.17      lukem    2051: .Sy DESTDIR Ns Pa /METALOG
1.9       lukem    2052: are correctly applied to the files as they're copied to
1.15      lukem    2053: .Pa / .
1.9       lukem    2054: .
1.15      lukem    2055: .It
1.67      apb      2056: .Li "% ./build.sh [options] -U -u release"
1.15      lukem    2057: .Pp
1.2       lukem    2058: Using unprivileged mode,
1.17      lukem    2059: build a complete release to
                   2060: .Sy DESTDIR
                   2061: and
                   2062: .Sy RELEASEDIR
                   2063: directories that
                   2064: .Sy build.sh
                   2065: selects (and will display).
1.25      lukem    2066: .Sy MKUPDATE=yes
1.15      lukem    2067: .Pq Fl u
                   2068: is set to prevent the
                   2069: .Dq make cleandir ,
                   2070: so that if this is run after example 2, it doesn't need to redo that
                   2071: portion of the release build.
1.2       lukem    2072: .El
1.1       lukem    2073: .
                   2074: .Sh OBSOLETE VARIABLES
                   2075: .
                   2076: .Bl -tag -width "NBUILDJOBS"
                   2077: .
                   2078: .It Sy NBUILDJOBS
1.91      abs      2079: Use the
1.1       lukem    2080: .Xr make 1
                   2081: option
1.57      dholland 2082: .Fl j
1.1       lukem    2083: instead.
                   2084: .
                   2085: .It Sy USE_NEW_TOOLCHAIN
                   2086: The new toolchain is now the default.
                   2087: To disable, use
                   2088: .Sy TOOLCHAIN_MISSING=yes .
                   2089: .El
                   2090: .Sh SEE ALSO
                   2091: .Xr make 1 ,
                   2092: .Xr hier 7 ,
1.42      apb      2093: .Xr release 7 ,
1.48      apb      2094: .Xr etcupdate 8 ,
                   2095: .Xr postinstall 8 ,
1.49      apb      2096: .Xr sysinst 8 ,
1.43      apb      2097: .Pa pkgsrc/sysutils/cdrtools
1.1       lukem    2098: .
                   2099: .Sh HISTORY
                   2100: .
                   2101: The
                   2102: .Nm build.sh
                   2103: based build scheme was introduced for
                   2104: .Nx 1.6
                   2105: as
                   2106: .Sy USE_NEW_TOOLCHAIN ,
                   2107: and re-worked to
                   2108: .Sy TOOLCHAIN_MISSING
                   2109: after that.
1.104     apb      2110: .
                   2111: .Sh CAVEATS
                   2112: .
                   2113: After significant updates to third-party components in the source
                   2114: tree, the
                   2115: .Dq make cleandir
                   2116: operation may be insufficient to clean out old files in object
                   2117: directories.
                   2118: Instead, one may have to manually remove the files.
                   2119: Consult the
                   2120: .Pa UPDATING
                   2121: file for notices concerning this.

CVSweb <webmaster@jp.NetBSD.org>