BUILDING: fix typo

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.

Deprecate extsrc/, EXTSRCSRCDIR, MKEXTSRC

Remove support for building extsrc/:
1. Makefile: remove do-extsrc target.
2. build.sh: remove options -y and -Y extsrcdir.
3. distrib/sets: remove support for extsrc in various tools
including the options -L ext and -y, and the extsrc sets.
4. doc/BUILDING.mdoc: remove docs for extsrc/, EXTSRCSRCDIR, MKEXTSRC (etc)
5. bsd.own.mk and various Makefiles: remove support for extsrc/,
EXTSRCSRCDIR, MKEXTSRC.

As proposed on tech-kern and tech-userlevel on 2022-01-07
and followed up on 2022-08-21.

s/knowlege/knowledge/

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.

If this file is processed with real roff (doc.tmac) tweak things to
make ascii output as close to the mandoc output as possible.
There are only two diffs:
- groff renders em-dash as -- in the NAME section
- mandoc misses "NetBSD" in the "NetBSD System Manager's Manual"
section header

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

New build.sh option: -c <compiler>

Could never remember what the incantation is to do a clang build, so
now it's just `build.sh -c clang'.

Fix a typo

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

Spelling mistake.
Reword MKINFO description.

branches: 1.124.2; 1.124.4;
Fix a typo.

Pointed out by aalm in #NetBSD@Freenode.

While SH3 is no longer an exception, m68000 still is.

Direct reader to use build.sh for building NetBSD in favour of using make directly.
Give an example of why build.sh is better to use.

SH3 is no longer an exception for MKPIC, in src/share/mk/bsd.own.mk we set MKPIC
to yes by default.
Kill trailing whitespace.

Remove MKCRYPTO option.

Originally, MKCRYPTO was introduced because the United States
classified cryptography as a munition and restricted its export. The
export controls were substantially relaxed fifteen years ago, and are
essentially irrelevant for software with published source code.

In the intervening time, nobody bothered to remove the option after
its motivation -- the US export restriction -- was eliminated. I'm
not aware of any other operating system that has a similar option; I
expect it is mainly out of apathy for churn that we still have it.
Today, cryptography is an essential part of modern computing -- you
can't use the internet responsibly without cryptography.

The position of the TNF board of directors is that TNF makes no
representation that MKCRYPTO=no satisfies any country's cryptography
regulations.

My personal position is that the availability of cryptography is a
basic human right; that any local laws restricting it to a privileged
few are fundamentally immoral; and that it is wrong for developers to
spend effort crippling cryptography to work around such laws.

As proposed on tech-crypto, tech-security, and tech-userlevel to no
objections:

https://mail-index.netbsd.org/tech-crypto/2017/05/06/msg000719.html
https://mail-index.netbsd.org/tech-security/2017/05/06/msg000928.html
https://mail-index.netbsd.org/tech-userlevel/2017/05/06/msg010547.html

P.S. Reviewing all the uses of MKCRYPTO in src revealed a lot of
*bad* crypto that was conditional on it, e.g. DES in telnet... That
should probably be removed too, but on the grounds that it is bad,
not on the grounds that it is (nominally) crypto.

state correct location for install-image (RELEASEDIR/images)

Use Fl and Xr. New sentence, new line.

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

document -P

branches: 1.115.2; 1.115.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 location of live-images to reflect changes made in rev 1.398 of
src/etc/Makefile

Update Xorg defaults description. From Joachim Henke on netbsd-docs.

Use `It Sy', not just `It', for live-image, to match other targets.

No change to plain-text BUILDING file.

Add a new build make variable, CONFIGOPTS, which is passed to config(1)
when building kernels. Revert "mkernel=*" and "mkernels" in favor of
this option.

Diff posted on source-changes-d@, approved by (null).

Document build.sh mkernels.

Document mkernel=*.

Document "extsrc". This was added to src/BUILDING in revision 1.90
dated 2009-11-30, but was not added to src/doc/BUILDING.mdoc,
so the changes were lost.

The original log message was:
- - - -
revision 1.90
date: 2009-11-30 16:13:22 +0000; author: uebayasi; state: Exp; lines: +22 -0;
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.)
- - - -

Document the "kernels" operation.

sync with reality: iso -> images

branches: 1.104.2;
Add advice about avoiding common pitfalls.

This is taken from the patch in PR 48741, by David H. Gutteridge,
but I made small changes to wording and markup.

