BUILDING: list known mk.conf vars. tweak section headers

List known supported and obsolete mk.conf(5) variables,
so that searches in this document at least find them.
This partially reverts my revision 1.144 on 2023-06-12
which completely removed the duplication with mk.conf(5).

Remove quote characters from some section headings;
it makes it harder to search for a section by known name
when rendering in markup variations that use smart quotes.

BUILDING: clarify environ vs mk.conf behaviour

Document that variables set in the environment or the
nbmake-MACHINE wrapper script don't override variable
assignments in mk.conf(5), and that using ?= in mk.conf
allows environment / nbmake-MACHINE variables to override
mk.conf.

Consistently refer to "nbmake-MACHINE wrapper script".

BUILDING: consistency fix

build.sh: use mk.conf (if present) as MAKECONF

Set MAKECONF to mk.conf in the same directory as build.sh
(i.e., the top of the source tree) if mk.conf is present.
This means unprivileged users can benefit from mk.conf(5)
semantics without write privileges to /etc/mk.conf, and
also simplifies per-source-directory configuration.

Fail early if $MAKECONF is empty, since build.sh will fail
anyway after rebuilding nbmake.

Ensure that the computed MAKECONF isn't empty, and then
always set MAKECONF in the makewrapper (nbmake-$MACHINE).

Improve some formatting consistency in BUILDING.mdoc,
(even if BUILDING is generated without markup).

BUILDING: wording tweaks

BUILDING: remove duplication from mk.conf(5)

Remove all "make" variables / mk.conf(5) variables already documented
in mk.conf(5). The duplication was a maintenance headache, as I've
experienced over recent weeks getting the build documentation up to
date.

Add notes clarifying that manual page references are to the NetBSD
manual pages, not to the host manual pages, and how to format from
source, or find online at https://man.netbsd.org.

Add explicit links to the mdoc(7) in-tree source for mk.conf(5),
hier(7), and release(7) because those are directly relevant to the host
build information in BUILDING.

Note: We don't normally need these notes for native documentation,
but BUILDING is intended for users on host systems which might not
be NetBSD(-current).

Add missing defaults.

BUILDING: update from mk.conf(5). reorder

Sync variable entries from mk.conf(5).

Merge the "make variables for full builds" section into the previous.
Having two separate sections and some entries duplicated was confusing
when searching for variables.

more NBUILDJOBS deprecation

The NBUILDJOBS option was deprecated in 2002;
there's no need to keep warning about it,
remove from params / show-params,
and only document as obsolete.

BUILDING: editorial

MKX11=yes wants MKINET6=yes

Change the width of the variable lists to 14n (from 15n)
so that when the lists are rendered and then left aligned,
the column is 16 characters (aka 2 tabs) which makes
copypasta to bsd.README easier.

BUILDING: update from canonical mk.conf(5)

Incorporate content and styles updates for mk.conf entries
from share/man/man5/mk.conf.5, which is the canonical
reference for mk.conf.

Add: BSDOBJDIR, BSDSRCDIR, EXTERNAL_TOOLCHAIN, MKDEBUGKERNEL,
MKDEBUGTOOLS, MKHTML, MKLINKLIB, MKOBJDIRS, TOOLCHAIN_MISSING,
NETBSDSRCDIR

It's for further study as to whether we just replace the
most of subsection "make" variables with a link to mk.conf(5).

Style:
- Add more .de macros per mk.conf.5.
- Order list items alphabetically. When multiple items are present
in a list item, sort within the item first.
- More cross-references.

build.sh: MAKECONF and mk.conf(5) improvements

Move MAKECONF to the Environment variables section.
Add mk.conf(5) cross-references.
Make Notes more obvious.
Fix mandoc lint.

BUILDING: TMPDIR must not be noexec

Describe $TMPDIR as used by build.sh, and
add a note that it can't be mounted noexec.

PR toolchain/44459

build.sh, BUILDING: consistency improvements

Consistently use "show", instead of sometimes using "display" or "print".
Fix mdoc markup (even though BUILDING is raw text).
Document help, -P, -?

BUILDING: update upstream, regen

doc/BUILDING.mdoc is the upstream for BUILDING, so add recent changes
in the latter to the former, formatting correctly.

Move INSTALLBOOT_UBOOT_PATHS to Environment variables.
Move INSTALLBOOT_BOARDS to "make" variables for full builds.
Add installboot(8) cross-reference.

fix documentation for MKLINT

Since share/mk/bsd.own.mk 1.749 from 2013-08-26, MKLINT defaults to no.

By default, do not install any bootable images.

The previous commit introduced the ability to install a set of
bootable images as a normal part of a release build. While this made
it easy to install bootable images, the contents of a release build
depend on whether or not U-Boot packages are installed in /usr/pkgsrc,
which is the default location searched by installboot(8).

This commit requires users to explicitly list the bootable images to
be installed, which by default is none (i.e., prior behavior).

Create bootable images in ${RELEASEDIR}/${RELEASEMACHINEDIR}/binary/gzimg.

Release builds for arm platforms create compressed images in
${RELEASEDIR}/${RELEASEMACHINEDIR}/binary/gzimg. However, in some
cases, e.g., armv7.img.gz, they are not bootable. Consequently, boot
blocks must be manually installed in the images, which is an extra
barrier for testing systems or adopting NetBSD. This has prompted
creation of external repositories, e.g., armbsd.org, to host a
collection of bootable images. However, this does not ease the burden
on developers compiling their own systems; for them, manual
installation of boot blocks is still required.

For arm platforms, etc/etc.evbarm/Makefile.inc contains the commands
used to create system images. Because installboot(8) can write boot
blocks directly to system images, a loop through possible boards can
create a series of bootable images during the normal build process.

In the case of many arm platforms, installboot(8) uses U-Boot boot
blocks, which are not part of the NetBSD source code. Developers can,
however, install as many U-Boot boot blocks as desired, either in the
default location of /usr/pkg/share/u-boot or in a set of directories
pointed to by the U-Boot search path, the INSTALLBOOT_UBOOT_PATHS
environment variable. For each board with an available boot block, a
board-specific bootable image will be created in
${RELEASEDIR}/${RELEASEMACHINEDIR}/binary/gzimg. If a boot block is
not available, which is the typical situation currently, no additional
image will be created.

This facility creates opportunities to build bootable images for any
number of boards within the scope of a standard release build.
However, that is not required and will not occur without the
intervention of installing U-Boot boot blocks prior to the build.

BUILDING: regen for removal of extsrc/

s/knowlege/knowledge/

Rename:
MKKDEBUG -> MKDEBUGKERNEL
MKTOOLSDEBUG -> MKDEBUGTOOLS
while keeping compatibility with the old names. Add missing documentation.
Now all debugging tunables are prefixed with MKDEBUG.

Reintroduce the support of MKCATPAGES

Requested by <mrg>

Remove the support for MKCATPAGES

It was optional since 1999 and disabled by default since 2012.

Proposed on tech-userlevel@.

