Rewrote the chapter on "getting pkgsrc and keeping it up-to-date" based on

the current discussion on the pkgsrc-users mailing list.

1 files changed, 158 insertions, 69 deletions

diff --git a/doc/guide/files/getting.xml b/doc/guide/files/getting.xml
index 40f2b1f411f..1d9d39bf1e9 100644
--- a/doc/guide/files/getting.xml
+++ b/doc/guide/files/getting.xml
@@ -1,77 +1,166 @@
-<!-- $NetBSD: getting.xml,v 1.9 2006/02/12 14:44:59 rillig Exp $ -->
+<!-- $NetBSD: getting.xml,v 1.10 2006/05/28 20:37:52 rillig Exp $ -->
 
 <chapter id="getting">
-  <title>Where to get pkgsrc and how to keep it up-to-date</title>
-
-  <para>There are three ways to get pkgsrc. Either as a tar file, via SUP, or
-    via CVS. All three ways are described here.</para>
-
-  <sect1 id="as-tar-file">
-    <title>As tar file</title>
-
-    <para>To get pkgsrc going, you need to get the pkgsrc.tar.gz file
-      from <ulink
-      url="ftp://ftp.NetBSD.org/pub/NetBSD/NetBSD-current/tar_files/pkgsrc.tar.gz">ftp.NetBSD.org</ulink>
-      and unpack it into <filename>/usr/pkgsrc</filename>.</para>
-
-  </sect1>
-
-  <sect1 id="via-sup">
-    <title>Via SUP</title>
-
-    <para>As an alternative to the tar file, you can get pkgsrc via
-      the Software Update Protocol, SUP. To do so, make sure your
-      supfile has a line</para>
+<title>Where to get pkgsrc and how to keep it up-to-date</title>
+
+	<para>The most common location where pkgsrc is installed is
+	<filename>/usr/pkgsrc</filename> for the <quote>package
+	sources</quote> and <filename>/usr/pkg</filename> for the
+	installed binary packages. You are though free to install the
+	sources and binary packages wherever you want in your
+	filesystem, provided that both paths do not contain white-space
+	or other characters that are interpreted specially by the shell
+	and some other programs. A safe bet is to use only letters,
+	digits, underscores and dashes in the names.</para>
+
+<sect1 id="getting-first">
+<title>Getting pkgsrc for the first time</title>
+
+	<para>Before you download any pkgsrc files, you should decide
+	whether you want the <emphasis>current</emphasis> branch or the
+	<emphasis>stable</emphasis> branch. The latter is forked on a
+	quarterly basis from the current branch and only gets modified
+	for security updates. The names of the stable branches are built
+	from the year and the quarter, for example
+	<literal>2006Q1</literal>.</para>
+
+	<para>The second step is to decide <emphasis>how</emphasis> you
+	want to download pkgsrc. You can get it as a tar file, via SUP,
+	or via CVS. All three ways are described here.</para>
+
+<sect2 id="getting-via-tar">
+<title>As tar file</title>
+
+	<para>The primary download location for all pkgsrc files is
+	<ulink url="ftp://ftp.NetBSD.org/pub/pkgsrc/"/>. There are a
+	number of subdirectories for different purposes, which are
+	described in detail in <xref linkend="ftp-layout"/>.</para>
+
+	<para>The tar file for the current branch is in the directory
+	<filename>current</filename> and is called <ulink
+	url="ftp://ftp.NetBSD.org/pub/pkgsrc/current/pkgsrc.tar.gz"><filename>pkgsrc.tar.gz</filename></ulink>.
+	It is autogenerated daily.</para>
+
+	<para>The tar file for the stable branch 2006Q1 is in the
+	directory <filename>2006Q1</filename> and is also called <ulink
+	url="ftp://ftp.NetBSD.org/pub/pkgsrc/2006Q1/pkgsrc.tar.gz"><filename>pkgsrc.tar.gz</filename></ulink>.</para>
+
+	<para>After downloading the tar file, change to the directory
+	where you want to have pkgsrc. This is usually
+	<filename>/usr</filename>. Then, run <command>tar xfz
+	pkgsrc.tar.gz</command> to extract the files.</para>
+
+</sect2>
+<sect2 id="getting-via-sup">
+<title>Via SUP</title>
+
+	<para>As an alternative to the tar file, you can get pkgsrc via
+	the Software Update Protocol, SUP. To do so, make sure your
+	supfile has a line
 
 <programlisting>
     release=pkgsrc
 </programlisting>
 
