Subject: Re: New NetBSD Guide chapter: Obtaining the sources
To: Rui Paulo <rpaulo@NetBSD.org>
From: Greg Troxel <email@example.com>
Date: 08/08/2005 08:34:47
Before starting to fetch or download the required files, you may
want to know the definitions of ?Formal releases?,
This should be stronger, making the point that one must choose a
branch or release first.
CVS is usually quite fast for fetching sources if you have decent
internet connectivity. However, in a case you are using a modem, you
may wish to compress data for the update. In that case use the -z
option. For example:
"decent" is not precise. I suggest giving guidance for when to use
-z3 and -z9 based on pipe size. I would think that -z3 is appropriate
for <= 128 kb/s, and -z9 never.
I would explain how to get tarballs first, and explain (if true) that
one can unpack tarballs and then use cvs.
CVS also supports several connection methods. If you want to use the
?external? method (only available with ssh(1)) you should do:
Given new users, this should explain how to make this choice. Perhaps
even call ssh the 'normal way', and discourage pserver use. (Or the
other way, for server load - what I really mean is to get expert
consensus and teach that.)
Seeing csh examples rubs me the wrong way, since while I started to
use csh under BSD after V7, I went back to a Bourne-style shell in
1990, and object to scripts in csh. One thought is to show both sh
and csh style variable setting, and to avoid environment variables
when possible. In particular, I object to setting CVSROOT (and
prohibit it within my research group) since when using multiple
repositories it is often wrong. So I'd say:
cvs -d :ext:anoncvs@anoncvs.NetBSD.org:/cvsroot co src
because once checked out, there is no need to have CVSROOT set.
In general, I would omit prompts so that text from the guide can be
cut/pasted into a shell.
The CVS program (http://www.CVShome.org/) is part of NetBSD. If you
have an old release which didn't come with CVS, you can install it
either by using pkg_add, or building from pkgsrc.
How ancient is that? I'd omit all this - people running that old a
release are either very clueful and doing it for a reason, or would
need huge amounts of guidance.
I expect that the guide intends only to cover building netbsd on
netbsd, and not how to get sources on windows to crossbuild under
cygwin, or rather that anyone doing such crossbuilding would only want
to find the list of sources and CVSROOT and would already know how to
do everything else.
Where <BRANCH> is the release branch to be checked out, for example,
?netbsd-2-0-RELEASE?, ?netbsd-2-1-RELEASE? or ?netbsd-3-0-RELEASE?. If
you want to fetch a different patchlevel, you would use
?netbsd-2-0-1-RELEASE? or ?netbsd-2-0-2-RELEASE?.
This blurs branches and point tags. While perhaps a fine point, this
is very confusing to most people, and I advise being clear from the
beginning. Having a sentence "A release is a set of particular
versions of source files, and once released does not change over
time." would perhaps help to explain this. Then, do not use the word
branch in this section.
For example, if you want to fetch the stable version of ?netbsd-2?,
you just need to use that tag:
Not the stable version of netbsd-2, but the *most recent* version of
netbsd-2 (which points out that netbsd-2 changes over time).
(netbsd-2 is a stable branch, but there aren't stable versions of that
Explain what -P means. I had not seen it used on checkout before, and
it seems clear that it is intended to not checkout empty directories
in order to avoid build breakage. This is subtle.
To know the pkgsrc branches for the current year, run:
"Once you have some version of pkgsrc checked out"
This advice is problematic, since it can lead to people using the
next, not yet debugged branch while the old is still active. But
given pkgsrc resources, it's probably 98% good advice.
I'd like to see an explanation of how to get a copy of the repository
(sup, cvsup or rsync, I think), and guidance on the advantages and
disadvantages of each, both for the user and the servers. Probably
this is advanced for most users, and perhaps duplicatesa
Perhaps that page can be stripped down to bare bones information and
refer to the guide. By bare bones, I mean written for someone who
knows how to use CVS, and just needs to be given the CVSROOT value and
the set of modules to check out.
Greg Troxel <firstname.lastname@example.org>