Document CPUFLAGS here (it's already documented in share/mk/bsd.README).
This will address the initial concern in PR port-alpha/55545.

Mention HOST_CFLAGS and HOST_CXXFLAGS.

Bump date and regen for BUILDING.mdoc revision 1.127
that introduced build.sh -c <compiler> option.

Fix a typo

Reported by Tobias Ulmer via netbsd-docs@ ML, thanks!

regen

branches: 1.133.2;
Re-add files that were accidentally deleted in my previous commit.

Synch with HEAD

branches: 1.131.2;
regen

regen

regen

regen

regen

regen using regen target in doc.

Introduce MKSTRIPSYM build option

If it's yes, all local symbols of shared libraries are stripped
(default). If it's no, only temporary local symbols are stripped;
for example, symbols of static functions are kept. Keeping such
symbols is useful on using DTrace for userland libraries and
getting a backtrace from a rump server loading modules (shared
libraries).

Proposed and discussed on tech-kern and tech-toolchain

regen

The default values for MKPIC are yes and no for sh3 and m68000, respectively.
Bump date.

branches: 1.122.2; 1.122.4;
Document MKREPRO_TIMESTAMP.

remove the xfree86 reachover makefiles and the vast majority of
the support in the rest of the source tree.

X11 sets could use some cleaning up perhaps (just deletion, as
we've never really marked the old X11R6 as obsolete for native
xorg using platforms so far either.)

Update to reflect changes made in rev 1.398 of src/etc/Makefile

regen

regen

regen

regen

regen from doc/BUILDING.mdoc revision 1.107.
This reinstates documentation for "extsrc" which was lost in 2009.

fourth time's the charm, i guess. when committing a generated file,
it's best to use the latest revision of the source file (hi uebs!)

regen to include changes from revision 1.105 of doc/BUILDING.mdoc

regen

Expand TABs.

Document the new "kernels" operation, prompted by joerg@.

regen

branches: 1.109.2;
regen BUILDING from doc/BUILDING.mdoc

BUILDINFO part6: regen BUILDING from doc/BUILDING.mdoc

Regen from doc/BUILDING.mdoc;1.100:
Improve documentation for BUILDID.

regen

branches: 1.105.4;
regen using 'make regen' from src/doc.

regen (using mandoc doc/BUILDING.mdoc > BUILDING -- let me know
if a different way is preferred, I see that it now contains formatting).

regen

regen

branches: 1.101.2;
regen using 'make regen' in doc/

Document MKREPRO using joerg's wording.

Add a missing period.

branches: 1.98.2;
Regen from revision 1.87 of doc/BUILDING.mdoc.

Add "live-image" and "install-image" target support to build.sh.

"live-image" target builds pre-installed disk images that can be used on
emulators or boot from USB memory sticks to try NetBSD without installation.
Currently amd64, i386, pmax, sparc, sparc64, sun2, sun3, and vax
(which have working emulators and don't require extra tools like preparing
msdosfs or partitioning MD label structures) support this target.

"install-image" target builds an bootable installation disk image that can
be used as an install CD but burned into USB memory sticks etc.
Current only amd64 and i386 (which would support USB boot) have this target.

For more details (and known issue) see following posts on netbsd-bugs@:
http://mail-index.NetBSD.org/netbsd-bugs/2011/08/06/msg023639.html
http://mail-index.NetBSD.org/netbsd-bugs/2011/09/23/msg024207.html
http://mail-index.NetBSD.org/netbsd-bugs/2011/12/07/msg025166.html
http://mail-index.NetBSD.org/netbsd-bugs/2011/12/08/msg025178.html

No particular comments about implementation, and
"go ahead" comments from mrg@, riz@ and christos@.

Closes PR toolchain/45153 and PR misc/45155.

branches: 1.96.2;
Add tests for the shell under which build.sh is run. If the
shell fails the tests, then build.sh tries to re-exec itself
under a more suitable shell.

Revisions 1.92 and 1.93 of src/BUILDING were not reflected in
src/doc/BUILDING.mdoc, so those changes were lost when src/BUILDING
was regenerated in revision 1.94.

Now update src/doc/BUILDING.mdoc and regenerate src/BUILDING to
reinstate the lost changes. (I also edited one of the changes, to use
the phrase "space-separated list" for consistency with other parts of
the document.)

The original changes were:

Add description of MKKMOD, part of PR misc/45216

Pass down INSTALLSETS variable to installsets target. Use :Q to escape
shell meta-characters, as the variable contains a list of sets, separated
by spaces.

$ ./build.sh -V INSTALLSETS="base etc" install=idir

should now work as expected.

Reviewed by apb@ on tech-toolchain.

Allow MAKEFLAGS to be set via build.sh -V. Somebody asked for this
in 2008.

Also add comments above a few functions in build.sh, and bump copyright
dates.

Add description of MKKMOD, part of PR misc/45216

Pass down INSTALLSETS variable to installsets target. Use :Q to escape
shell meta-characters, as the variable contains a list of sets, separated
by spaces.

$ ./build.sh -V INSTALLSETS="base etc" install=idir

should now work as expected.

Reviewed by apb@ on tech-toolchain.

branches: 1.91.2;
remove the MKSUBPIXEL/MKTTINTERP options; they're going away.

regenerate.

Support "extsrc", externally added programs and libraries. Users can write
their own reach-overs, cross-build, install, and get set files just like base
and X11 / X.org. (These sets are not included as TNF releases.)

If ${NETBDSRCDIR}/../xsrc exists, then use it as the default value
of X11SRCDIR. If it doesn't exist, then use /usr/xsrc as before.

OK mrg

* Use a more robust method of creating the top level object directory.
Use getmakevar to expand MAKEOBJDIRPREFIX or MAKEOBJDIR, or (if
neither of those variables is set) use a non-recursive "make obj" in
the top level source directory.

* Do not let TOP_objdir default to ${TOP}. It's now set only by the
-M or -O command line options, or after using getmakevar to expand
MAKEOBJDIRPREFIX or MAKEOBJDIR.

* Make try_set_TOOLDIR handle MAKEOBJDIRPERFIX passed from the
environment. It runs too early to use getmakevar, so it will not work
if the value contains embedded '${...}' variable references.

* Use '$TOOLDIR' (with a literal '$') instead of 'nonexistent' in
a message when rebuilding make when TOOLDIR is not yet known.

Allow build.sh "-C cdextra" option to be specified multiple times.

Add a modules operation to build.sh, which builds and installs kernel modules
into DESTDIR.

This is based on the patch provided by tsutsui@ on tech-toolchain@.

regen

regen

Introduce MKSUBPIXEL, which allows enabling subpixel rendering code
in FreeType.

branches: 1.82.2;
be explicit about MAKEOBJDIR and MAKEOBJDIRPREFIX not being for
mk.conf or ${MAKECONF}.

revert sparc back to default of XFree86 at the request of macallan.

Add support for new MAKEVERBOSE levels 3 and 4. The complete list is now:

0 Minimal output ("quiet")
1 Describe what is occurring
2 Describe what is occurring and echo the actual command
3 Ignore the effect of the "@" prefix in make commands
4 Trace shell commands using the shell's -x flag

The default remains MAKEVERBOSE=2.

- retire MKXORG from public use
- introduce X11FLAVOUR to choose src/x11 vs src/external/mit/xorg
for the X11 to build if MKX11=yes is set. it takes the values
of either Xorg or XFree86.
- default to Xorg on alpha, i386, macppc, shark, sparc and sparc64
- remove MKXORG_WITH_XSRC_XSERVER, unused and never useful

branches: 1.78.2;
regen for recent change to examples and objdir advice,
and for the older MKSTRIPIDENT change.

regen for MKHTML

Improve support for MKXORG!=no to enable builds into external/mit/xorg.
This will be mutually exclusive to MKX11!=no.

Document "build.sh cleandir".
Fix formatting nit.
Remove BUGS; all the in-tree platforms are using build.sh now.

* Suggest a "-j" value between 1+NCPU and 2*NCPU for the fastest builds.
* Remove some duplicated content that appeared in both the section about
make's -j flag and the section about build.sh's -j flag.

* Add more detail for build.sh -M and -O options.
* Mention new default when source is /usr/src but build.sh is run
with neither -M nor -O.

Builds now use "BUILDSEED" so that c++ binaries are reproduceable.
By default BUILDSEED is set to NetBSD-{majorversion} -- a -S flag may
be used to change it.

Discussed on tech-toolchain.

branches: 1.71.4;
Correct/clarify the default setting of USETOOLS in the previous version.
Noted by apb.

Assorted updates and clarifications, grammar fixes and wording improvements,
and so on. Significant highlights:
- mention src/tests and reference atf;
- provide examples of MACHINE and MACHINE_ARCH;
- mention that MKOBJ=no is not recommended;
- correct the description of the default setting of USETOOLS;
- document the interactions of build.sh -[uo] with various things;
- document the interactions of build.sh tools and kernel=FOO;
- use a lot fewer parentheses.
Discussed on netbsd-docs.

Consistently document RELEASEDIR/RELEASEMACHINEDIR.

Mention that "build" and "distribution" do not build nor install (to DESTDIR)
a kernel.

branches: 1.67.4;
Add support for CDBUILDEXTRA which acts like CDEXTRA to add extra items
to the CD-ROM image.
Make CDEXTRA and CDBUILDEXTRA be able to contain lists of files and directories
which are added in turn.
Add support for CDEXTRA_SKIP which contains a list of fnmatch(3) items to
skip during the copy. This is _very_ useful for skipping CVS dirs for example.
CDBUILDEXTRA and CDEXTRA_SKIP are to be used in Makefiles creating the images,
CDEXTRA remains to be used from build.sh.
Update documentation and build.sh help text to show that -C can be used to
specify a list of files and directories rather than just a single dir.

Convert build.sh iso-dir=directory option to -C cddir as per jmmv@ on
source-changes.

Add an iso-dir=directory option. When combined with iso-image or
iso-image-source, it will cause directory to be added to the CD-ROM image.

describe new iso-image-source target

Remove STATUS paragraph which makes it sound like the build system is
half baked.

branches: 1.62.4;
Document recent changes to "make iso-image".

Document the fact that "make installworld" and "build.sh
installworld=..." do not install the etc or xetc sets. Suggest using
etcupdate(8) and postinstall(8) after installworld.

Try to clarify the description of build.sh -m mach.
Document new evbarm-eb and evbarm-el aliases.

branches: 1.59.2;
Clarify that DESTDIR/OBJDIR/etc are absolute paths, but build.sh
-D/-O/etc allows relative paths.

Closes PR 32345 by Andre Luiz de Oliveira.

Use ${HOST_SH} instead of the host system's /bin/sh wherever possible:

* Describe the HOST_SH variable, and the way build.sh attempts to set it.

* Suggest passing HOST_SH in the environment if /bin/sh is not a working
shell.

mkisofs is in pkgsrc/sysutils/cdrtools now, not pkgsrc/sysutils/cdrecord.
Reported by Jukka Salmi.

* Add an "iso-image" target in the top level Makefile,
which invokes make iso-image in the etc directory.
* Add an "iso-image" action in build.sh, which
invokes make iso-image.
* Document the above in doc/BUILDING.mdoc.
* Re-generate BUILDING.

Approved by christos

Bump date for syspkgs.

Document "make syspkgs" and "build.sh syspkgs".

Reviewed by agc

Document the environment variables for if you need to override or
manually select your compilers.
(And regen BUILDING from doc/BUILDING.mdoc.)

Fix some typo's/bad wording as highlighted in PR#27219

regen (Document -h. From Karsten Kruse in PR 25974.
While here, remove a duplicate sentence).

Document MKTTINTERP.

* Document build.sh -X and -x
* Document MKX11 and X11SRCDIR
* Remove note warning against cross-building from systems other than NetBSD;
it works on many other platforms.

Note tools/compat/README as the place to get notes from non-native cross builds

Change -v to -V in the following section:

"Print make(1)'s idea of the value of var. Does not build any targets."

To reflect reality.

Found by Tomasz Marciniak <Tomasz.Marciniak@felix.fizyka.amu.edu.pl>, thanks!

Improve how build.sh -N and MAKEVERBOSE interoperate;
rather than adding '-s' to make's command line in the makewrapper,
use the .SILENT target based on MAKEVERBOSE's value.

This means that you can do:
./build.sh -N 1 makewrapper

$TOOLDIR/bin/nbmake-$MACHINE
# runs at MAKEVERBOSE==1, with command lines suppressed

$TOOLDIR/bin/nbmake-$MACHINE MAKEVERBOSE=2
# runs at MAKEVERBOSE==2 for this invocation, with command lines shown

Implement build -N noisy, which sets MAKEVERBOSE to noisy and adds
`-s' to MAKEFLAGS for noisy < 2.

regenerate for "%" prompt update

Backout the previous commit

Remove # from the example.

fix description of MAKEOBJDIR. from Martin Husemann

Add build.sh -Z var, to unset a variable and ensure it's unset in makewrapper.
For -M MAKEOBJDIRPREFIX, unset MAKEOBJDIR.
For -O MAKEOBJDIR, unset MAKEOBJDIRPREFIX.

fix default location of TOOLDIR

Update for the MKUNPRIVED/MKUPDATE changes.

rebuild with new groff

attempt to clarify how MAKEOBJDIR{,PREFIX} may be provided ...
(this document needs a rototill, which i may get to whilst writing a
paper about build.sh)

all:
* add "releasekernel=conf", to install a gzipped copy of the kernels
built by "kernel=conf" to RELEASEDIR/MACHINE/binary/kernel

build.sh:
* be more consistent in various status messages
* move the {release,}kernel=conf conf parsing code into getkernelconf()
and use in both buildkernel() and releasekernel()
* only warn once when building multiple kernels without updating the tools

For normal builds, MKOBJDIRS default to `no' (not `yes').
It's only build.sh that sets this to `yes' by default.
Noted by OGAWA Takaya in [toolchain/19823]

