Rewrite portions of development.7 to make sense
in the world of subversion. Approved by: gjb MFC after: 2 weeks
This commit is contained in:
Eitan Adler
parent
b7e1113e8f
commit
1fce71e497
@ -23,7 +23,7 @@
|
||||
.\"
|
||||
.\" $FreeBSD$
|
||||
.\"
|
||||
.Dd May 2, 2012
|
||||
.Dd September 19, 2012
|
||||
.Dt DEVELOPMENT 7
|
||||
.Os
|
||||
.Sh NAME
|
||||
@ -48,7 +48,7 @@ kernel.
|
||||
The methods described
|
||||
here are as applicable to production installations as it is to development
|
||||
environments.
|
||||
You need a good 12-17GB of disk space on one machine to make this work
|
||||
You need approximately 10GB of disk space on one machine to make this work
|
||||
conveniently.
|
||||
.Sh SETTING UP THE ENVIRONMENT ON THE MASTER SERVER
|
||||
Your master server should always run a stable, production version of the
|
||||
@ -62,9 +62,9 @@ where you lose the environment and/or cannot recover from a mistake.
|
||||
.Pp
|
||||
Create a huge partition called
|
||||
.Pa /FreeBSD .
|
||||
8-12GB is recommended.
|
||||
Approximately 7GB is recommended.
|
||||
This partition will contain nearly all the development environment,
|
||||
including the CVS tree, broken-out source, and possibly even object files.
|
||||
including the subversion tree, broken-out source, and possibly even object files.
|
||||
You are going to export this partition to your other machines via a
|
||||
READ-ONLY NFS export so do not mix it with other more security-sensitive
|
||||
partitions.
|
||||
@ -89,70 +89,19 @@ I recommend a
|
||||
partition of at least 5GB.
|
||||
.Pp
|
||||
On the master server, use
|
||||
.Xr csup 1
|
||||
to automatically pull down and maintain
|
||||
.Xr svn 1
|
||||
to pull down and maintain
|
||||
the
|
||||
.Fx
|
||||
CVS archive once a day.
|
||||
source.
|
||||
The first pull will take a long time,
|
||||
it is several gigabytes, but once you have it,
|
||||
the daily synchronizations will be quite small.
|
||||
.Bd -literal -offset 4n
|
||||
mkdir /FreeBSD/FreeBSD-CVS
|
||||
rm -rf /home/ncvs
|
||||
ln -s /FreeBSD/FreeBSD-CVS /home/ncvs
|
||||
.Ed
|
||||
.Pp
|
||||
The
|
||||
.Xr cron 8
|
||||
job should look something like this (please randomize the time of
|
||||
day!).
|
||||
Note that you can use the
|
||||
.Xr csup 1
|
||||
configuration file example directly from
|
||||
.Pa /usr/share/examples
|
||||
without modification by supplying appropriate arguments
|
||||
to
|
||||
.Xr csup 1 .
|
||||
.Bd -literal -offset 4n
|
||||
33 6 * * * /usr/bin/csup -r 20 -L 2 -h cvsup.freebsd.org /usr/share/examples/cvsup/cvs-supfile
|
||||
.Ed
|
||||
.Pp
|
||||
Run the
|
||||
.Xr csup 1
|
||||
manually the first time to pull down the archive.
|
||||
It could take
|
||||
all day depending on how fast your connection is!
|
||||
You will run all
|
||||
.Xr csup 1
|
||||
and
|
||||
.Xr cvs 1
|
||||
the updates will be quite small.
|
||||
Run all
|
||||
.Xr svn 1
|
||||
operations as
|
||||
.Dq Li root
|
||||
and you need to set up a
|
||||
.Pa ~/.cvsrc
|
||||
.Pq Pa /root/.cvsrc
|
||||
file, as shown below, for proper
|
||||
.Xr cvs 1
|
||||
operation.
|
||||
Using
|
||||
.Pa ~/.cvsrc
|
||||
to specify
|
||||
.Xr cvs 1
|
||||
defaults is an excellent way to
|
||||
.Dq "file and forget" ,
|
||||
but you should never forget that you put them in there.
|
||||
.Bd -literal -offset 4n
|
||||
# cvs -q
|
||||
diff -u
|
||||
update -Pd
|
||||
checkout -P
|
||||
.Ed
|
||||
.Pp
|
||||
Now use
|
||||
.Xr cvs 1
|
||||
to check out a -STABLE source tree and a -CURRENT source tree,
|
||||
as well as ports and docs, to create your initial source environment.
|
||||
Keeping the broken-out source and ports in
|
||||
.Pa /FreeBSD
|
||||
allows you to export
|
||||
@ -160,71 +109,16 @@ it to other machines via read-only NFS.
|
||||
This also means you only need to edit/maintain files in one place and all
|
||||
your clients automatically pick up the changes.
|
||||
.Bd -literal -offset 4n
|
||||
mkdir /FreeBSD/FreeBSD-4.x
|
||||
mkdir /FreeBSD/FreeBSD-current
|
||||
|
||||
cd /FreeBSD/FreeBSD-4.x
|
||||
cvs -d /home/ncvs checkout -rRELENG_4 src
|
||||
|
||||
cd /FreeBSD/FreeBSD-current
|
||||
cvs -d /home/ncvs checkout src
|
||||
cvs -d /home/ncvs checkout ports
|
||||
cvs -d /home/ncvs checkout doc
|
||||
.Ed
|
||||
.Pp
|
||||
Now create a softlink for
|
||||
.Pa /usr/src
|
||||
and
|
||||
.Pa /usr/src2 .
|
||||
On the main server I always point
|
||||
.Pa /usr/src
|
||||
at -STABLE and
|
||||
.Pa /usr/src2
|
||||
at -CURRENT.
|
||||
On client machines I usually do not have a
|
||||
.Pa /usr/src2
|
||||
and I make
|
||||
.Pa /usr/src
|
||||
point at whatever version of
|
||||
.Fx
|
||||
the client box is intended to
|
||||
run.
|
||||
.Bd -literal -offset 4n
|
||||
mkdir /FreeBSD
|
||||
cd /FreeBSD
|
||||
svn co svn://svn.freebsd.org/ports/head ports
|
||||
svn co svn://svn.freebsd.org/doc/head doc
|
||||
svn co svn://svn.freebsd.org/base/head src
|
||||
cd /usr
|
||||
rm -rf src src2
|
||||
ln -s /FreeBSD/FreeBSD-4.x/src src (could be -CURRENT on a client)
|
||||
ln -s /FreeBSD/FreeBSD-current/src src2 (MASTER SERVER ONLY)
|
||||
rm -rf src
|
||||
ln -s /FreeBSD/src src
|
||||
.Ed
|
||||
.Pp
|
||||
Now you have to make a choice for
|
||||
.Pa /usr/obj .
|
||||
Well, hopefully you made it already and chose the partition method.
|
||||
If you
|
||||
chose poorly you probably intend to put it in
|
||||
.Pa /FreeBSD
|
||||
and, if so, this is
|
||||
what you want to do:
|
||||
.Bd -literal -offset 4n
|
||||
(ONLY IF YOU MADE A POOR CHOICE AND PUT /usr/obj in /FreeBSD!)
|
||||
mkdir /FreeBSD/obj
|
||||
cd /usr
|
||||
rm -rf obj
|
||||
ln -s /FreeBSD/obj obj
|
||||
.Ed
|
||||
.Pp
|
||||
Alternatively you may chose simply to leave
|
||||
.Pa /usr/obj
|
||||
in
|
||||
.Pa /usr .
|
||||
If your
|
||||
.Pa /usr
|
||||
is large enough this will work, but I do not recommend it for
|
||||
safety reasons
|
||||
.Pa ( /usr/obj
|
||||
is constantly being modified,
|
||||
.Pa /usr
|
||||
is not).
|
||||
.Pp
|
||||
Note that exporting
|
||||
.Pa /usr/obj
|
||||
via read-only NFS to your other boxes will
|
||||
@ -240,19 +134,17 @@ problems and issues down the line and presents a security problem as well.
|
||||
It is far easier to do builds on the master server and then only do installs
|
||||
on the clients.
|
||||
.Pp
|
||||
I usually maintain my ports tree via CVS.
|
||||
It is sitting right there in the master CVS archive and I have even told you
|
||||
to check it out (see above).
|
||||
I usually maintain my ports tree via svn or portsnap.
|
||||
With some fancy softlinks you can make the ports tree available both on your
|
||||
master server and on all of your other machines.
|
||||
Note that the ports tree exists only on the HEAD CVS branch, so its always
|
||||
-CURRENT even on a -STABLE box.
|
||||
Note that the ports tree exists only on the HEAD ports branch, so its always
|
||||
usable even on a -STABLE box.
|
||||
This is what you do:
|
||||
.Bd -literal -offset 4n
|
||||
(THESE COMMANDS ON THE MASTER SERVER AND ON ALL CLIENTS)
|
||||
cd /usr
|
||||
rm -rf ports
|
||||
ln -s /FreeBSD/FreeBSD-current/ports ports
|
||||
ln -s /FreeBSD/ports ports
|
||||
|
||||
cd /usr/ports (this pushes into the softlink)
|
||||
rm -rf distfiles (ON MASTER SERVER ONLY)
|
||||
@ -344,7 +236,7 @@ into the NFS-mounted environment.
|
||||
If a particular client is running -CURRENT,
|
||||
.Pa /usr/src
|
||||
should be a softlink to
|
||||
.Pa /FreeBSD/FreeBSD-current/src .
|
||||
.Pa /FreeBSD/src .
|
||||
If it is running -STABLE,
|
||||
.Pa /usr/src
|
||||
should be a softlink to
|
||||
@ -359,8 +251,8 @@ human variety) on a client.
|
||||
(ON EACH CLIENT)
|
||||
cd /usr
|
||||
rm -rf ports src
|
||||
ln -s /FreeBSD/FreeBSD-current/ports ports
|
||||
ln -s /FreeBSD/FreeBSD-XXX/src src
|
||||
ln -s /FreeBSD/ports ports
|
||||
ln -s /FreeBSD/src src
|
||||
.Ed
|
||||
.Pp
|
||||
Do not forget to create the working directories so you can build ports, as
|
||||
@ -521,11 +413,6 @@ subdirectory in
|
||||
which is typically local to the client.
|
||||
You can then do builds to your heart's content!
|
||||
.Sh MAINTAINING A LOCAL BRANCH
|
||||
I have described how to maintain two versions of the source tree, a stable
|
||||
version in
|
||||
.Pa /FreeBSD/FreeBSD-4.x
|
||||
and a current version in
|
||||
.Pa /FreeBSD/FreeBSD-current .
|
||||
There is absolutely nothing preventing you
|
||||
from breaking out other versions of the source tree
|
||||
into
|
||||
@ -548,135 +435,33 @@ which can build those other operating systems.
|
||||
Many developers choose to maintain a local branch of
|
||||
.Fx
|
||||
to test patches or build a custom distribution.
|
||||
This can be done with CVS or another source code management system
|
||||
(SubVersion, Perforce, BitKeeper) with its own repository.
|
||||
Since the main
|
||||
.Fx
|
||||
tree is based on CVS, the former is convenient.
|
||||
This can be done with svn or another source code management system
|
||||
(git, mercurial, Perforce, BitKeeper) with its own repository.
|
||||
.Pp
|
||||
First, you need to modify your
|
||||
.Xr csup 1
|
||||
environment to avoid it modifying
|
||||
the local changes you have committed to the repository.
|
||||
It is important to remove the
|
||||
.Ic delete
|
||||
keyword from your
|
||||
.Pa supfile
|
||||
and to add the
|
||||
.Pa CVSROOT
|
||||
subdirectory to your
|
||||
.Pa refuse
|
||||
file.
|
||||
For more information, see
|
||||
.Xr csup 1 .
|
||||
.Pp
|
||||
The
|
||||
.Fx
|
||||
version of
|
||||
.Xr cvs 1
|
||||
examines a custom environmental variable,
|
||||
.Ev CVS_LOCAL_BRANCH_NUM ,
|
||||
which specifies an integer to use when doing a
|
||||
.Xr cvs 1
|
||||
.Cm tag Ns / Ns Cm rtag .
|
||||
Set this number to something high (say 1000) to avoid colliding
|
||||
with potential future branches of the main repository.
|
||||
For example,
|
||||
branching a file with version 1.4 produces 1.4.1000.
|
||||
Future commits to this branch will produce revisions 1.4.1000.1,
|
||||
1.4.1000.2, etc.
|
||||
.Pp
|
||||
To fork your local branch, do:
|
||||
.Bd -literal -offset 4n
|
||||
cvs rtag -r RELENG_4 -b LOCAL_RELENG_4 src
|
||||
.Ed
|
||||
.Pp
|
||||
After this, you can check out a copy from your local repository using the
|
||||
new tag and begin making changes and committing them.
|
||||
For more information on using CVS, see
|
||||
.Xr cvs 1 .
|
||||
.Pp
|
||||
.Sy WARNING!
|
||||
The
|
||||
.Xr csup 1
|
||||
utility may blow away changes made on a local branch in
|
||||
some situations.
|
||||
This has been reported to occur when the master CVS repository is
|
||||
directly manipulated or an RCS file is changed.
|
||||
At this point,
|
||||
.Xr csup 1
|
||||
notices that the client and server have entirely
|
||||
different RCS files, so it does a full replace instead of trying to
|
||||
send just deltas.
|
||||
Ideally this situation should never arise, but in the real world it
|
||||
happens all the time.
|
||||
.Pp
|
||||
While this is the only scenario where the problem should crop up,
|
||||
there have been some suspicious-sounding reports of
|
||||
.Ev CVS_LOCAL_BRANCH_NUM
|
||||
lossage that cannot be explained by this alone.
|
||||
Bottom line is, if you value your local branch then you
|
||||
should back it up before every update.
|
||||
.Sh UPDATING VIA CVS
|
||||
The advantage of using
|
||||
.Xr csup 1
|
||||
to maintain an updated copy of the CVS
|
||||
repository instead of using it to maintain source trees directly is that you
|
||||
can then pick and choose when you bring your source tree (or pieces of your
|
||||
source tree) up to date.
|
||||
.Sh "UPDATING VIA SVN"
|
||||
By using a
|
||||
.Xr cron 8
|
||||
job to maintain an updated CVS repository, you can update
|
||||
your source tree at any time without any network cost as follows:
|
||||
job to maintain an updated svn repository,
|
||||
the source tree can be
|
||||
updated at any time as follows:
|
||||
.Bd -literal -offset 4n
|
||||
(on the main development server)
|
||||
cd /usr/src
|
||||
cvs -d /home/ncvs update
|
||||
cd /usr/src2
|
||||
cvs -d /home/ncvs update
|
||||
cd /usr/ports
|
||||
cvs -d /home/ncvs update
|
||||
cd /usr
|
||||
svn update src doc ports
|
||||
.Ed
|
||||
.Pp
|
||||
It is that simple, and since you are exporting the whole lot to your
|
||||
clients, your clients have immediate visibility into the updated
|
||||
source.
|
||||
This is a good time to also remind you that most of the
|
||||
.Xr cvs 1
|
||||
.Xr svn 1
|
||||
operations you do will be done as
|
||||
.Dq Li root ,
|
||||
and that certain options are
|
||||
required for CVS to operate properly on the
|
||||
.Fx
|
||||
repository.
|
||||
For example,
|
||||
.Fl Pd
|
||||
is necessary when running
|
||||
.Nm cvs Cm update .
|
||||
These options are typically placed in your
|
||||
.Pa ~/.cvsrc
|
||||
(as already described)
|
||||
so you do not have to re-specify them every time you run a
|
||||
.Xr cvs 1
|
||||
command.
|
||||
Maintaining the CVS repository also gives you far more flexibility
|
||||
in regards to breaking out multiple versions of the source tree.
|
||||
.Dq Li root .
|
||||
It is a good idea to give your
|
||||
.Pa /FreeBSD
|
||||
partition a lot of space (I recommend
|
||||
8-12GB) precisely for that reason.
|
||||
If you can make it 15GB I would do it.
|
||||
10-15GB) precisely for that reason.
|
||||
.Pp
|
||||
I generally do not
|
||||
.Nm cvs Cm update
|
||||
via a
|
||||
.Xr cron 8
|
||||
job.
|
||||
This is because I generally want the source to not change out from under me
|
||||
when I am developing code.
|
||||
Instead I manually update the source every so often...\& when I feel it is
|
||||
a good time.
|
||||
My recommendation is to only keep the CVS repository synchronized via
|
||||
.Xr cron 8 .
|
||||
.Sh SEE ALSO
|
||||
.Xr crontab 1 ,
|
||||
@ -696,3 +481,9 @@ and first appeared
|
||||
in
|
||||
.Fx 5.0 ,
|
||||
December 2002.
|
||||
It was since extensively modified by
|
||||
.An Eitan Adler Aq eadler@FreeBSD.org
|
||||
to reflect the repository conversion from
|
||||
.Xr cvs
|
||||
to
|
||||
.Xr svn .
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user