Document build.sh list-arch

Bump date for previous

BUILDINFO part 5: Document BUILDINFO in doc/BUILDING.mdoc.

Improve documentation for BUILDID.

Use Pa for paths. Fix a couple of typos.

Document MKCROSSGDB, MKKDEBUG and build.sh kernel.gdb=

Document MKDEBUG and MKDEBUGLIB

Document external directories

branches: 1.95.2;
Add missing Ar

- Bump date (for r1.93);
- remove superfluous macros (fixes mandoc(1) warnings).

From Bug Hunting.

MKCATPAGES defaults to no these days; noted on netbsd-docs by Luc van
der Veen.

Adjust postinstall recommendation syntax. based on comment from Snader_LB on IRC

strip trailing whitespace

Fix inverted logic description for MKSTRIPIDENT.
Noted by Snader_LB on freenode IRC

branches: 1.89.2;
Document MKREPRO using joerg's wording.

Add a missing period.

branches: 1.87.2;
Minor changes to wording in the documentation for
build.sh install-image and live-image.

Document build.sh "live-image" and "install-image" targets.

These were documented in revision 1.97 of src/BUILDING, but were
not documented in src/doc/BUILDING.sh. The original log message
was:

revision 1.97
date: 2012/01/22 03:53:32; author: tsutsui; state: Exp; lines: +39 -0
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.85.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.

Move the code for creating src/BUILDING from "make build-docs" in
src/Makefile to "make regen" in src/doc/Makefile, and update a comment
in doc/BUILDING.mdoc to match.

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.

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

regenerate.

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

backout wrong changes after I got teached that the vowel *sound* matters
and not the spelling letter (which is what I learned at school).

fix grammar: a -> an

* 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.

Revision 1.86 of src/BUILDING somehow got committed without the
corresponding changes to src/doc/BUILDING.mdoc. Fix that now.
The original log message was:

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@.

s/reproducable/reproducible/, requested by salo@

Add a keywords for people looking for reproducable (identical) builds.

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

branches: 1.71.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.67.2;
* Strengthen the advice against relying on the default objdir selection
rules.
* Add "[options]" to examples in an attempt to make it clear that
extra options should be passed.

Document MKSTRIPIDENT. Requested by lukem@

document 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.59.2; 1.59.4;
Convert TNF licenses to new 2 clause variant

branches: 1.58.2;
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.54.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.49.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.46.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.

Nitpicking. You won't see a difference in the text output, but there is
a difference in the postscript output.

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

Change all .Xr config 8 to .Xr config 1, following the recent move of
config from usr.sbin -> usr.bin.

Reviewed by wiz.

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

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.

provide a `%' for the non-root examples, as we show `#' for the root prompt.

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.

fix warning found by 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

New sentence, new line; use Pa for paths.

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.

- Add support for ./build.sh -k kern, which configures and builds the named
kernel using the $TOOLDIR toolchain. If kern doesn't contain `/', it will
be searched for in ${KERNCONFDIR} (typically, sys/arch/${MACHINE}/conf).
- Improve ./build.sh usage.
- Add some examples to the documentation.

This is heavily based on [toolchain/18739] from Alan Barrett <apb@cequrux.com>,
with improvements by me.

move BUILDING.mdoc -> doc/BUILDING.mdoc

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.

Deprecate extsrc/, EXTSRCSRCDIR, MKEXTSRC

Remove support for building extsrc/:
1. Makefile: remove do-extsrc target.
2. build.sh: remove options -y and -Y extsrcdir.
3. distrib/sets: remove support for extsrc in various tools
including the options -L ext and -y, and the extsrc sets.
4. doc/BUILDING.mdoc: remove docs for extsrc/, EXTSRCSRCDIR, MKEXTSRC (etc)
5. bsd.own.mk and various Makefiles: remove support for extsrc/,
EXTSRCSRCDIR, MKEXTSRC.

As proposed on tech-kern and tech-userlevel on 2022-01-07
and followed up on 2022-08-21.

s/knowlege/knowledge/

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.

If this file is processed with real roff (doc.tmac) tweak things to
make ascii output as close to the mandoc output as possible.
There are only two diffs:
- groff renders em-dash as -- in the NAME section
- mandoc misses "NetBSD" in the "NetBSD System Manager's Manual"
section header

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

New build.sh option: -c <compiler>

Could never remember what the incantation is to do a clang build, so
now it's just `build.sh -c clang'.

Fix a typo

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