improve description of how "build.sh -m mach" sets the default
MACHINE_ARCH, and list the special cases that this does not occur for.

crank date for previous

Add "sourcesets" argument/target, which builds source sets into
RELEASEDIR/source/sets

build.sh now provides defaults for DESTDIR and RELEASEDIR if not expert mode.
Remove -D and -R from EXAMPLES since they're not necessary any more.

Fix example 3; the build.sh target is "install" not "installworld".
Improve description.
Noted by Valeriy Ushakov (uwe@) in private email.

attempt to further improve and clarify the examples...

Prefix various paths with 'DESTDIR', to highlight that the DESTDIR
is taken into account.

allow toolprefix to be easily changed

Various improvements per discussion with Alan Barrett.

- Add "sets" top-level Makefile target and build.sh operation.
[Latter suggested by Julio Merino in private email]
- Add "help" build.sh operation.

Change build.sh so that at least one operation is required.
Add "makewrapper" operation to build.sh.
[The above changes were suggested by Alan Barrett on current-users@]

Fail if building as non-root unless: UNPRIVED is set, -U is given, or -E
(expert mode) is given.
[Suggested by James Wetterau in private email]

Improve the examples in BUILDING.

Rework how build.sh functions, so that command line options set various
parameters, and a list of "operations" defines what to do.
The full usage is show below. Notes:
`-b' has been deprecated (it always occurs now)
`-d' is replaced by "distribution"
`-R rel' onlys sets RELEASEDIR; use "release" to build a release
`-k kern' has been replaced by "kernel=kern"
`-i idir' has been replaced by "install=idir"
-r now occurs before nbmake is rebuilt

Add a copyright (long due!). Rework the code to (a KNF inspired) ShellNF.
Use functions appropriately. Allow `nb' prefix to be easily changed to
something else. Solve world peace (just kidding)

This is part of the (never achievable) goal of attempting to make
NetBSD easier to build...


--8<-- new usage follows --8<--

Usage: build.sh [-EnorUu] [-a arch] [-B buildid] [-D dest] [-j njob] [-M obj]
[-m mach] [-O obj] [-R release] [-T tools] [-V var=[value]]
[-w wrapper] [operation [...] ]

System build operations (all imply "obj" and "tools"):
build Run "make build"
distribution Run "make distribution" (includes etc/ files)
release Run "make release" (includes kernels & distrib media)

Other operations:
obj Run "make obj" (default unless -o)
tools Build and install tools
kernel=conf Build kernel with config file `conf'
install=idir Run "make installworld" to `idir'
(useful after 'distribution' or 'release')

Options:
-a arch Set MACHINE_ARCH to arch (otherwise deduced from MACHINE)
-B buildId Set BUILDID to buildId
-D dest Set DESTDIR to dest
-E Set "expert" mode; disables some DESTDIR checks
-j njob Run up to njob jobs in parallel; see make(1)
-M obj Set obj root directory to obj (sets MAKEOBJDIRPREFIX)
-m mach Set MACHINE to mach (not required if NetBSD native)
-n Show commands that would be executed, but do not execute them
-O obj Set obj root directory to obj (sets a MAKEOBJDIR pattern)
-o Set MKOBJDIRS=no (do not create objdirs at start of build)
-R release Set RELEASEDIR to release
-r Remove contents of TOOLDIR and DESTDIR before building
-T tools Set TOOLDIR to tools. If unset, and TOOLDIR is not set in
the environment, nbmake will be (re)built unconditionally.
-U Set UNPRIVED
-u Set UPDATE
-V v=[val] Set variable `v' to `val'
-w wrapper Create nbmake script as wrapper
(default: ${TOOLDIR}/bin/nbmake-${MACHINE})

Add "-V var=[value]", for setting arbitrary variables which will also
be added to the nbmake-${MACHINE} wrapper.
Useful for setting RELEASEDIR, without -R's habit of building a release.

Document:
* build.sh -i idir
* top level targets: distribution, buildworld, installworld
* top level variables: INSTALLWORLDDIR

Add -E - "expert mode". If this is not specified, builds to DESTDIR=/ are
not permitted.
By using this flag, you are taking responsibility for any issues that
may occur because of this...

- be consistent about option ordering in build.sh usage display
- use Fl and Ar instead of Sy and Em to format options

Update location of BUILDING.mdoc.

regen for build.sh -k

regen for: USE_NEW_TOOLCHAIN was replaced with TOOLCHAIN_MISSING

Expand on the difference between ``build.sh -d'' and ``make install'',
as requested by Brian Stark in PR toolchain/18228 (which this closes).

Remove duplicate 'files'. From Ryo HAYASAKA in toolchain/17674.

branches: 1.12.2;
add "-M makeobjdirprefix" to build.sh

Move the METALOG from ${_SRC_TOP_OBJ_} to ${DESTDIR}.

There were too many synchronisation problems with using the former;
including situations such as a "make clean" performed between two
installs to the same DESTDIR would result in a truncated METALOG and
the resultant sets would be missing stuff such as include files that
don't get reinstalled if they haven't changed, even with !UPDATE.

Re-gen.

Add a -B option to set the BUILDID for the build. This also causes
the make(1) wrapper script to be named "nbmake-MACHINE-BUILDID".

document various supported environment variables, including MAKEOBJDIRPREFIX

document:
- make's UNPRIVED support
- build.sh's -U support
- the build system currently needs to build onto a file system with
long file name and hard link support

Document the -d option to build.sh

Note only <bsd.own.mk> as the authority for determining whether the new
BUILDING instructions should be used.

Turn off host-specific objdirs by default. Set MKHOSTOBJ=yes to enable.