-    <para>in it, see the examples in
-      <filename>/usr/share/examples/supfiles</filename>, and that the
-      <filename>/usr/pkgsrc</filename> directory exists. Then, simply run
-      <command>sup -v <replaceable>/path/to/your/supfile</replaceable></command>.</para>
-  </sect1>
-
-  <sect1 id="via-cvs">
-    <title>Via CVS</title>
-
-    <para>To get pkgsrc via CVS, make sure you have <quote>cvs</quote> installed.
-      To do an initial (full) checkout of pkgsrc, do the following steps:</para>
-
-    <screen>&cprompt; <userinput>setenv CVSROOT anoncvs@anoncvs.NetBSD.org:/cvsroot</userinput>
-&cprompt; <userinput>setenv CVS_RSH ssh</userinput>
-&cprompt; <userinput>cd /usr</userinput>
-&cprompt; <userinput>cvs checkout -P pkgsrc</userinput></screen>
-
-    <para>This will create the <filename>pkgsrc</filename> directory in your
-      <filename>/usr</filename>, and all the package source will be stored
-      under <filename>/usr/pkgsrc</filename>.  To update pkgsrc
-      after the initial checkout, make sure you have
-      <varname>CVS_RSH</varname> set as above, then do:</para>
-
-    <screen>&cprompt; <userinput>cd /usr/pkgsrc</userinput>
-&cprompt; <userinput>cvs -q update -dP</userinput></screen>
-
-    <para>Please also note that it is possible to have multiple copies of the
-      pkgsrc hierarchy in use at any one time - all work is done relatively
-      within the pkgsrc tree.</para>
-  </sect1>
-
-  <sect1 id="uptodate-cvs">
-    <title>Keeping pkgsrc up-to-date via CVS</title>
-
-      <para>If your copy of pkgsrc contains a lot of
-      <filename>CVS</filename> directories, you can update it using the
-      &man.cvs.1; program. First, <command>cd</command> to the top level
-      directory of pkgsrc. Then run <command>cvs -q update
-      -dP</command>, and you're done.</para>
-
-      <para>If that doesn't work and the file
-      <filename>CVS/Root</filename> contains the string
-      <quote>:pserver:</quote>, you have to run <command>cvs
-      login</command> once to get known to the NetBSD CVS server. The
-      <command>cvs</command> utility will then ask you for a password.
-      Just enter <quote>anoncvs</quote>. Then try again to update.</para>
-  </sect1>
+	in it, see the examples in
+	<filename>/usr/share/examples/supfiles</filename>, and that the
+	<filename>/usr/pkgsrc</filename> directory exists. Then, simply
+	run <command>sup -v
+	<replaceable>/path/to/your/supfile</replaceable></command>.</para>
+
+</sect2>
+<sect2 id="getting-via-cvs">
+<title>Via CVS</title>
+
+	<para>To get pkgsrc via CVS, make sure you have &man.cvs.1;
+	installed. To do an initial (full) checkout of pkgsrc, you first
+	have to set some environment variables. For the C-Shell,
+	type:</para>
+
+<screen>
+    &cprompt; <userinput>setenv CVSROOT anoncvs@anoncvs.NetBSD.org:/cvsroot</userinput>
+    &cprompt; <userinput>setenv CVS_RSH ssh</userinput>
+</screen>
+
+	<para>Or, the same for the bourne shell:</para>
+
+<screen>
+    &uprompt; <userinput>CVSROOT="anoncvs@anoncvs.NetBSD.org:/cvsroot"</userinput>
+    &uprompt; <userinput>CVS_RSH="ssh"</userinput>
+    &uprompt; <userinput>export CVSROOT CVS_RSH</userinput>
+</screen>
+
+	<para>Then, you change to the directory where you want to have
+	your copy of pkgsrc. In most cases this is
+	<filename>/usr</filename>. In that directory you run the
+	checkout command, which is <command>cvs -q checkout -P
+	pkgsrc</command> for the current branch and <command>cvs -q
+	checkout -rpkgsrc-2006Q1 -P pkgsrc</command> for the stable
+	branch. This command will create a directory called
+	<filename>pkgsrc</filename> with all the pkgsrc files in
+	it.</para>
+
+</sect2>
+</sect1>
+
+<sect1 id="uptodate">
+<title>Keeping pkgsrc up-to-date</title>
+
+	<para>The preferred way to keep pkgsrc up-to-date is via CVS
+	(which also works if you have first installed it via a tar
+	file). It saves bandwidth and hard disk activity, compared to
+	downloading the tar file again.</para>
+
+<sect2 id="uptodate-tar">
+<title>Via tar files</title>
+
+	<warning><para>Updating from tar file cannot detect or preserve
+	any changes you have done to your local copy of pkgsrc.
+	Therefore updating via CVS is strongly
+	recommended.</para></warning>
+	
+	<para>To update pkgsrc from a tar file, download the tar file as
+	explained above. Then, make sure that you have not made any
+	changes to the files in the pkgsrc directory. Remove the pkgsrc
+	directory and extract the new tar file. Done.</para>
+
+</sect2>
+<sect2 id="uptodate-cvs">
+<title>Via CVS</title>
+
+	<para>To update pkgsrc via CVS, make sure the environment
+	variable <varname>CVS_RSH</varname> is set as above. Then,
+	change to the pkgsrc directory and run <command>cvs -q update
+	-dP</command>. The <quote>-q</quote> option tells cvs to only
+	report those files that have changed. The <quote>-d</quote>
+	option fetches new packages (which is curiously not done by
+	default), and the <quote>-P</quote> option removes empty
+	directories after everything has been updated.</para>
+
+<sect3 id="uptodate-cvs-switch">
+<title>Switching between different pkgsrc branches</title>
+
+	<para>When updating pkgsrc, the CVS program keeps track of the
+	branch you selected. But if you, for whatever reason, want to
+	switch from the stable branch to the current one, you can do it
+	by adding the option <quote>-A</quote> after the
+	<quote>update</quote> keyword. To switch from the current branch
+	back to the stable branch, add the
+	<quote>-rpkgsrc-2006Q1</quote> option.</para>
+
+</sect3>
+<sect3 id="uptodate-cvs-changes">
+<title>What happens to my changes when updating?</title>
+
+	<para>When you update pkgsrc, the CVS program will only touch
+	those files that are registered in the CVS repository. That
+	means that any packages that you created on your own will stay
+	unmodified. If you change files that are managed by CVS, later
+	updates will try to merge your changes with those that have been
+	done by others. See the CVS manual, chapter
+	<quote>update</quote> for details.</para>
+
+</sect3>
+</sect2>
+</sect1>
 </chapter>