Subject: [docathon] converted howto-pullup.html and build-release.html
To: None <netbsd-docs@netbsd.org>
From: Mark Weinem <mark.weinem@alumni.uni-duisburg-essen.de>
List: netbsd-docs
Date: 04/09/2007 00:43:37
--Boundary-00=_ZAXGGYvCVwxsqQ6
Content-Type: text/plain;
charset="utf-8"
Content-Transfer-Encoding: 7bit
Content-Disposition: inline
The html-only files howto-pullup.html and build-release.html
from /htdocs/developers/releng are now converted to xml.
Patch is attached and the xml files also. Please review. The "<webpage>"
attributes are still incomplete.
If you're committing a patch, please be sure to update the
according status entry at
http://wiki.netbsd.se/index.php/Hackathon5#List_of_.list_files
Best regards, Mark
--
Mark Weinem
Jabber: weinem@jabber.cz
PGP-Key available
--Boundary-00=_ZAXGGYvCVwxsqQ6
Content-Type: text/x-diff;
charset="utf-8";
name="releng.diff"
Content-Transfer-Encoding: 7bit
Content-Disposition: attachment;
filename="releng.diff"
Index: layout.xml
===================================================================
RCS file: /cvsroot/htdocs/layout.xml,v
retrieving revision 1.272
diff -u -r1.272 layout.xml
--- layout.xml 8 Apr 2007 14:23:20 -0000 1.272
+++ layout.xml 8 Apr 2007 21:54:27 -0000
@@ -425,6 +425,8 @@
</tocentry>
<tocentry page="developers/releng/index.xml" dir="releng" filename=".">
<tocentry page="developers/releng/pullups.xml" filename="pullups.html"/>
+ <tocentry page="developers/releng/build-release.xml" filename="build-release.html"/>
+ <tocentry page="developers/releng/howto-pullup.xml" filename="howto-pullup.html"/>
</tocentry>
<tocentry page="developers/restricted.xml" filename="restricted.html"/>
<tocentry page="developers/security.xml" filename="security.html"/>
Index: Makefile
===================================================================
RCS file: /cvsroot/htdocs/developers/releng/Makefile,v
retrieving revision 1.4
diff -u -r1.4 Makefile
--- Makefile 14 Oct 2005 09:00:02 -0000 1.4
+++ Makefile 8 Apr 2007 21:59:16 -0000
@@ -1,5 +1,5 @@
# $NetBSD: Makefile,v 1.4 2005/10/14 09:00:02 rillig Exp $
-XMLDOCS= index pullups
+XMLDOCS= index pullups build-release howto-pullup
.include "../../share/mk/web.site.mk"
Index: build-release.xml
===================================================================
RCS file: build-release.xml
diff -N build-release.xml
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ build-release.xml 8 Apr 2007 21:59:16 -0000
@@ -0,0 +1,203 @@
+<?xml version="1.0"?>
+<!DOCTYPE webpage
+ PUBLIC "-//NetBSD//DTD Website-based NetBSD Extension//EN"
+ "http://www.NetBSD.org/XML/htdocs/lang/share/xml/website-netbsd.dtd">
+
+<webpage id="">
+<config param="desc" value=""/>
+<config param="cvstag" value="$NetBSD$"/>
+<config param="rcsdate" value="$Date$"/>
+<head>
+<!-- Copyright (c) 1994-2007
+ The NetBSD Foundation, Inc. ALL RIGHTS RESERVED. -->
+
+<title>NetBSD Developer Documentation: Building and Packaging a Release
+or Snapshot</title>
+</head>
+
+<para>
+ These instructions are for building releases and snapshots of NetBSD
+ version 1.5 or later. They cover the steps to go from a source tree to
+ a set of .tgz files comprising a release. You can also make a
+ snapshot this way, though of course it should be clearly labeled as
+ such.</para>
+
+<note>
+ When uploading a snapshot, please do not
+ forget to update
+ the <ulink url="../features/">feature
+ table</ulink>.</note>
+
+<para>
+ The NetBSD release format is described in the
+ <code>&man.release.7;</code> manual page.
+ The file <code>/usr/share/mk/bsd.README</code> is
+ also useful documentation.</para>
+
+<para>
+ The .tgz files are built in two steps. In the first, you build
+ the base distribution. The second step is to build the X Window System
+ distribution files. Some architectures require extra steps to build
+ installation materials (such as boot loaders or boot floppy images).
+ All of the following steps assume that you change to `src' to get to
+ the root of your NetBSD source tree.</para>
+
+<para>
+ In earlier versions, there was a (US) domestic section of NetBSD
+ containing
+ code based on DES which could not be legally exported from the United
+ States or Canada. For more details please see our page on
+ <ulink url="../../Misc/crypto-export.html">Exportability of NetBSD
+ crypto code</ulink>.</para>
+
+<para>
+The steps to build and package a release are as follows.</para>
+
+<sect1 id="" role="toc">
+
+
+<sect2 id="">
+
+
+
+
+<sect3>
+<title> I. Building the Base System </title>
+
+<orderedlist>
+ <listitem> Set the variables you will need for your build. The
+ following can be set in the environment (lowest priority) or in
+ <code>/etc/mk.conf</code> or on the make command
+ line (highest priority).
+ Here is an example <code>/etc/mk.conf</code> file:
+ <screen>
+ # The location of your source tree.
+ BSDSRCDIR=/home/cjs/netbsd/src
+ # The location of the object files produced by the build.
+ BSDOBJDIR=/home/cjs/netbsd/obj
+ # These two aren't really necessary; they just make life
+ # easier if/when you rebuild later. See /usr/share/mk/bsd.README
+ # for exact definitions. See also the top-level Makefile in src.
+ BUILD=1
+ UPDATE=1
+ # Where to install the binaries
+ DESTDIR=/usr/home/cjs/netbsd/destdir
+ # Where to put the actual release files
+ RELEASEDIR=/usr/home/cjs/netbsd/release
+ </screen>
+
+ <note>Some scripts in the src directory require
+ <code>DESTDIR</code> set in the environment (e.g. checkflist,
+ see below). Also setting
+ <code>DESTDIR</code> in
+ <code>/etc/mk.conf</code> may affect building of
+ packages in pkgsrc.
+ You may find it easier and safer to set <code>DESTDIR</code> and
+ <code>RELEASEDIR</code> in the environment or on
+ the make command line.</note>
+ </listitem>
+
+ <listitem> Change to your source directory, and build the release.
+ <screen>
+ cd src
+ make obj
+ make release
+ </screen>
+ Or you may wish to set some variables on the make command line. For
+ example:
+ <screen>
+make DESTDIR=/home/destdir RELEASEDIR=/home/releasedir release
+ </screen></listitem>
+
+</orderedlist>
+</sect3>
+
+
+<sect3>
+<title> II. Building X </title>
+
+<para> The information for building and packaging the X sets is similar
+ to the main sets above.
+ Change directory into your X source directory and type:
+ <screen>
+ make release
+ </screen>
+ or if you are specifying variables on the make command line:
+ <screen>
+ make DESTDIR=/home/destdir RELEASEDIR=/home/release
+</screen></para>
+
+<note>
+ Note that I and II assume that the set-lists are up-to-date.
+ You may want to check them. Instead of doing `make release'
+ in each case:
+ <screen>
+ cd src
+ make obj
+ # Build the object code and install it.
+ make build
+ # Install the final bits of the distribution.
+ cd src/etc & make distribution
+ # Make the xsrc object code and install it.
+ cd xsrc & make build
+</screen></note>
+
+ <para> To check the set-lists for accuracy, update them appropriately,
+ and then make the tar files for the sets, do the following:
+ <screen>
+ cd src/distrib/sets
+ sh ./checkflist -both
+ </screen>
+ Now edit the files src/distrib/sets/lists/*/* as necessary.
+ <screen>
+ cd src/etc
+ make INSTALL_DONE=1 release
+ cd xsrc
+ make INSTALL_DONE=1 release
+</screen></para>
+
+</sect3>
+
+<sect3>
+<title> III. Building Installation Materials </title>
+
+ <para>
+ On most architectures, the basic installation materials are
+ handled by the `make release' in step I above. However, sometimes
+ there are
+ architecture-dependent things that need to be done
+ under src/distrib/<code>arch</code>; some of these are not yet
+ documented here. The results then need to be put in
+<code>$RELEASEDIR</code>
+ by hand (following the conventions listed in the
+ <code>&man.release.7;</code> manual page).</para>
+
+<para>
+ To produce an ISO9660 image of a release for making CD-ROMs, do
+ steps I and II and ensure that you have <code>mkisofs</code> (from
+ the <code><ulink
+url="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/sysutils/cdrtools/
+README.html">
+ cdrtools</ulink></code> package) installed on your machine and in your
+path.
+ Then:
+ <screen>
+ cd src/etc
+ make iso-image
+ </screen>
+will make an ISO9660 image and save it in
+<code>$RELEASEDIR/installation/cdrom</code>.</para>
+
+
+
+ <para>
+ This page can still use a lot of work. Comments and updates
+ for this page may be sent to <ulink url="mailto:cjs@NetBSD.org">
+ cjs@NetBSD.org</ulink>.</para>
+
+</sect3>
+
+
+</sect2>
+</sect1>
+</webpage>
Index: howto-pullup.xml
===================================================================
RCS file: howto-pullup.xml
diff -N howto-pullup.xml
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ howto-pullup.xml 8 Apr 2007 21:59:16 -0000
@@ -0,0 +1,136 @@
+<?xml version="1.0"?>
+<!DOCTYPE webpage
+ PUBLIC "-//NetBSD//DTD Website-based NetBSD Extension//EN"
+ "http://www.NetBSD.org/XML/htdocs/lang/share/xml/website-netbsd.dtd">
+
+<webpage id="">
+<config param="desc" value=""/>
+<config param="cvstag" value="$NetBSD$"/>
+<config param="rcsdate" value="$Date$"/>
+<head>
+<!-- Copyright (c) 1994-2007
+ The NetBSD Foundation, Inc. ALL RIGHTS RESERVED. -->
+
+<title>How to actually perform a CVS pull-up</title>
+</head>
+
+
+
+<sect1 id="">
+
+
+
+<para>For a given release cycle, typically in the beginning, developers
+may
+be expected to do pull-ups themselves after approval from the release
+engineering team.</para>
+
+<para>Let us say you are pulling up the changes between
+<code>foo.c</code>
+1.19 and 1.21.</para>
+
+<note>
+ The idea of "pulling up to 1.21" is meaningless -- you
+are always applying diffs between two versions. One of them might be the
+base tag, but in any case, since you are pulling up diffs, you always
+need to know the two versions between which the changes
+occurred.)</note>
+
+<para>First, and foremost, make sure you are starting with a clean
+ <code>foo.c</code>
+ <screen>
+ cvs update -rnetbsd-1-4 foo.c
+ </screen>
+ </para>
+
+<para>(See note at the end about the effect of this command.)</para>
+
+
+<para>Then, you need to patch up foo.c to add the changes you
+want to pull
+up. There are two ways of doing this. You can create a patch file and
+apply it, or you can use cvs update's <code>-j</code> flag to avoid
+needing that.</para>
+
+<para>The incantation:
+ <screen>
+ cvs diff -kk -c -r1.19 -r1.21 foo.c >/tmp/patch
+ </screen>
+ will produce a patch file which you can then apply by doing
+ <screen>
+ patch </tmp/patch
+ </screen>
+ or by feeding it directly to patch via a pipe. The command
+ <screen>
+ cvs update -kk -j1.19 -j1.21 foo.c
+ </screen>
+ is essentially equivalent to the two steps listed above, and will
+ similarly patch your file.</para>
+
+<para>Now manually examine the file to make sure What You Wanted Done Is
+ Done. If you are trying to make <code>foo.c</code> identical to the
+ head (presumably 1.21 is the head and 1.19 was the branch point or
+ some such), you can do a
+ <screen>
+ cvs diff -kk -r1.21 foo.c
+ </screen>
+ and this should produce no diff (-kk prevents the expansion of RCS
+ IDs). If <code>foo.c</code> isn't supposed to be identical to the
+ head, you are going to have to make sure things are okay manually or
+ use creative sets of cvs diffs to assure that what you wanted done was
+ done.</para>
+
+
+<para>In any case, once done, do a:
+ <screen>
+ cvs commit foo.c
+ </screen>
+ The format of the commit message on a release branch has over time
+ been formalized to ease tracking and maintenance. The format of the
+ first line of the commit message should be one of the following:
+ <itemizedlist>
+ <listitem><code>Pull up revision 1.45 (requested by
+ <emphasis>user</emphasis>):</code></listitem>
+ <listitem><code>Pull up revision 1.45 (via patch, requested by
+ <emphasis>user</emphasis>):</code></listitem>
+ <listitem><code>Pull up revisions 1.1-1.5 (new, requested by
+ <emphasis>user</emphasis>):</code></listitem>
+ <listitem><code>Apply patch (requested by
+ <emphasis>user</emphasis>):</code></listitem>
+ </itemizedlist>
+ or obvious minor variations over these themes. The rest of the commit
+message shall contain a free-format text explaining why the pull-up
+was done. This message should preferably be an "externally sensible"
+message explaining <emphasis role="bold">what</emphasis> was fixed, not the exact details of how
+it was done. The text of this message should be indented by two
+spaces, and for patch releases this text should also go in as an entry
+in the appropriate CHANGES file.</para>
+
+<para>If the pull-up fixes a formally reported problem, this
+ should be notedas <emphasis role="bold">Fixes PR#nnnn</emphasis> at
+ the end of the commit message text.</para>
+
+<para>The fact that we want exact revision numbers recorded in the
+ commit message means, BTW, that you must <emphasis>not</emphasis> do a
+ bunch of pull-ups
+ in the same directory and then commit them with a message like "sync
+ with trunk," because that won't say what versions you pulled
+ up.</para>
+
+
+<note>
+ The command
+ <screen>
+ cvs update -rnetbsd-1-4 foo.c
+ </screen>
+ will glue <code>foo.c</code> to "netbsd-1-4" (see what happens to
+ <code>CVS/Entries</code>), and subsequent CVS commands will thus apply
+ to this release until you unstick this "glue" with
+ <screen>
+ cvs update -A foo.c
+ </screen></note>
+
+
+</sect1>
+
+</webpage>
--Boundary-00=_ZAXGGYvCVwxsqQ6
Content-Type: text/xml;
charset="utf-8";
name="build-release.xml"
Content-Transfer-Encoding: 7bit
Content-Disposition: attachment;
filename="build-release.xml"
<?xml version="1.0"?>
<!DOCTYPE webpage
PUBLIC "-//NetBSD//DTD Website-based NetBSD Extension//EN"
"http://www.NetBSD.org/XML/htdocs/lang/share/xml/website-netbsd.dtd">
<webpage id="">
<config param="desc" value=""/>
<config param="cvstag" value="$NetBSD$"/>
<config param="rcsdate" value="$Date$"/>
<head>
<!-- Copyright (c) 1994-2007
The NetBSD Foundation, Inc. ALL RIGHTS RESERVED. -->
<title>NetBSD Developer Documentation: Building and Packaging a Release
or Snapshot</title>
</head>
<para>
These instructions are for building releases and snapshots of NetBSD
version 1.5 or later. They cover the steps to go from a source tree to
a set of .tgz files comprising a release. You can also make a
snapshot this way, though of course it should be clearly labeled as
such.</para>
<note>
When uploading a snapshot, please do not
forget to update
the <ulink url="../features/">feature
table</ulink>.</note>
<para>
The NetBSD release format is described in the
<code>&man.release.7;</code> manual page.
The file <code>/usr/share/mk/bsd.README</code> is
also useful documentation.</para>
<para>
The .tgz files are built in two steps. In the first, you build
the base distribution. The second step is to build the X Window System
distribution files. Some architectures require extra steps to build
installation materials (such as boot loaders or boot floppy images).
All of the following steps assume that you change to `src' to get to
the root of your NetBSD source tree.</para>
<para>
In earlier versions, there was a (US) domestic section of NetBSD
containing
code based on DES which could not be legally exported from the United
States or Canada. For more details please see our page on
<ulink url="../../Misc/crypto-export.html">Exportability of NetBSD
crypto code</ulink>.</para>
<para>
The steps to build and package a release are as follows.</para>
<sect1 id="" role="toc">
<sect2 id="">
<sect3>
<title> I. Building the Base System </title>
<orderedlist>
<listitem> Set the variables you will need for your build. The
following can be set in the environment (lowest priority) or in
<code>/etc/mk.conf</code> or on the make command
line (highest priority).
Here is an example <code>/etc/mk.conf</code> file:
<screen>
# The location of your source tree.
BSDSRCDIR=/home/cjs/netbsd/src
# The location of the object files produced by the build.
BSDOBJDIR=/home/cjs/netbsd/obj
# These two aren't really necessary; they just make life
# easier if/when you rebuild later. See /usr/share/mk/bsd.README
# for exact definitions. See also the top-level Makefile in src.
BUILD=1
UPDATE=1
# Where to install the binaries
DESTDIR=/usr/home/cjs/netbsd/destdir
# Where to put the actual release files
RELEASEDIR=/usr/home/cjs/netbsd/release
</screen>
<note>Some scripts in the src directory require
<code>DESTDIR</code> set in the environment (e.g. checkflist,
see below). Also setting
<code>DESTDIR</code> in
<code>/etc/mk.conf</code> may affect building of
packages in pkgsrc.
You may find it easier and safer to set <code>DESTDIR</code> and
<code>RELEASEDIR</code> in the environment or on
the make command line.</note>
</listitem>
<listitem> Change to your source directory, and build the release.
<screen>
cd src
make obj
make release
</screen>
Or you may wish to set some variables on the make command line. For
example:
<screen>
make DESTDIR=/home/destdir RELEASEDIR=/home/releasedir release
</screen></listitem>
</orderedlist>
</sect3>
<sect3>
<title> II. Building X </title>
<para> The information for building and packaging the X sets is similar
to the main sets above.
Change directory into your X source directory and type:
<screen>
make release
</screen>
or if you are specifying variables on the make command line:
<screen>
make DESTDIR=/home/destdir RELEASEDIR=/home/release
</screen></para>
<note>
Note that I and II assume that the set-lists are up-to-date.
You may want to check them. Instead of doing `make release'
in each case:
<screen>
cd src
make obj
# Build the object code and install it.
make build
# Install the final bits of the distribution.
cd src/etc & make distribution
# Make the xsrc object code and install it.
cd xsrc & make build
</screen></note>
<para> To check the set-lists for accuracy, update them appropriately,
and then make the tar files for the sets, do the following:
<screen>
cd src/distrib/sets
sh ./checkflist -both
</screen>
Now edit the files src/distrib/sets/lists/*/* as necessary.
<screen>
cd src/etc
make INSTALL_DONE=1 release
cd xsrc
make INSTALL_DONE=1 release
</screen></para>
</sect3>
<sect3>
<title> III. Building Installation Materials </title>
<para>
On most architectures, the basic installation materials are
handled by the `make release' in step I above. However, sometimes
there are
architecture-dependent things that need to be done
under src/distrib/<code>arch</code>; some of these are not yet
documented here. The results then need to be put in
<code>$RELEASEDIR</code>
by hand (following the conventions listed in the
<code>&man.release.7;</code> manual page).</para>
<para>
To produce an ISO9660 image of a release for making CD-ROMs, do
steps I and II and ensure that you have <code>mkisofs</code> (from
the <code><ulink
url="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/sysutils/cdrtools/
README.html">
cdrtools</ulink></code> package) installed on your machine and in your
path.
Then:
<screen>
cd src/etc
make iso-image
</screen>
will make an ISO9660 image and save it in
<code>$RELEASEDIR/installation/cdrom</code>.</para>
<para>
This page can still use a lot of work. Comments and updates
for this page may be sent to <ulink url="mailto:cjs@NetBSD.org">
cjs@NetBSD.org</ulink>.</para>
</sect3>
</sect2>
</sect1>
</webpage>
--Boundary-00=_ZAXGGYvCVwxsqQ6
Content-Type: text/xml;
charset="utf-8";
name="howto-pullup.xml"
Content-Transfer-Encoding: 7bit
Content-Disposition: attachment;
filename="howto-pullup.xml"
<?xml version="1.0"?>
<!DOCTYPE webpage
PUBLIC "-//NetBSD//DTD Website-based NetBSD Extension//EN"
"http://www.NetBSD.org/XML/htdocs/lang/share/xml/website-netbsd.dtd">
<webpage id="">
<config param="desc" value=""/>
<config param="cvstag" value="$NetBSD$"/>
<config param="rcsdate" value="$Date$"/>
<head>
<!-- Copyright (c) 1994-2007
The NetBSD Foundation, Inc. ALL RIGHTS RESERVED. -->
<title>How to actually perform a CVS pull-up</title>
</head>
<sect1 id="">
<para>For a given release cycle, typically in the beginning, developers
may
be expected to do pull-ups themselves after approval from the release
engineering team.</para>
<para>Let us say you are pulling up the changes between
<code>foo.c</code>
1.19 and 1.21.</para>
<note>
The idea of "pulling up to 1.21" is meaningless -- you
are always applying diffs between two versions. One of them might be the
base tag, but in any case, since you are pulling up diffs, you always
need to know the two versions between which the changes
occurred.)</note>
<para>First, and foremost, make sure you are starting with a clean
<code>foo.c</code>
<screen>
cvs update -rnetbsd-1-4 foo.c
</screen>
</para>
<para>(See note at the end about the effect of this command.)</para>
<para>Then, you need to patch up foo.c to add the changes you
want to pull
up. There are two ways of doing this. You can create a patch file and
apply it, or you can use cvs update's <code>-j</code> flag to avoid
needing that.</para>
<para>The incantation:
<screen>
cvs diff -kk -c -r1.19 -r1.21 foo.c >/tmp/patch
</screen>
will produce a patch file which you can then apply by doing
<screen>
patch </tmp/patch
</screen>
or by feeding it directly to patch via a pipe. The command
<screen>
cvs update -kk -j1.19 -j1.21 foo.c
</screen>
is essentially equivalent to the two steps listed above, and will
similarly patch your file.</para>
<para>Now manually examine the file to make sure What You Wanted Done Is
Done. If you are trying to make <code>foo.c</code> identical to the
head (presumably 1.21 is the head and 1.19 was the branch point or
some such), you can do a
<screen>
cvs diff -kk -r1.21 foo.c
</screen>
and this should produce no diff (-kk prevents the expansion of RCS
IDs). If <code>foo.c</code> isn't supposed to be identical to the
head, you are going to have to make sure things are okay manually or
use creative sets of cvs diffs to assure that what you wanted done was
done.</para>
<para>In any case, once done, do a:
<screen>
cvs commit foo.c
</screen>
The format of the commit message on a release branch has over time
been formalized to ease tracking and maintenance. The format of the
first line of the commit message should be one of the following:
<itemizedlist>
<listitem><code>Pull up revision 1.45 (requested by
<emphasis>user</emphasis>):</code></listitem>
<listitem><code>Pull up revision 1.45 (via patch, requested by
<emphasis>user</emphasis>):</code></listitem>
<listitem><code>Pull up revisions 1.1-1.5 (new, requested by
<emphasis>user</emphasis>):</code></listitem>
<listitem><code>Apply patch (requested by
<emphasis>user</emphasis>):</code></listitem>
</itemizedlist>
or obvious minor variations over these themes. The rest of the commit
message shall contain a free-format text explaining why the pull-up
was done. This message should preferably be an "externally sensible"
message explaining <emphasis role="bold">what</emphasis> was fixed, not the exact details of how
it was done. The text of this message should be indented by two
spaces, and for patch releases this text should also go in as an entry
in the appropriate CHANGES file.</para>
<para>If the pull-up fixes a formally reported problem, this
should be notedas <emphasis role="bold">Fixes PR#nnnn</emphasis> at
the end of the commit message text.</para>
<para>The fact that we want exact revision numbers recorded in the
commit message means, BTW, that you must <emphasis>not</emphasis> do a
bunch of pull-ups
in the same directory and then commit them with a message like "sync
with trunk," because that won't say what versions you pulled
up.</para>
<note>
The command
<screen>
cvs update -rnetbsd-1-4 foo.c
</screen>
will glue <code>foo.c</code> to "netbsd-1-4" (see what happens to
<code>CVS/Entries</code>), and subsequent CVS commands will thus apply
to this release until you unstick this "glue" with
<screen>
cvs update -A foo.c
</screen></note>
</sect1>
</webpage>
--Boundary-00=_ZAXGGYvCVwxsqQ6--