Major overhaul of src/tools and host toolchain. Summary of changes:

* Rewrite src/tools Make logic to work like the rest of the tree wrt
"dependall" and "install". The old "make build" hack is gone.

* Remove the MKTOOLS logic. This was linked to the "make build" hack,
and was only needed because TOOLDIR originally had no writable default.

* Redo the GNU configure/make logic to make it fit reasonably in a
BSD make wrapper. Use new ${.ALLTARGETS} variable to scan for
targets in $(srcdir), and mark them with .MADE: to prevent rebuilding.

* Only build cross tools in src/tools; remove some messy logic in
src/usr.* and src/gnu/usr.* that would do target filename rewriting
(improves consistency and readability).

* Add the ability to build cross gdb at tool build time by setting
MKCROSSGDB (default no) to "yes" in mk.conf.

* Add src/tools/groff and set up paths to work with this cross groff.

Remove mention of BUILDLING.html, and follow rename of BUILDING.txt to
BUILDING.
Noted by Love <lha@stacken.kth.se> on tech-toolchain.

By popular demand, one preformatted version of BUILDING, plaintext, no CRs.

BUILDING: list known mk.conf vars. tweak section headers

List known supported and obsolete mk.conf(5) variables,
so that searches in this document at least find them.
This partially reverts my revision 1.144 on 2023-06-12
which completely removed the duplication with mk.conf(5).

Remove quote characters from some section headings;
it makes it harder to search for a section by known name
when rendering in markup variations that use smart quotes.

BUILDING: clarify environ vs mk.conf behaviour

Document that variables set in the environment or the
nbmake-MACHINE wrapper script don't override variable
assignments in mk.conf(5), and that using ?= in mk.conf
allows environment / nbmake-MACHINE variables to override
mk.conf.

Consistently refer to "nbmake-MACHINE wrapper script".

BUILDING: consistency fix

build.sh: use mk.conf (if present) as MAKECONF

Set MAKECONF to mk.conf in the same directory as build.sh
(i.e., the top of the source tree) if mk.conf is present.
This means unprivileged users can benefit from mk.conf(5)
semantics without write privileges to /etc/mk.conf, and
also simplifies per-source-directory configuration.

Fail early if $MAKECONF is empty, since build.sh will fail
anyway after rebuilding nbmake.

Ensure that the computed MAKECONF isn't empty, and then
always set MAKECONF in the makewrapper (nbmake-$MACHINE).

Improve some formatting consistency in BUILDING.mdoc,
(even if BUILDING is generated without markup).

BUILDING: wording tweaks

BUILDING: remove duplication from mk.conf(5)

Remove all "make" variables / mk.conf(5) variables already documented
in mk.conf(5). The duplication was a maintenance headache, as I've
experienced over recent weeks getting the build documentation up to
date.

Add notes clarifying that manual page references are to the NetBSD
manual pages, not to the host manual pages, and how to format from
source, or find online at https://man.netbsd.org.

Add explicit links to the mdoc(7) in-tree source for mk.conf(5),
hier(7), and release(7) because those are directly relevant to the host
build information in BUILDING.

Note: We don't normally need these notes for native documentation,
but BUILDING is intended for users on host systems which might not
be NetBSD(-current).

Add missing defaults.

BUILDING: update from mk.conf(5). reorder

Sync variable entries from mk.conf(5).

Merge the "make variables for full builds" section into the previous.
Having two separate sections and some entries duplicated was confusing
when searching for variables.

more NBUILDJOBS deprecation

The NBUILDJOBS option was deprecated in 2002;
there's no need to keep warning about it,
remove from params / show-params,
and only document as obsolete.

BUILDING: editorial

MKX11=yes wants MKINET6=yes

Change the width of the variable lists to 14n (from 15n)
so that when the lists are rendered and then left aligned,
the column is 16 characters (aka 2 tabs) which makes
copypasta to bsd.README easier.

BUILDING: update from canonical mk.conf(5)

Incorporate content and styles updates for mk.conf entries
from share/man/man5/mk.conf.5, which is the canonical
reference for mk.conf.

Add: BSDOBJDIR, BSDSRCDIR, EXTERNAL_TOOLCHAIN, MKDEBUGKERNEL,
MKDEBUGTOOLS, MKHTML, MKLINKLIB, MKOBJDIRS, TOOLCHAIN_MISSING,
NETBSDSRCDIR

It's for further study as to whether we just replace the
most of subsection "make" variables with a link to mk.conf(5).

Style:
- Add more .de macros per mk.conf.5.
- Order list items alphabetically. When multiple items are present
in a list item, sort within the item first.
- More cross-references.

build.sh: MAKECONF and mk.conf(5) improvements

Move MAKECONF to the Environment variables section.
Add mk.conf(5) cross-references.
Make Notes more obvious.
Fix mandoc lint.

BUILDING: TMPDIR must not be noexec

Describe $TMPDIR as used by build.sh, and
add a note that it can't be mounted noexec.

PR toolchain/44459

build.sh, BUILDING: consistency improvements

Consistently use "show", instead of sometimes using "display" or "print".
Fix mdoc markup (even though BUILDING is raw text).
Document help, -P, -?

BUILDING: update upstream, regen

doc/BUILDING.mdoc is the upstream for BUILDING, so add recent changes
in the latter to the former, formatting correctly.

Move INSTALLBOOT_UBOOT_PATHS to Environment variables.
Move INSTALLBOOT_BOARDS to "make" variables for full builds.
Add installboot(8) cross-reference.

fix documentation for MKLINT

Since share/mk/bsd.own.mk 1.749 from 2013-08-26, MKLINT defaults to no.

By default, do not install any bootable images.

The previous commit introduced the ability to install a set of
bootable images as a normal part of a release build. While this made
it easy to install bootable images, the contents of a release build
depend on whether or not U-Boot packages are installed in /usr/pkgsrc,
which is the default location searched by installboot(8).

This commit requires users to explicitly list the bootable images to
be installed, which by default is none (i.e., prior behavior).

Create bootable images in ${RELEASEDIR}/${RELEASEMACHINEDIR}/binary/gzimg.

Release builds for arm platforms create compressed images in
${RELEASEDIR}/${RELEASEMACHINEDIR}/binary/gzimg. However, in some
cases, e.g., armv7.img.gz, they are not bootable. Consequently, boot
blocks must be manually installed in the images, which is an extra
barrier for testing systems or adopting NetBSD. This has prompted
creation of external repositories, e.g., armbsd.org, to host a
collection of bootable images. However, this does not ease the burden
on developers compiling their own systems; for them, manual
installation of boot blocks is still required.

For arm platforms, etc/etc.evbarm/Makefile.inc contains the commands
used to create system images. Because installboot(8) can write boot
blocks directly to system images, a loop through possible boards can
create a series of bootable images during the normal build process.

In the case of many arm platforms, installboot(8) uses U-Boot boot
blocks, which are not part of the NetBSD source code. Developers can,
however, install as many U-Boot boot blocks as desired, either in the
default location of /usr/pkg/share/u-boot or in a set of directories
pointed to by the U-Boot search path, the INSTALLBOOT_UBOOT_PATHS
environment variable. For each board with an available boot block, a
board-specific bootable image will be created in
${RELEASEDIR}/${RELEASEMACHINEDIR}/binary/gzimg. If a boot block is
not available, which is the typical situation currently, no additional
image will be created.

This facility creates opportunities to build bootable images for any
number of boards within the scope of a standard release build.
However, that is not required and will not occur without the
intervention of installing U-Boot boot blocks prior to the build.

BUILDING: regen for removal of extsrc/

s/knowlege/knowledge/

Rename:
MKKDEBUG -> MKDEBUGKERNEL
MKTOOLSDEBUG -> MKDEBUGTOOLS
while keeping compatibility with the old names. Add missing documentation.
Now all debugging tunables are prefixed with MKDEBUG.

Reintroduce the support of MKCATPAGES

Requested by <mrg>

Remove the support for MKCATPAGES

It was optional since 1999 and disabled by default since 2012.

Proposed on tech-userlevel@.

