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

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

jnemeth%victoria.tc.ca@localhost (John Nemeth) writes:

> On Jun 16, 10:25am, Aleksej Saushev wrote:
> } 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?
>
>      "tools" is automatically built.  Could you be more specific about
> what happened (i.e. show output)?

It didn't work for me and I don't notice they're built automatically.
In other words, I am forced to build tools first.

> } > 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.
>
>      It does no such thing.  "tools" is automatically built if needed.
> The problem is the lack of use of "-T ../tools" in 33.1.2.  However,
> specifying -T is not an explicit request to build tools, just says
> where to put them.

I think that this should be omitted from the Guide because it belongs to
more advanced usage. Using -O results in putting tools into reasonable place,
subsequent build.sh invocations find it there. My opinion is that -T serves
no purpose in the Guide, rather it clutters commands with unnecessary details.

> } 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),
>
>      Okay.
>
> } thus you need to build tools, then use these tools to build the rest.
> } Stress that tools is a pre-requisite.
>
>      There is no need to explicitly build tools.

I have never perceived this, and I suspect others hit this as well.

Yes, build.sh bails out and reports the error, but it is better to mention
"tools" step so that first-timers don't learn it the hard way.

> } 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.
>
>      Checking that it is the default going forward might be useful, but
> it doesn't help with older versions until such a change is pullled up.
>
>      I tried "./build.sh params" and it bombed saying that TOOLDIR was
> empty and was invalid.  I then tried "./build.sh -U distribution".  It
> bombed, complaining about missing /usr/obj.  I created /usr/obj and
> tried again.  It bombed in the same way as "./build.sh params".  My
> final test was, "./build.sh -O ../obj -U distribution".  This also
> bombed in the same way as "./build.sh params", but created /usr/obj
> (/usr/src/../obj) by itself.  From this exercise, I conclude that one
> must specify a TOOLDIR.  This means that either build.sh must be
> updated, or the instructions must be updated accordingly.  Indeed,
> "./build.sh -O ../obj -T ../tools params" works as expected.  This is
> basically what 33.1.5 tells you do and is inconsistent with 33.1.1.
> I'll fix that.

"./build.sh -U params" results in:

mkdir: /usr/src/tooldir.NetBSD-5.99.23-i386: Permission denied
ERROR: mkdir of '/usr/src/tooldir.NetBSD-5.99.23-i386/bin' failed
*** BUILD ABORTED ***

It doesn't use /usr/obj by default. Alright.


"./build.sh -O /tmp/obj -U params" results in creating /tmp/obj with
tooldir containing _only_ nbmake and the wrapper.


"./build.sh -O /tmp/obj -U kernel=GENERIC" results in

ERROR: /tmp/obj/tooldir.NetBSD-5.99.23-i386/bin/nbconfig does not exist. You 
need to "./build.sh tools" first.
*** BUILD ABORTED ***

Obviously, tools are _not_ built automatically.
This is what I'm talking about each time someone comes with this problem on IRC.

Note that this is 5.99.23.

Also note that default TOOLDIR value is reasonable.

> } 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.
>
>      This is wrong with current build.sh.

I don't see how this is wrong, see above.
I use the procedure I describe since before 4.0, this means that it is so
in all (more or less) supported systems.

> } Update routine in the Guide (for new users) should read in short:
> } 
> }   mkdir ../obj
> }   ./build.sh -O ../obj -U tools distribution sets kernel=<KERNEL>
>
>      This doesn't work, due to the missing -T.  Also, no need to
> specify "tools" or "sets" here.

This does work, I use it for a long time, see above.

> }   <install kernel, reboot>
> }   ./build.sh -U tools install=/
>
>      If you are going to use a rebuild of tools to test the new kernel,
> then I would prefer to see this done as two seperate steps as above.

Yes, I build tools (at the very least) to test new kernel.
I admit that I should have mentioned it.

It's fine to split this into separate commands.
It's fine to omit it as well, provided that you describe a way to recover
from botched update. (It is to be described anyway, but with some testing
chances are less that you find yourself in severely broken system.)

> } The latter is basically what I do.
> } 
> } 
> } Note "-U" repetition. This suggests that we should make it default.
>
>      Possibly.

Any obvious issues with this except forcing old users to reconsider
their scripts?

> } Technical question: is there any document with short instructions
> } how to update our documentation? Or should I just send diff?
>
>      This isn't a technical question, it's a procedural question.

Alright.

> Either send a diff to www@ (but, make sure you have tested working
> instructions first), or ask on the private chat and somebody can step
> you through the process.

Alright.

>      Another significant error is that the chapter claims to be
> suitable for NetBSD-current.  However, for NetBSD-current, if you are
> using the i386 GENERIC kernel then you must install the modules before
> the first reboot, or the system won't boot.  I (or somebody) will have
> to think about the instructions for this, test them, and update the
> chapter accordingly.

Yes, I've forgotten about it.

Another problem to deal with is updating bootstrap loader,
this does matter for users updating from 5.0 to CURRENT.


-- 
HE CE3OH...