Spelling mistake.
Reword MKINFO description.

branches: 1.124.2; 1.124.4;
Fix a typo.

Pointed out by aalm in #NetBSD@Freenode.

While SH3 is no longer an exception, m68000 still is.

Direct reader to use build.sh for building NetBSD in favour of using make directly.
Give an example of why build.sh is better to use.

SH3 is no longer an exception for MKPIC, in src/share/mk/bsd.own.mk we set MKPIC
to yes by default.
Kill trailing whitespace.

Remove MKCRYPTO option.

Originally, MKCRYPTO was introduced because the United States
classified cryptography as a munition and restricted its export. The
export controls were substantially relaxed fifteen years ago, and are
essentially irrelevant for software with published source code.

In the intervening time, nobody bothered to remove the option after
its motivation -- the US export restriction -- was eliminated. I'm
not aware of any other operating system that has a similar option; I
expect it is mainly out of apathy for churn that we still have it.
Today, cryptography is an essential part of modern computing -- you
can't use the internet responsibly without cryptography.

The position of the TNF board of directors is that TNF makes no
representation that MKCRYPTO=no satisfies any country's cryptography
regulations.

My personal position is that the availability of cryptography is a
basic human right; that any local laws restricting it to a privileged
few are fundamentally immoral; and that it is wrong for developers to
spend effort crippling cryptography to work around such laws.

As proposed on tech-crypto, tech-security, and tech-userlevel to no
objections:

https://mail-index.netbsd.org/tech-crypto/2017/05/06/msg000719.html
https://mail-index.netbsd.org/tech-security/2017/05/06/msg000928.html
https://mail-index.netbsd.org/tech-userlevel/2017/05/06/msg010547.html

P.S. Reviewing all the uses of MKCRYPTO in src revealed a lot of
*bad* crypto that was conditional on it, e.g. DES in telnet... That
should probably be removed too, but on the grounds that it is bad,
not on the grounds that it is (nominally) crypto.

state correct location for install-image (RELEASEDIR/images)

Use Fl and Xr. New sentence, new line.

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

document -P

branches: 1.115.2; 1.115.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 location of live-images to reflect changes made in rev 1.398 of
src/etc/Makefile

Update Xorg defaults description. From Joachim Henke on netbsd-docs.

Use `It Sy', not just `It', for live-image, to match other targets.

No change to plain-text BUILDING file.

Add a new build make variable, CONFIGOPTS, which is passed to config(1)
when building kernels. Revert "mkernel=*" and "mkernels" in favor of
this option.

Diff posted on source-changes-d@, approved by (null).

Document build.sh mkernels.

Document mkernel=*.

Document "extsrc". This was added to src/BUILDING in revision 1.90
dated 2009-11-30, but was not added to src/doc/BUILDING.mdoc,
so the changes were lost.

The original log message was:
- - - -
revision 1.90
date: 2009-11-30 16:13:22 +0000; author: uebayasi; state: Exp; lines: +22 -0;
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.)
- - - -

Document the "kernels" operation.

sync with reality: iso -> images

branches: 1.104.2;
Add advice about avoiding common pitfalls.

This is taken from the patch in PR 48741, by David H. Gutteridge,
but I made small changes to wording and markup.

Document build.sh list-arch

Bump date for previous

BUILDINFO part 5: Document BUILDINFO in doc/BUILDING.mdoc.

Improve documentation for BUILDID.

Use Pa for paths. Fix a couple of typos.

Document MKCROSSGDB, MKKDEBUG and build.sh kernel.gdb=

Document MKDEBUG and MKDEBUGLIB

Document external directories

branches: 1.95.2;
Add missing Ar

- Bump date (for r1.93);
- remove superfluous macros (fixes mandoc(1) warnings).

From Bug Hunting.

MKCATPAGES defaults to no these days; noted on netbsd-docs by Luc van
der Veen.

Adjust postinstall recommendation syntax. based on comment from Snader_LB on IRC

strip trailing whitespace

Fix inverted logic description for MKSTRIPIDENT.
Noted by Snader_LB on freenode IRC

branches: 1.89.2;
Document MKREPRO using joerg's wording.

Add a missing period.

branches: 1.87.2;
Minor changes to wording in the documentation for
build.sh install-image and live-image.

Document build.sh "live-image" and "install-image" targets.

These were documented in revision 1.97 of src/BUILDING, but were
not documented in src/doc/BUILDING.sh. The original log message
was:

revision 1.97
date: 2012/01/22 03:53:32; author: tsutsui; state: Exp; lines: +39 -0
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.85.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.

Move the code for creating src/BUILDING from "make build-docs" in
src/Makefile to "make regen" in src/doc/Makefile, and update a comment
in doc/BUILDING.mdoc to match.

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.

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

regenerate.

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

backout wrong changes after I got teached that the vowel *sound* matters
and not the spelling letter (which is what I learned at school).

fix grammar: a -> an

* 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.

Revision 1.86 of src/BUILDING somehow got committed without the
corresponding changes to src/doc/BUILDING.mdoc. Fix that now.
The original log message was:

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@.

s/reproducable/reproducible/, requested by salo@

Add a keywords for people looking for reproducable (identical) builds.

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

branches: 1.71.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.67.2;
* Strengthen the advice against relying on the default objdir selection
rules.
* Add "[options]" to examples in an attempt to make it clear that
extra options should be passed.

Document MKSTRIPIDENT. Requested by lukem@

document 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.59.2; 1.59.4;
Convert TNF licenses to new 2 clause variant

branches: 1.58.2;
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.54.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.49.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.46.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.

Nitpicking. You won't see a difference in the text output, but there is
a difference in the postscript output.

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

Change all .Xr config 8 to .Xr config 1, following the recent move of
config from usr.sbin -> usr.bin.

Reviewed by wiz.

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

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.

provide a `%' for the non-root examples, as we show `#' for the root prompt.

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.

fix warning found by 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

New sentence, new line; use Pa for paths.

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.

- Add support for ./build.sh -k kern, which configures and builds the named
kernel using the $TOOLDIR toolchain. If kern doesn't contain `/', it will
be searched for in ${KERNCONFDIR} (typically, sys/arch/${MACHINE}/conf).
- Improve ./build.sh usage.
- Add some examples to the documentation.

This is heavily based on [toolchain/18739] from Alan Barrett <apb@cequrux.com>,
with improvements by me.

move BUILDING.mdoc -> doc/BUILDING.mdoc

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.

Deprecate extsrc/, EXTSRCSRCDIR, MKEXTSRC

Remove support for building extsrc/:
1. Makefile: remove do-extsrc target.
2. build.sh: remove options -y and -Y extsrcdir.
3. distrib/sets: remove support for extsrc in various tools
including the options -L ext and -y, and the extsrc sets.
4. doc/BUILDING.mdoc: remove docs for extsrc/, EXTSRCSRCDIR, MKEXTSRC (etc)
5. bsd.own.mk and various Makefiles: remove support for extsrc/,
EXTSRCSRCDIR, MKEXTSRC.

As proposed on tech-kern and tech-userlevel on 2022-01-07
and followed up on 2022-08-21.

s/knowlege/knowledge/

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.

If this file is processed with real roff (doc.tmac) tweak things to
make ascii output as close to the mandoc output as possible.
There are only two diffs:
- groff renders em-dash as -- in the NAME section
- mandoc misses "NetBSD" in the "NetBSD System Manager's Manual"
section header

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

New build.sh option: -c <compiler>

Could never remember what the incantation is to do a clang build, so
now it's just `build.sh -c clang'.

Fix a typo

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

Spelling mistake.
Reword MKINFO description.

branches: 1.124.2; 1.124.4;
Fix a typo.

Pointed out by aalm in #NetBSD@Freenode.

While SH3 is no longer an exception, m68000 still is.

Direct reader to use build.sh for building NetBSD in favour of using make directly.
Give an example of why build.sh is better to use.

SH3 is no longer an exception for MKPIC, in src/share/mk/bsd.own.mk we set MKPIC
to yes by default.
Kill trailing whitespace.

Remove MKCRYPTO option.

Originally, MKCRYPTO was introduced because the United States
classified cryptography as a munition and restricted its export. The
export controls were substantially relaxed fifteen years ago, and are
essentially irrelevant for software with published source code.

In the intervening time, nobody bothered to remove the option after
its motivation -- the US export restriction -- was eliminated. I'm
not aware of any other operating system that has a similar option; I
expect it is mainly out of apathy for churn that we still have it.
Today, cryptography is an essential part of modern computing -- you
can't use the internet responsibly without cryptography.

The position of the TNF board of directors is that TNF makes no
representation that MKCRYPTO=no satisfies any country's cryptography
regulations.