Document CPUFLAGS here (it's already documented in share/mk/bsd.README).
This will address the initial concern in PR port-alpha/55545.

Mention HOST_CFLAGS and HOST_CXXFLAGS.

Bump date and regen for BUILDING.mdoc revision 1.127
that introduced build.sh -c <compiler> option.

Fix a typo

Reported by Tobias Ulmer via netbsd-docs@ ML, thanks!

regen

branches: 1.133.2;
Re-add files that were accidentally deleted in my previous commit.

Synch with HEAD

branches: 1.131.2;
regen

regen

regen

regen

regen

regen using regen target in doc.

Introduce MKSTRIPSYM build option

If it's yes, all local symbols of shared libraries are stripped
(default). If it's no, only temporary local symbols are stripped;
for example, symbols of static functions are kept. Keeping such
symbols is useful on using DTrace for userland libraries and
getting a backtrace from a rump server loading modules (shared
libraries).

Proposed and discussed on tech-kern and tech-toolchain

regen

The default values for MKPIC are yes and no for sh3 and m68000, respectively.
Bump date.

branches: 1.122.2; 1.122.4;
Document MKREPRO_TIMESTAMP.

remove the xfree86 reachover makefiles and the vast majority of
the support in the rest of the source tree.

X11 sets could use some cleaning up perhaps (just deletion, as
we've never really marked the old X11R6 as obsolete for native
xorg using platforms so far either.)

Update to reflect changes made in rev 1.398 of src/etc/Makefile

regen

regen

regen

regen

regen from doc/BUILDING.mdoc revision 1.107.
This reinstates documentation for "extsrc" which was lost in 2009.

fourth time's the charm, i guess. when committing a generated file,
it's best to use the latest revision of the source file (hi uebs!)

regen to include changes from revision 1.105 of doc/BUILDING.mdoc

regen

Expand TABs.

Document the new "kernels" operation, prompted by joerg@.

regen

branches: 1.109.2;
regen BUILDING from doc/BUILDING.mdoc

BUILDINFO part6: regen BUILDING from doc/BUILDING.mdoc

Regen from doc/BUILDING.mdoc;1.100:
Improve documentation for BUILDID.

regen

branches: 1.105.4;
regen using 'make regen' from src/doc.

regen (using mandoc doc/BUILDING.mdoc > BUILDING -- let me know
if a different way is preferred, I see that it now contains formatting).

regen

regen

branches: 1.101.2;
regen using 'make regen' in doc/

Document MKREPRO using joerg's wording.

Add a missing period.

branches: 1.98.2;
Regen from revision 1.87 of doc/BUILDING.mdoc.

Add "live-image" and "install-image" target support to build.sh.

"live-image" target builds pre-installed disk images that can be used on
emulators or boot from USB memory sticks to try NetBSD without installation.
Currently amd64, i386, pmax, sparc, sparc64, sun2, sun3, and vax
(which have working emulators and don't require extra tools like preparing
msdosfs or partitioning MD label structures) support this target.

"install-image" target builds an bootable installation disk image that can
be used as an install CD but burned into USB memory sticks etc.
Current only amd64 and i386 (which would support USB boot) have this target.

For more details (and known issue) see following posts on netbsd-bugs@:
http://mail-index.NetBSD.org/netbsd-bugs/2011/08/06/msg023639.html
http://mail-index.NetBSD.org/netbsd-bugs/2011/09/23/msg024207.html
http://mail-index.NetBSD.org/netbsd-bugs/2011/12/07/msg025166.html
http://mail-index.NetBSD.org/netbsd-bugs/2011/12/08/msg025178.html

No particular comments about implementation, and
"go ahead" comments from mrg@, riz@ and christos@.

Closes PR toolchain/45153 and PR misc/45155.

branches: 1.96.2;
Add tests for the shell under which build.sh is run. If the
shell fails the tests, then build.sh tries to re-exec itself
under a more suitable shell.

Revisions 1.92 and 1.93 of src/BUILDING were not reflected in
src/doc/BUILDING.mdoc, so those changes were lost when src/BUILDING
was regenerated in revision 1.94.

Now update src/doc/BUILDING.mdoc and regenerate src/BUILDING to
reinstate the lost changes. (I also edited one of the changes, to use
the phrase "space-separated list" for consistency with other parts of
the document.)

The original changes were:

Add description of MKKMOD, part of PR misc/45216

Pass down INSTALLSETS variable to installsets target. Use :Q to escape
shell meta-characters, as the variable contains a list of sets, separated
by spaces.

$ ./build.sh -V INSTALLSETS="base etc" install=idir

should now work as expected.

Reviewed by apb@ on tech-toolchain.

Allow MAKEFLAGS to be set via build.sh -V. Somebody asked for this
in 2008.

Also add comments above a few functions in build.sh, and bump copyright
dates.

Add description of MKKMOD, part of PR misc/45216

Pass down INSTALLSETS variable to installsets target. Use :Q to escape
shell meta-characters, as the variable contains a list of sets, separated
by spaces.

$ ./build.sh -V INSTALLSETS="base etc" install=idir

should now work as expected.

Reviewed by apb@ on tech-toolchain.

branches: 1.91.2;
remove the MKSUBPIXEL/MKTTINTERP options; they're going away.

regenerate.

Support "extsrc", externally added programs and libraries. Users can write
their own reach-overs, cross-build, install, and get set files just like base
and X11 / X.org. (These sets are not included as TNF releases.)

If ${NETBDSRCDIR}/../xsrc exists, then use it as the default value
of X11SRCDIR. If it doesn't exist, then use /usr/xsrc as before.

OK mrg

* Use a more robust method of creating the top level object directory.
Use getmakevar to expand MAKEOBJDIRPREFIX or MAKEOBJDIR, or (if
neither of those variables is set) use a non-recursive "make obj" in
the top level source directory.

* Do not let TOP_objdir default to ${TOP}. It's now set only by the
-M or -O command line options, or after using getmakevar to expand
MAKEOBJDIRPREFIX or MAKEOBJDIR.

* Make try_set_TOOLDIR handle MAKEOBJDIRPERFIX passed from the
environment. It runs too early to use getmakevar, so it will not work
if the value contains embedded '${...}' variable references.

* Use '$TOOLDIR' (with a literal '$') instead of 'nonexistent' in
a message when rebuilding make when TOOLDIR is not yet known.

Allow build.sh "-C cdextra" option to be specified multiple times.

Add a modules operation to build.sh, which builds and installs kernel modules
into DESTDIR.

This is based on the patch provided by tsutsui@ on tech-toolchain@.

regen

regen

Introduce MKSUBPIXEL, which allows enabling subpixel rendering code
in FreeType.

branches: 1.82.2;
be explicit about MAKEOBJDIR and MAKEOBJDIRPREFIX not being for
mk.conf or ${MAKECONF}.

revert sparc back to default of XFree86 at the request of macallan.

Add support for new MAKEVERBOSE levels 3 and 4. The complete list is now:

0 Minimal output ("quiet")
1 Describe what is occurring
2 Describe what is occurring and echo the actual command
3 Ignore the effect of the "@" prefix in make commands
4 Trace shell commands using the shell's -x flag

The default remains MAKEVERBOSE=2.

- retire MKXORG from public use
- introduce X11FLAVOUR to choose src/x11 vs src/external/mit/xorg
for the X11 to build if MKX11=yes is set. it takes the values
of either Xorg or XFree86.
- default to Xorg on alpha, i386, macppc, shark, sparc and sparc64
- remove MKXORG_WITH_XSRC_XSERVER, unused and never useful

branches: 1.78.2;
regen for recent change to examples and objdir advice,
and for the older MKSTRIPIDENT change.

regen for MKHTML

Improve support for MKXORG!=no to enable builds into external/mit/xorg.
This will be mutually exclusive to MKX11!=no.

Document "build.sh cleandir".
Fix formatting nit.
Remove BUGS; all the in-tree platforms are using build.sh now.

* Suggest a "-j" value between 1+NCPU and 2*NCPU for the fastest builds.
* Remove some duplicated content that appeared in both the section about
make's -j flag and the section about build.sh's -j flag.

* Add more detail for build.sh -M and -O options.
* Mention new default when source is /usr/src but build.sh is run
with neither -M nor -O.

Builds now use "BUILDSEED" so that c++ binaries are reproduceable.
By default BUILDSEED is set to NetBSD-{majorversion} -- a -S flag may
be used to change it.

Discussed on tech-toolchain.

branches: 1.71.4;
Correct/clarify the default setting of USETOOLS in the previous version.
Noted by apb.

Assorted updates and clarifications, grammar fixes and wording improvements,
and so on. Significant highlights:
- mention src/tests and reference atf;
- provide examples of MACHINE and MACHINE_ARCH;
- mention that MKOBJ=no is not recommended;
- correct the description of the default setting of USETOOLS;
- document the interactions of build.sh -[uo] with various things;
- document the interactions of build.sh tools and kernel=FOO;
- use a lot fewer parentheses.
Discussed on netbsd-docs.

Consistently document RELEASEDIR/RELEASEMACHINEDIR.

Mention that "build" and "distribution" do not build nor install (to DESTDIR)
a kernel.

branches: 1.67.4;
Add support for CDBUILDEXTRA which acts like CDEXTRA to add extra items
to the CD-ROM image.
Make CDEXTRA and CDBUILDEXTRA be able to contain lists of files and directories
which are added in turn.
Add support for CDEXTRA_SKIP which contains a list of fnmatch(3) items to
skip during the copy. This is _very_ useful for skipping CVS dirs for example.
CDBUILDEXTRA and CDEXTRA_SKIP are to be used in Makefiles creating the images,
CDEXTRA remains to be used from build.sh.
Update documentation and build.sh help text to show that -C can be used to
specify a list of files and directories rather than just a single dir.

Convert build.sh iso-dir=directory option to -C cddir as per jmmv@ on
source-changes.

Add an iso-dir=directory option. When combined with iso-image or
iso-image-source, it will cause directory to be added to the CD-ROM image.

describe new iso-image-source target

Remove STATUS paragraph which makes it sound like the build system is
half baked.

branches: 1.62.4;
Document recent changes to "make iso-image".

Document the fact that "make installworld" and "build.sh
installworld=..." do not install the etc or xetc sets. Suggest using
etcupdate(8) and postinstall(8) after installworld.

Try to clarify the description of build.sh -m mach.
Document new evbarm-eb and evbarm-el aliases.

branches: 1.59.2;
Clarify that DESTDIR/OBJDIR/etc are absolute paths, but build.sh
-D/-O/etc allows relative paths.

Closes PR 32345 by Andre Luiz de Oliveira.

Use ${HOST_SH} instead of the host system's /bin/sh wherever possible:

* Describe the HOST_SH variable, and the way build.sh attempts to set it.

* Suggest passing HOST_SH in the environment if /bin/sh is not a working
shell.

mkisofs is in pkgsrc/sysutils/cdrtools now, not pkgsrc/sysutils/cdrecord.
Reported by Jukka Salmi.

* Add an "iso-image" target in the top level Makefile,
which invokes make iso-image in the etc directory.
* Add an "iso-image" action in build.sh, which
invokes make iso-image.
* Document the above in doc/BUILDING.mdoc.
* Re-generate BUILDING.

Approved by christos

Bump date for syspkgs.

Document "make syspkgs" and "build.sh syspkgs".

Reviewed by agc

Document the environment variables for if you need to override or
manually select your compilers.
(And regen BUILDING from doc/BUILDING.mdoc.)

Fix some typo's/bad wording as highlighted in PR#27219

regen (Document -h. From Karsten Kruse in PR 25974.
While here, remove a duplicate sentence).

Document MKTTINTERP.

* Document build.sh -X and -x
* Document MKX11 and X11SRCDIR
* Remove note warning against cross-building from systems other than NetBSD;
it works on many other platforms.

Note tools/compat/README as the place to get notes from non-native cross builds

Change -v to -V in the following section:

"Print make(1)'s idea of the value of var. Does not build any targets."

To reflect reality.

Found by Tomasz Marciniak <Tomasz.Marciniak@felix.fizyka.amu.edu.pl>, thanks!

Improve how build.sh -N and MAKEVERBOSE interoperate;
rather than adding '-s' to make's command line in the makewrapper,
use the .SILENT target based on MAKEVERBOSE's value.

This means that you can do:
./build.sh -N 1 makewrapper

$TOOLDIR/bin/nbmake-$MACHINE
# runs at MAKEVERBOSE==1, with command lines suppressed

$TOOLDIR/bin/nbmake-$MACHINE MAKEVERBOSE=2
# runs at MAKEVERBOSE==2 for this invocation, with command lines shown

Implement build -N noisy, which sets MAKEVERBOSE to noisy and adds
`-s' to MAKEFLAGS for noisy < 2.

regenerate for "%" prompt update

Backout the previous commit

Remove # from the example.

fix description of MAKEOBJDIR. from Martin Husemann

Add build.sh -Z var, to unset a variable and ensure it's unset in makewrapper.
For -M MAKEOBJDIRPREFIX, unset MAKEOBJDIR.
For -O MAKEOBJDIR, unset MAKEOBJDIRPREFIX.

fix default location of TOOLDIR

Update for the MKUNPRIVED/MKUPDATE changes.

rebuild with new groff

attempt to clarify how MAKEOBJDIR{,PREFIX} may be provided ...
(this document needs a rototill, which i may get to whilst writing a
paper about build.sh)

all:
* add "releasekernel=conf", to install a gzipped copy of the kernels
built by "kernel=conf" to RELEASEDIR/MACHINE/binary/kernel

build.sh:
* be more consistent in various status messages
* move the {release,}kernel=conf conf parsing code into getkernelconf()
and use in both buildkernel() and releasekernel()
* only warn once when building multiple kernels without updating the tools

For normal builds, MKOBJDIRS default to `no' (not `yes').
It's only build.sh that sets this to `yes' by default.
Noted by OGAWA Takaya in [toolchain/19823]

