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

[jnemeth%victoria.tc.ca@localhost (John Nemeth)]

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)?

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

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

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

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

     Okay.

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

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

}   <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

     Okay.

}   cd /usr/src
}   ./build.sh -U tools distribution sets kernel=<KERNEL>

     Again, doesn't work.

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

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

     Possibly.

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

     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.

}-- End of excerpt from Aleksej Saushev