Fix the Guide (Re: Recovering from botched update?)

[Aleksej Saushev <asau%inbox.ru@localhost>]

David Chanters <david.chanters%googlemail.com@localhost> writes:

> So I decided in my infinite wisdom to follow the following guide:
>
> http://www.NetBSD.org/docs/guide/en/chap-updating.html
>
> Following section "33.1.5" the first problem I noticed was the
> instructions don't tell you to build anything in tools, which meant I
> couldn't compile anything anyway -- this ought to be fixed, I think?
> I think this was noted here:
>
> http://mail-index.netbsd.org/netbsd-users/2010/01/16/msg005384.html
>
> I am not qualified to make a decision either way, but i think the
> "chap-updating.html" could do with simplifying for someone like me new
> to NetBSD following this for the first time.  Indeed, someone called
> "ASau" was kind enough to help me, but even he agrees that page needs
> simplifying --- and I would help, if I knew just how that's meant to
> be done.

After I've looked in the guide I've found that it is plain wrong,
since it suggests building userland before tools.

The question reoccurs quite frequently on IRC, we should react in some way.


I propose making following changes.

Mention that NetBSD always cross-builds ("expert" mode is for experts),
thus you need to build tools, then use these tools to build the rest.
Stress that tools is a pre-requisite.

Mention that it is good habit to use separate object tree,
canonical place is /usr/obj, check that it is set in build.sh by default
if the directory exists.

Mention that it is possible to build system unprivileged and it is good
habit to do so.

REMOVE all references to "-T ../tools", use default place for tools
under MAKEOBJDIR, under /usr/obj by default. I propose to leave this
practice (using separate directory for tools) for more advanced users.

Update routine in the Guide (for new users) should read in short:

  mkdir ../obj
  ./build.sh -O ../obj -U tools distribution sets kernel=<KERNEL>
  <install kernel, reboot>
  ./build.sh -O ../obj -U tools # this serves testing purpose well enough
  ./build.sh -O ../obj -U install=/

or simpler

  su root -c 'mkdir /usr/obj; chmod g+w /usr/obj' # so that wheel group can use 
it
  cd /usr/src
  ./build.sh -U tools distribution sets kernel=<KERNEL>
  <install kernel, reboot>
  ./build.sh -U tools install=/

The latter is basically what I do.


Note "-U" repetition. This suggests that we should make it default.


Technical question: is there any document with short instructions
how to update our documentation? Or should I just send diff?


-- 
HE CE3OH...