improve description of how "build.sh -m mach" sets the default
MACHINE_ARCH, and list the special cases that this does not occur for.

crank date for previous

Add "sourcesets" argument/target, which builds source sets into
RELEASEDIR/source/sets

build.sh now provides defaults for DESTDIR and RELEASEDIR if not expert mode.
Remove -D and -R from EXAMPLES since they're not necessary any more.

Fix example 3; the build.sh target is "install" not "installworld".
Improve description.
Noted by Valeriy Ushakov (uwe@) in private email.

attempt to further improve and clarify the examples...

Prefix various paths with 'DESTDIR', to highlight that the DESTDIR
is taken into account.

allow toolprefix to be easily changed

Various improvements per discussion with Alan Barrett.

- Add "sets" top-level Makefile target and build.sh operation.
[Latter suggested by Julio Merino in private email]
- Add "help" build.sh operation.

Change build.sh so that at least one operation is required.
Add "makewrapper" operation to build.sh.
[The above changes were suggested by Alan Barrett on current-users@]

Fail if building as non-root unless: UNPRIVED is set, -U is given, or -E
(expert mode) is given.
[Suggested by James Wetterau in private email]

Improve the examples in BUILDING.

Rework how build.sh functions, so that command line options set various
parameters, and a list of "operations" defines what to do.
The full usage is show below. Notes:
`-b' has been deprecated (it always occurs now)
`-d' is replaced by "distribution"
`-R rel' onlys sets RELEASEDIR; use "release" to build a release
`-k kern' has been replaced by "kernel=kern"
`-i idir' has been replaced by "install=idir"
-r now occurs before nbmake is rebuilt

Add a copyright (long due!). Rework the code to (a KNF inspired) ShellNF.
Use functions appropriately. Allow `nb' prefix to be easily changed to
something else. Solve world peace (just kidding)

This is part of the (never achievable) goal of attempting to make
NetBSD easier to build...


--8<-- new usage follows --8<--

Usage: build.sh [-EnorUu] [-a arch] [-B buildid] [-D dest] [-j njob] [-M obj]
[-m mach] [-O obj] [-R release] [-T tools] [-V var=[value]]
[-w wrapper] [operation [...] ]

System build operations (all imply "obj" and "tools"):
build Run "make build"
distribution Run "make distribution" (includes etc/ files)
release Run "make release" (includes kernels & distrib media)

Other operations:
obj Run "make obj" (default unless -o)
tools Build and install tools
kernel=conf Build kernel with config file `conf'
install=idir Run "make installworld" to `idir'
(useful after 'distribution' or 'release')

Options:
-a arch Set MACHINE_ARCH to arch (otherwise deduced from MACHINE)
-B buildId Set BUILDID to buildId
-D dest Set DESTDIR to dest
-E Set "expert" mode; disables some DESTDIR checks
-j njob Run up to njob jobs in parallel; see make(1)
-M obj Set obj root directory to obj (sets MAKEOBJDIRPREFIX)
-m mach Set MACHINE to mach (not required if NetBSD native)
-n Show commands that would be executed, but do not execute them
-O obj Set obj root directory to obj (sets a MAKEOBJDIR pattern)
-o Set MKOBJDIRS=no (do not create objdirs at start of build)
-R release Set RELEASEDIR to release
-r Remove contents of TOOLDIR and DESTDIR before building
-T tools Set TOOLDIR to tools. If unset, and TOOLDIR is not set in
the environment, nbmake will be (re)built unconditionally.
-U Set UNPRIVED
-u Set UPDATE
-V v=[val] Set variable `v' to `val'
-w wrapper Create nbmake script as wrapper
(default: ${TOOLDIR}/bin/nbmake-${MACHINE})

Add "-V var=[value]", for setting arbitrary variables which will also
be added to the nbmake-${MACHINE} wrapper.
Useful for setting RELEASEDIR, without -R's habit of building a release.

Document:
* build.sh -i idir
* top level targets: distribution, buildworld, installworld
* top level variables: INSTALLWORLDDIR

Add -E - "expert mode". If this is not specified, builds to DESTDIR=/ are
not permitted.
By using this flag, you are taking responsibility for any issues that
may occur because of this...

- be consistent about option ordering in build.sh usage display
- use Fl and Ar instead of Sy and Em to format options

Update location of BUILDING.mdoc.

regen for build.sh -k

regen for: USE_NEW_TOOLCHAIN was replaced with TOOLCHAIN_MISSING