My personal position is that the availability of cryptography is a
basic human right; that any local laws restricting it to a privileged
few are fundamentally immoral; and that it is wrong for developers to
spend effort crippling cryptography to work around such laws.

As proposed on tech-crypto, tech-security, and tech-userlevel to no
objections:

https://mail-index.netbsd.org/tech-crypto/2017/05/06/msg000719.html
https://mail-index.netbsd.org/tech-security/2017/05/06/msg000928.html
https://mail-index.netbsd.org/tech-userlevel/2017/05/06/msg010547.html

P.S. Reviewing all the uses of MKCRYPTO in src revealed a lot of
*bad* crypto that was conditional on it, e.g. DES in telnet... That
should probably be removed too, but on the grounds that it is bad,
not on the grounds that it is (nominally) crypto.

state correct location for install-image (RELEASEDIR/images)

Use Fl and Xr. New sentence, new line.

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

document -P

branches: 1.115.2; 1.115.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 location of live-images to reflect changes made in rev 1.398 of
src/etc/Makefile

Update Xorg defaults description. From Joachim Henke on netbsd-docs.

Use `It Sy', not just `It', for live-image, to match other targets.

No change to plain-text BUILDING file.

Add a new build make variable, CONFIGOPTS, which is passed to config(1)
when building kernels. Revert "mkernel=*" and "mkernels" in favor of
this option.

Diff posted on source-changes-d@, approved by (null).

Document build.sh mkernels.

Document mkernel=*.

Document "extsrc". This was added to src/BUILDING in revision 1.90
dated 2009-11-30, but was not added to src/doc/BUILDING.mdoc,
so the changes were lost.

The original log message was:
- - - -
revision 1.90
date: 2009-11-30 16:13:22 +0000; author: uebayasi; state: Exp; lines: +22 -0;
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.)
- - - -

Document the "kernels" operation.

sync with reality: iso -> images

branches: 1.104.2;
Add advice about avoiding common pitfalls.

This is taken from the patch in PR 48741, by David H. Gutteridge,
but I made small changes to wording and markup.

Document build.sh list-arch

Bump date for previous

BUILDINFO part 5: Document BUILDINFO in doc/BUILDING.mdoc.

Improve documentation for BUILDID.

Use Pa for paths. Fix a couple of typos.

Document MKCROSSGDB, MKKDEBUG and build.sh kernel.gdb=

Document MKDEBUG and MKDEBUGLIB

Document external directories

branches: 1.95.2;
Add missing Ar

- Bump date (for r1.93);
- remove superfluous macros (fixes mandoc(1) warnings).

From Bug Hunting.

MKCATPAGES defaults to no these days; noted on netbsd-docs by Luc van
der Veen.

Adjust postinstall recommendation syntax. based on comment from Snader_LB on IRC

strip trailing whitespace

Fix inverted logic description for MKSTRIPIDENT.
Noted by Snader_LB on freenode IRC

branches: 1.89.2;
Document MKREPRO using joerg's wording.

Add a missing period.

branches: 1.87.2;
Minor changes to wording in the documentation for
build.sh install-image and live-image.

Document build.sh "live-image" and "install-image" targets.

These were documented in revision 1.97 of src/BUILDING, but were
not documented in src/doc/BUILDING.sh. The original log message
was:

revision 1.97
date: 2012/01/22 03:53:32; author: tsutsui; state: Exp; lines: +39 -0
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.85.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.

Move the code for creating src/BUILDING from "make build-docs" in
src/Makefile to "make regen" in src/doc/Makefile, and update a comment
in doc/BUILDING.mdoc to match.

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.

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

regenerate.

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

backout wrong changes after I got teached that the vowel *sound* matters
and not the spelling letter (which is what I learned at school).

fix grammar: a -> an

* 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.

Revision 1.86 of src/BUILDING somehow got committed without the
corresponding changes to src/doc/BUILDING.mdoc. Fix that now.
The original log message was:

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@.

s/reproducable/reproducible/, requested by salo@

Add a keywords for people looking for reproducable (identical) builds.

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

branches: 1.71.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.67.2;
* Strengthen the advice against relying on the default objdir selection
rules.
* Add "[options]" to examples in an attempt to make it clear that
extra options should be passed.

Document MKSTRIPIDENT. Requested by lukem@

document 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.59.2; 1.59.4;
Convert TNF licenses to new 2 clause variant

branches: 1.58.2;
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.54.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.49.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.46.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.