toolchain/49535: Examples in BUILDING don't work as-is

[gson%gson.org@localhost (Andreas Gustafsson)]

>Number:         49535
>Category:       toolchain
>Synopsis:       Examples in BUILDING don't work as-is
>Confidential:   no
>Severity:       serious
>Priority:       medium
>Responsible:    toolchain-manager
>State:          open
>Class:          doc-bug
>Submitter-Id:   net
>Arrival-Date:   Sun Jan 04 14:30:00 +0000 2015
>Originator:     Andreas Gustafsson
>Release:        NetBSD-current, souce date 2014.12.17.06.54.48
>Organization:
>Environment:
System: NetBSD
Architecture: x86_64
Machine: amd64
>Description:

If you do a full installation of NetBSD using sysinst, including the
source sets, cd to /usr/src, read the BUILDING file, and try to run
the first example listed under EXAMPLES,

    1.   % ./build.sh [options] tools kernel=GENERIC

as an unprivileged user without specifying any options, i.e.,

    $ ./build.sh tools kernel=GENERIC

the build will fail with:

    ERROR: -U or -E must be set for build as an unprivileged use

If you do it as root, it fails with:

    ERROR: Can't create top level object directory using make obj

I think having an example that works as-is would be helpful,
particularly to new users.

>How-To-Repeat:

See above.

>Fix:

First of all, presumably the shell prompt in Example 1 should be
changed from "%" to "#" to indicate that the command is to be run as
root, because unprivileged builds are covered separately in example
number 2.

As for the lack of a /usr/obj, there are many ways that could be
fixed, but I have no idea which one is correct.  I can think of
at least four:

1. If /usr/obj is supposed to exist in a fresh install, it should be
added to the release.

2. If you are supposed to specify a -O or -M option to build.sh to
force the object directory to be created, the example should contain
such an option.

3. If you are supposed to manually mkdir /usr/obj, the example should
include that command.

4. If build.sh is supposed to create the object directory
automatically, it should be changed to do so.