Expand on the difference between ``build.sh -d'' and ``make install'',
as requested by Brian Stark in PR toolchain/18228 (which this closes).

Remove duplicate 'files'. From Ryo HAYASAKA in toolchain/17674.

branches: 1.12.2;
add "-M makeobjdirprefix" to build.sh

Move the METALOG from ${_SRC_TOP_OBJ_} to ${DESTDIR}.

There were too many synchronisation problems with using the former;
including situations such as a "make clean" performed between two
installs to the same DESTDIR would result in a truncated METALOG and
the resultant sets would be missing stuff such as include files that
don't get reinstalled if they haven't changed, even with !UPDATE.

Re-gen.

Add a -B option to set the BUILDID for the build. This also causes
the make(1) wrapper script to be named "nbmake-MACHINE-BUILDID".

document various supported environment variables, including MAKEOBJDIRPREFIX

document:
- make's UNPRIVED support
- build.sh's -U support
- the build system currently needs to build onto a file system with
long file name and hard link support

Document the -d option to build.sh

Note only <bsd.own.mk> as the authority for determining whether the new
BUILDING instructions should be used.

Turn off host-specific objdirs by default. Set MKHOSTOBJ=yes to enable.

Major overhaul of src/tools and host toolchain. Summary of changes:

* Rewrite src/tools Make logic to work like the rest of the tree wrt
"dependall" and "install". The old "make build" hack is gone.

* Remove the MKTOOLS logic. This was linked to the "make build" hack,
and was only needed because TOOLDIR originally had no writable default.

* Redo the GNU configure/make logic to make it fit reasonably in a
BSD make wrapper. Use new ${.ALLTARGETS} variable to scan for
targets in $(srcdir), and mark them with .MADE: to prevent rebuilding.

* Only build cross tools in src/tools; remove some messy logic in
src/usr.* and src/gnu/usr.* that would do target filename rewriting
(improves consistency and readability).

* Add the ability to build cross gdb at tool build time by setting
MKCROSSGDB (default no) to "yes" in mk.conf.

* Add src/tools/groff and set up paths to work with this cross groff.

Remove mention of BUILDLING.html, and follow rename of BUILDING.txt to
BUILDING.
Noted by Love <lha@stacken.kth.se> on tech-toolchain.

By popular demand, one preformatted version of BUILDING, plaintext, no CRs.

BUILDING: consistency fix

build.sh: use mk.conf (if present) as MAKECONF

Set MAKECONF to mk.conf in the same directory as build.sh
(i.e., the top of the source tree) if mk.conf is present.
This means unprivileged users can benefit from mk.conf(5)
semantics without write privileges to /etc/mk.conf, and
also simplifies per-source-directory configuration.

Fail early if $MAKECONF is empty, since build.sh will fail
anyway after rebuilding nbmake.

Ensure that the computed MAKECONF isn't empty, and then
always set MAKECONF in the makewrapper (nbmake-$MACHINE).

Improve some formatting consistency in BUILDING.mdoc,
(even if BUILDING is generated without markup).

BUILDING: wording tweaks

BUILDING: remove duplication from mk.conf(5)

Remove all "make" variables / mk.conf(5) variables already documented
in mk.conf(5). The duplication was a maintenance headache, as I've
experienced over recent weeks getting the build documentation up to
date.

Add notes clarifying that manual page references are to the NetBSD
manual pages, not to the host manual pages, and how to format from
source, or find online at https://man.netbsd.org.

Add explicit links to the mdoc(7) in-tree source for mk.conf(5),
hier(7), and release(7) because those are directly relevant to the host
build information in BUILDING.

Note: We don't normally need these notes for native documentation,
but BUILDING is intended for users on host systems which might not
be NetBSD(-current).

Add missing defaults.

BUILDING: update from mk.conf(5). reorder

Sync variable entries from mk.conf(5).

Merge the "make variables for full builds" section into the previous.
Having two separate sections and some entries duplicated was confusing
when searching for variables.

more NBUILDJOBS deprecation

The NBUILDJOBS option was deprecated in 2002;
there's no need to keep warning about it,
remove from params / show-params,
and only document as obsolete.

BUILDING: editorial

MKX11=yes wants MKINET6=yes

Change the width of the variable lists to 14n (from 15n)
so that when the lists are rendered and then left aligned,
the column is 16 characters (aka 2 tabs) which makes
copypasta to bsd.README easier.

BUILDING: update from canonical mk.conf(5)

Incorporate content and styles updates for mk.conf entries
from share/man/man5/mk.conf.5, which is the canonical
reference for mk.conf.

Add: BSDOBJDIR, BSDSRCDIR, EXTERNAL_TOOLCHAIN, MKDEBUGKERNEL,
MKDEBUGTOOLS, MKHTML, MKLINKLIB, MKOBJDIRS, TOOLCHAIN_MISSING,
NETBSDSRCDIR

It's for further study as to whether we just replace the
most of subsection "make" variables with a link to mk.conf(5).

Style:
- Add more .de macros per mk.conf.5.
- Order list items alphabetically. When multiple items are present
in a list item, sort within the item first.
- More cross-references.

build.sh: MAKECONF and mk.conf(5) improvements

Move MAKECONF to the Environment variables section.
Add mk.conf(5) cross-references.
Make Notes more obvious.
Fix mandoc lint.

BUILDING: TMPDIR must not be noexec

Describe $TMPDIR as used by build.sh, and
add a note that it can't be mounted noexec.

PR toolchain/44459

build.sh, BUILDING: consistency improvements

Consistently use "show", instead of sometimes using "display" or "print".
Fix mdoc markup (even though BUILDING is raw text).
Document help, -P, -?

BUILDING: update upstream, regen

doc/BUILDING.mdoc is the upstream for BUILDING, so add recent changes
in the latter to the former, formatting correctly.

Move INSTALLBOOT_UBOOT_PATHS to Environment variables.
Move INSTALLBOOT_BOARDS to "make" variables for full builds.
Add installboot(8) cross-reference.

fix documentation for MKLINT

Since share/mk/bsd.own.mk 1.749 from 2013-08-26, MKLINT defaults to no.

By default, do not install any bootable images.

The previous commit introduced the ability to install a set of
bootable images as a normal part of a release build. While this made
it easy to install bootable images, the contents of a release build
depend on whether or not U-Boot packages are installed in /usr/pkgsrc,
which is the default location searched by installboot(8).

This commit requires users to explicitly list the bootable images to
be installed, which by default is none (i.e., prior behavior).

Create bootable images in ${RELEASEDIR}/${RELEASEMACHINEDIR}/binary/gzimg.

Release builds for arm platforms create compressed images in
${RELEASEDIR}/${RELEASEMACHINEDIR}/binary/gzimg. However, in some
cases, e.g., armv7.img.gz, they are not bootable. Consequently, boot
blocks must be manually installed in the images, which is an extra
barrier for testing systems or adopting NetBSD. This has prompted
creation of external repositories, e.g., armbsd.org, to host a
collection of bootable images. However, this does not ease the burden
on developers compiling their own systems; for them, manual
installation of boot blocks is still required.

For arm platforms, etc/etc.evbarm/Makefile.inc contains the commands
used to create system images. Because installboot(8) can write boot
blocks directly to system images, a loop through possible boards can
create a series of bootable images during the normal build process.

In the case of many arm platforms, installboot(8) uses U-Boot boot
blocks, which are not part of the NetBSD source code. Developers can,
however, install as many U-Boot boot blocks as desired, either in the
default location of /usr/pkg/share/u-boot or in a set of directories
pointed to by the U-Boot search path, the INSTALLBOOT_UBOOT_PATHS
environment variable. For each board with an available boot block, a
board-specific bootable image will be created in
${RELEASEDIR}/${RELEASEMACHINEDIR}/binary/gzimg. If a boot block is
not available, which is the typical situation currently, no additional
image will be created.

This facility creates opportunities to build bootable images for any
number of boards within the scope of a standard release build.
However, that is not required and will not occur without the
intervention of installing U-Boot boot blocks prior to the build.

BUILDING: regen for removal of extsrc/

s/knowlege/knowledge/

Rename:
MKKDEBUG -> MKDEBUGKERNEL
MKTOOLSDEBUG -> MKDEBUGTOOLS
while keeping compatibility with the old names. Add missing documentation.
Now all debugging tunables are prefixed with MKDEBUG.

Reintroduce the support of MKCATPAGES

Requested by <mrg>

Remove the support for MKCATPAGES

It was optional since 1999 and disabled by default since 2012.

Proposed on tech-userlevel@.

Document CPUFLAGS here (it's already documented in share/mk/bsd.README).
This will address the initial concern in PR port-alpha/55545.

Mention HOST_CFLAGS and HOST_CXXFLAGS.

Bump date and regen for BUILDING.mdoc revision 1.127
that introduced build.sh -c <compiler> option.

Fix a typo

Reported by Tobias Ulmer via netbsd-docs@ ML, thanks!

regen

branches: 1.133.2;
Re-add files that were accidentally deleted in my previous commit.

Synch with HEAD

branches: 1.131.2;
regen

regen

regen

regen

regen

regen using regen target in doc.

Introduce MKSTRIPSYM build option

If it's yes, all local symbols of shared libraries are stripped
(default). If it's no, only temporary local symbols are stripped;
for example, symbols of static functions are kept. Keeping such
symbols is useful on using DTrace for userland libraries and
getting a backtrace from a rump server loading modules (shared
libraries).

Proposed and discussed on tech-kern and tech-toolchain

regen

The default values for MKPIC are yes and no for sh3 and m68000, respectively.
Bump date.

branches: 1.122.2; 1.122.4;
Document MKREPRO_TIMESTAMP.

remove the xfree86 reachover makefiles and the vast majority of
the support in the rest of the source tree.

X11 sets could use some cleaning up perhaps (just deletion, as
we've never really marked the old X11R6 as obsolete for native
xorg using platforms so far either.)

Update to reflect changes made in rev 1.398 of src/etc/Makefile

regen

regen

regen

regen

regen from doc/BUILDING.mdoc revision 1.107.
This reinstates documentation for "extsrc" which was lost in 2009.

fourth time's the charm, i guess. when committing a generated file,
it's best to use the latest revision of the source file (hi uebs!)

regen to include changes from revision 1.105 of doc/BUILDING.mdoc

regen

Expand TABs.

Document the new "kernels" operation, prompted by joerg@.

regen

branches: 1.109.2;
regen BUILDING from doc/BUILDING.mdoc

BUILDINFO part6: regen BUILDING from doc/BUILDING.mdoc

Regen from doc/BUILDING.mdoc;1.100:
Improve documentation for BUILDID.

regen

branches: 1.105.4;
regen using 'make regen' from src/doc.

regen (using mandoc doc/BUILDING.mdoc > BUILDING -- let me know
if a different way is preferred, I see that it now contains formatting).

regen

regen

branches: 1.101.2;
regen using 'make regen' in doc/

Document MKREPRO using joerg's wording.

Add a missing period.

branches: 1.98.2;
Regen from revision 1.87 of doc/BUILDING.mdoc.

Add "live-image" and "install-image" target support to build.sh.

"live-image" target builds pre-installed disk images that can be used on
emulators or boot from USB memory sticks to try NetBSD without installation.
Currently amd64, i386, pmax, sparc, sparc64, sun2, sun3, and vax
(which have working emulators and don't require extra tools like preparing
msdosfs or partitioning MD label structures) support this target.

"install-image" target builds an bootable installation disk image that can
be used as an install CD but burned into USB memory sticks etc.
Current only amd64 and i386 (which would support USB boot) have this target.

For more details (and known issue) see following posts on netbsd-bugs@:
http://mail-index.NetBSD.org/netbsd-bugs/2011/08/06/msg023639.html
http://mail-index.NetBSD.org/netbsd-bugs/2011/09/23/msg024207.html
http://mail-index.NetBSD.org/netbsd-bugs/2011/12/07/msg025166.html
http://mail-index.NetBSD.org/netbsd-bugs/2011/12/08/msg025178.html

No particular comments about implementation, and
"go ahead" comments from mrg@, riz@ and christos@.

Closes PR toolchain/45153 and PR misc/45155.

branches: 1.96.2;
Add tests for the shell under which build.sh is run. If the
shell fails the tests, then build.sh tries to re-exec itself
under a more suitable shell.

Revisions 1.92 and 1.93 of src/BUILDING were not reflected in
src/doc/BUILDING.mdoc, so those changes were lost when src/BUILDING
was regenerated in revision 1.94.

Now update src/doc/BUILDING.mdoc and regenerate src/BUILDING to
reinstate the lost changes. (I also edited one of the changes, to use
the phrase "space-separated list" for consistency with other parts of
the document.)

The original changes were:

Add description of MKKMOD, part of PR misc/45216

Pass down INSTALLSETS variable to installsets target. Use :Q to escape
shell meta-characters, as the variable contains a list of sets, separated
by spaces.

$ ./build.sh -V INSTALLSETS="base etc" install=idir

should now work as expected.

Reviewed by apb@ on tech-toolchain.

Allow MAKEFLAGS to be set via build.sh -V. Somebody asked for this
in 2008.

Also add comments above a few functions in build.sh, and bump copyright
dates.

Add description of MKKMOD, part of PR misc/45216

Pass down INSTALLSETS variable to installsets target. Use :Q to escape
shell meta-characters, as the variable contains a list of sets, separated
by spaces.

$ ./build.sh -V INSTALLSETS="base etc" install=idir

should now work as expected.

Reviewed by apb@ on tech-toolchain.

branches: 1.91.2;
remove the MKSUBPIXEL/MKTTINTERP options; they're going away.

regenerate.

Support "extsrc", externally added programs and libraries. Users can write
their own reach-overs, cross-build, install, and get set files just like base
and X11 / X.org. (These sets are not included as TNF releases.)

If ${NETBDSRCDIR}/../xsrc exists, then use it as the default value
of X11SRCDIR. If it doesn't exist, then use /usr/xsrc as before.

OK mrg

* Use a more robust method of creating the top level object directory.
Use getmakevar to expand MAKEOBJDIRPREFIX or MAKEOBJDIR, or (if
neither of those variables is set) use a non-recursive "make obj" in
the top level source directory.

* Do not let TOP_objdir default to ${TOP}. It's now set only by the
-M or -O command line options, or after using getmakevar to expand
MAKEOBJDIRPREFIX or MAKEOBJDIR.

* Make try_set_TOOLDIR handle MAKEOBJDIRPERFIX passed from the
environment. It runs too early to use getmakevar, so it will not work
if the value contains embedded '${...}' variable references.

* Use '$TOOLDIR' (with a literal '$') instead of 'nonexistent' in
a message when rebuilding make when TOOLDIR is not yet known.

Allow build.sh "-C cdextra" option to be specified multiple times.

Add a modules operation to build.sh, which builds and installs kernel modules
into DESTDIR.

This is based on the patch provided by tsutsui@ on tech-toolchain@.

regen

regen

Introduce MKSUBPIXEL, which allows enabling subpixel rendering code
in FreeType.

branches: 1.82.2;
be explicit about MAKEOBJDIR and MAKEOBJDIRPREFIX not being for
mk.conf or ${MAKECONF}.

revert sparc back to default of XFree86 at the request of macallan.

Add support for new MAKEVERBOSE levels 3 and 4. The complete list is now:

0 Minimal output ("quiet")
1 Describe what is occurring
2 Describe what is occurring and echo the actual command
3 Ignore the effect of the "@" prefix in make commands
4 Trace shell commands using the shell's -x flag

The default remains MAKEVERBOSE=2.

- retire MKXORG from public use
- introduce X11FLAVOUR to choose src/x11 vs src/external/mit/xorg
for the X11 to build if MKX11=yes is set. it takes the values
of either Xorg or XFree86.
- default to Xorg on alpha, i386, macppc, shark, sparc and sparc64
- remove MKXORG_WITH_XSRC_XSERVER, unused and never useful

branches: 1.78.2;
regen for recent change to examples and objdir advice,
and for the older MKSTRIPIDENT change.

regen for MKHTML

Improve support for MKXORG!=no to enable builds into external/mit/xorg.
This will be mutually exclusive to MKX11!=no.

Document "build.sh cleandir".
Fix formatting nit.
Remove BUGS; all the in-tree platforms are using build.sh now.

* Suggest a "-j" value between 1+NCPU and 2*NCPU for the fastest builds.
* Remove some duplicated content that appeared in both the section about
make's -j flag and the section about build.sh's -j flag.

* Add more detail for build.sh -M and -O options.
* Mention new default when source is /usr/src but build.sh is run
with neither -M nor -O.

Builds now use "BUILDSEED" so that c++ binaries are reproduceable.
By default BUILDSEED is set to NetBSD-{majorversion} -- a -S flag may
be used to change it.

Discussed on tech-toolchain.

branches: 1.71.4;
Correct/clarify the default setting of USETOOLS in the previous version.
Noted by apb.

Assorted updates and clarifications, grammar fixes and wording improvements,
and so on. Significant highlights:
- mention src/tests and reference atf;
- provide examples of MACHINE and MACHINE_ARCH;
- mention that MKOBJ=no is not recommended;
- correct the description of the default setting of USETOOLS;
- document the interactions of build.sh -[uo] with various things;
- document the interactions of build.sh tools and kernel=FOO;
- use a lot fewer parentheses.
Discussed on netbsd-docs.

Consistently document RELEASEDIR/RELEASEMACHINEDIR.

Mention that "build" and "distribution" do not build nor install (to DESTDIR)
a kernel.