1 .\" Copyright (C) 1998 Matthew Dillon. All rights reserved.
3 .\" Redistribution and use in source and binary forms, with or without
4 .\" modification, are permitted provided that the following conditions
6 .\" 1. Redistributions of source code must retain the above copyright
7 .\" notice, this list of conditions and the following disclaimer.
8 .\" 2. Redistributions in binary form must reproduce the above copyright
9 .\" notice, this list of conditions and the following disclaimer in the
10 .\" documentation and/or other materials provided with the distribution.
12 .\" THIS SOFTWARE IS PROVIDED BY AUTHOR AND CONTRIBUTORS ``AS IS'' AND
13 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
14 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
15 .\" ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE
16 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
17 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
18 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
19 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
20 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
21 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
31 .Nd "introduction to development with the FreeBSD codebase"
33 This manual page describes how an ordinary system operator,
35 administrator, or developer
36 can, without any special permission, obtain, maintain, and modify the
38 codebase as well as how to maintain a master build which can
39 then be exported to other machines in your network.
41 is targeted to system operators, programmers, and developers.
43 Please note that what is being described here is based on a complete
45 environment, not just the
49 here are as applicable to production installations as it is to development
51 You need a good 12-17GB of disk space on one machine to make this work
53 .Sh SETTING UP THE ENVIRONMENT ON THE MASTER SERVER
54 Your master server should always run a stable, production version of the
57 This does not prevent you from doing -CURRENT
58 builds or development.
59 The last thing you want to do is to run an
60 unstable environment on your master server which could lead to a situation
61 where you lose the environment and/or cannot recover from a mistake.
63 Create a huge partition called
65 8-12GB is recommended.
66 This partition will contain nearly all the development environment,
67 including the CVS tree, broken-out source, and possibly even object files.
68 You are going to export this partition to your other machines via a
69 READ-ONLY NFS export so do not mix it with other more security-sensitive
72 You have to make a choice in regards to
81 I recommend making it a separate partition for several reasons.
83 as a safety measure since this partition is written to a great deal.
84 Second, because you typically do not have to back it up.
85 Third, because it makes it far easier to mix and match the development
86 environments which are described later in this document.
89 partition of at least 5GB.
91 On the master server, use
92 .Xr cvsup 1 Pq Pa ports/net/cvsup
93 to automatically pull down and maintain
96 CVS archive once a day.
97 The first pull will take a long time,
98 it is several gigabytes, but once you have it,
99 the daily synchronizations will be quite small.
100 .Bd -literal -offset 4n
101 mkdir /FreeBSD/FreeBSD-CVS
103 ln -s /FreeBSD/FreeBSD-CVS /home/ncvs
108 job should look something like this (please randomize the time of
110 Note that you can use the
112 configuration file example directly from
113 .Pa /usr/share/examples
114 without modification by supplying appropriate arguments
117 .Bd -literal -offset 4n
118 33 6 * * * /usr/local/bin/cvsup -g -r 20 -L 2 -h cvsup.freebsd.org /usr/share/examples/cvsup/cvs-supfile
123 manually the first time to pull down the archive.
125 all day depending on how fast your connection is!
132 and you need to set up a
135 file, as shown below, for proper
142 defaults is an excellent way to
143 .Dq "file and forget" ,
144 but you should never forget that you put them in there.
145 .Bd -literal -offset 4n
154 to check out a -STABLE source tree and a -CURRENT source tree,
155 as well as ports and docs, to create your initial source environment.
156 Keeping the broken-out source and ports in
159 it to other machines via read-only NFS.
160 This also means you only need to edit/maintain files in one place and all
161 your clients automatically pick up the changes.
162 .Bd -literal -offset 4n
163 mkdir /FreeBSD/FreeBSD-4.x
164 mkdir /FreeBSD/FreeBSD-current
166 cd /FreeBSD/FreeBSD-4.x
167 cvs -d /home/ncvs checkout -rRELENG_4 src
169 cd /FreeBSD/FreeBSD-current
170 cvs -d /home/ncvs checkout src
171 cvs -d /home/ncvs checkout ports
172 cvs -d /home/ncvs checkout doc
175 Now create a softlink for
179 On the main server I always point
184 On client machines I usually do not have a
188 point at whatever version of
190 the client box is intended to
192 .Bd -literal -offset 4n
195 ln -s /FreeBSD/FreeBSD-4.x/src src (could be -CURRENT on a client)
196 ln -s /FreeBSD/FreeBSD-current/src src2 (MASTER SERVER ONLY)
199 Now you have to make a choice for
201 Well, hopefully you made it already and chose the partition method.
203 chose poorly you probably intend to put it in
207 .Bd -literal -offset 4n
208 (ONLY IF YOU MADE A POOR CHOICE AND PUT /usr/obj in /FreeBSD!)
212 ln -s /FreeBSD/obj obj
215 Alternatively you may chose simply to leave
221 is large enough this will work, but I do not recommend it for
224 is constantly being modified,
230 via read-only NFS to your other boxes will
231 allow you to build on your main server and install from your other boxes.
232 If you also want to do builds on some or all of the clients you can simply
235 be a local directory on those clients.
236 You should never export
238 read-write, it will lead to all sorts of
239 problems and issues down the line and presents a security problem as well.
240 It is far easier to do builds on the master server and then only do installs
243 I usually maintain my ports tree via CVS.
244 It is sitting right there in the master CVS archive and I have even told you
245 to check it out (see above).
246 With some fancy softlinks you can make the ports tree available both on your
247 master server and on all of your other machines.
248 Note that the ports tree exists only on the HEAD CVS branch, so its always
249 -CURRENT even on a -STABLE box.
251 .Bd -literal -offset 4n
252 (THESE COMMANDS ON THE MASTER SERVER AND ON ALL CLIENTS)
255 ln -s /FreeBSD/FreeBSD-current/ports ports
257 cd /usr/ports (this pushes into the softlink)
258 rm -rf distfiles (ON MASTER SERVER ONLY)
259 ln -s /usr/ports.distfiles distfiles (ON MASTER SERVER ONLY)
261 mkdir /usr/ports.distfiles
262 mkdir /usr/ports.workdir
267 is softlinked into what will be read-only on all of your
268 clients, you have to tell the ports system to use a different working
269 directory to hold ports builds.
270 You want to add a line to your
272 file on the master server
273 and on all your clients:
274 .Bd -literal -offset 4n
275 WRKDIRPREFIX=/usr/ports.workdir
278 You should try to make the directory you use for the ports working directory
279 as well as the directory used to hold distfiles consistent across all of your
281 If there is not enough room in
282 .Pa /usr/ports.distfiles
284 .Pa /usr/ports.workdir
285 I usually make those softlinks (since this is on
287 these are per-machine) to
288 where the distfiles and working space really are.
289 .Sh EXPORTING VIA NFS FROM THE MASTER SERVER
290 The master server needs to export
295 rest of your machines can get at them.
296 I strongly recommend using a read-only export for both security and safety.
297 The environment I am describing in this manual page is designed primarily
298 around read-only NFS exports.
299 Your exports file on the master server should contain the following lines:
300 .Bd -literal -offset 4n
301 /FreeBSD -ro -alldirs -maproot=root: -network YOURLAN -mask YOURLANMASK
302 /usr/obj -ro -alldirs -maproot=root: -network YOURLAN -mask YOURLANMASK
305 Of course, NFS server operations must also be configured on that machine.
306 This is typically done via your
308 .Bd -literal -offset 4n
309 nfs_server_enable="YES"
310 nfs_server_flags="-u -t -n 4"
312 .Sh THE CLIENT ENVIRONMENT
313 All of your client machines can import the development/build environment
314 directory simply by NFS mounting
318 from the master server.
321 entry on your client machines will be something like this:
322 .Bd -literal -offset 4n
323 masterserver:/FreeBSD /FreeBSD nfs ro,bg 0 0
324 masterserver:/usr/obj /usr/obj nfs ro,bg 0 0
327 And, of course, you should configure the client for NFS client operations
330 In particular, this will turn on
332 which will improve client-side NFS
334 .Bd -literal -offset 4n
335 nfs_client_enable="YES"
338 Each client should create softlinks for
343 into the NFS-mounted environment.
344 If a particular client is running -CURRENT,
346 should be a softlink to
347 .Pa /FreeBSD/FreeBSD-current/src .
348 If it is running -STABLE,
350 should be a softlink to
351 .Pa /FreeBSD/FreeBSD-4.x/src .
352 I do not usually create a
355 clients, that is used as a convenient shortcut when working on the source
356 code on the master server only and could create massive confusion (of the
357 human variety) on a client.
358 .Bd -literal -offset 4n
362 ln -s /FreeBSD/FreeBSD-current/ports ports
363 ln -s /FreeBSD/FreeBSD-XXX/src src
366 Do not forget to create the working directories so you can build ports, as
367 previously described.
368 If these are not good locations, make them softlinks to the correct location.
370 .Pa /usr/ports/distfiles
372 the master server and is therefore going to point to the same place
374 .Pa /usr/ports.distfiles )
376 .Bd -literal -offset 4n
377 mkdir /usr/ports.distfiles
378 mkdir /usr/ports.workdir
381 Here is how you build a -STABLE kernel (on your main development box).
382 If you want to create a custom kernel, copy
386 and then edit it before configuring and building.
387 The kernel configuration file lives in
388 .Pa /usr/src/sys/i386/conf/KERNELNAME .
389 .Bd -literal -offset 4n
391 make buildkernel KERNCONF=KERNELNAME
395 If you are familiar with the old config/cd/make method of building
396 a -STABLE kernel, note that the
398 method will put the build environment in
399 .Pa /usr/src/sys/i386/compile/KERNELNAME
403 Building a -CURRENT kernel
404 .Bd -literal -offset 4n
405 cd /usr/src2 (on the master server)
406 make buildkernel KERNCONF=KERNELNAME
408 .Sh INSTALLING KERNELS
409 Installing a -STABLE kernel (typically done on a client,
410 only do this on your main development server if you want to install a new
411 kernel for your main development server):
412 .Bd -literal -offset 4n
414 make installkernel KERNCONF=KERNELNAME
417 If you are using the older config/cd/make build mechanism for -STABLE, you
419 .Bd -literal -offset 4n
420 cd /usr/src/sys/i386/compile/KERNELNAME
424 Installing a -CURRENT kernel (typically done only on a client)
425 .Bd -literal -offset 4n
426 (remember /usr/src is pointing to the client's specific environment)
428 make installkernel KERNCONF=KERNELNAME
430 .Sh BUILDING THE WORLD
431 This environment is designed such that you do all builds on the master server,
432 and then install from each client.
433 You can do builds on a client only if
435 is local to that client.
436 Building the world is easy:
437 .Bd -literal -offset 4n
442 If you are on the master server you are running in a -STABLE environment, but
443 that does not prevent you from building the -CURRENT world.
446 into the appropriate source directory and you are set.
448 accidentally install it on your master server though!
449 .Bd -literal -offset 4n
453 .Sh INSTALLING THE WORLD
454 You can build on your main development server and install on clients.
455 The main development server must export
459 via read-only NFS to the clients.
464 is a softlink on the master server, it must also be the EXACT
465 SAME softlink on each client.
470 or a mount point on the master server,
471 then it must be (interchangeably) a directory in
476 absolute paths are expected to be the same when building the world as when
477 installing it, and you generally build it on your main development box
478 and install it from a client.
481 properly you will not be able to build on
482 machine and install on another.
483 .Bd -literal -offset 4n
485 (remember /usr/src is pointing to the client's specific environment)
491 If builds work on the master server but installs do not work from the
492 clients, for example you try to install and the client complains that
493 the install tried to write into the read-only
498 file on the client does not match the one on the
499 master server closely enough and the install is trying to install something
501 .Sh DOING DEVELOPMENT ON A CLIENT (NOT JUST INSTALLING)
502 Developers often want to run buildkernel's or buildworld's on client
503 boxes simply to life-test the box.
504 You do this in the same manner that you buildkernel and buildworld on your
506 All you have to do is make sure that
508 is pointing to local storage.
509 If you followed my advise and made
511 its own partition on the master
513 then it is typically going to be an NFS mount on the client.
516 will leave you with a
521 which is typically local to the client.
522 You can then do builds to your heart's content!
523 .Sh MAINTAINING A LOCAL BRANCH
524 I have described how to maintain two versions of the source tree, a stable
526 .Pa /FreeBSD/FreeBSD-4.x
527 and a current version in
528 .Pa /FreeBSD/FreeBSD-current .
529 There is absolutely nothing preventing you
530 from breaking out other versions of the source tree
535 partition also contains
538 and various flavors of
540 You may not necessarily be able to build
543 your master server, but being able
544 to collect and manage source distributions from a central server is a very
545 useful thing to be able to do and you can certainly export to machines
546 which can build those other operating systems.
548 Many developers choose to maintain a local branch of
550 to test patches or build a custom distribution.
551 This can be done with CVS or another source code management system
552 (SubVersion, Perforce, BitKeeper) with its own repository.
555 tree is based on CVS, the former is convenient.
557 First, you need to modify your
559 environment to avoid it modifying
560 the local changes you have committed to the repository.
561 It is important to remove the
570 For more information, see
577 examines a custom environmental variable,
578 .Ev CVS_LOCAL_BRANCH_NUM ,
579 which specifies an integer to use when doing a
581 .Cm tag Ns / Ns Cm rtag .
582 Set this number to something high (say 1000) to avoid colliding
583 with potential future branches of the main repository.
585 branching a file with version 1.4 produces 1.4.1000.
586 Future commits to this branch will produce revisions 1.4.1000.1,
589 To fork your local branch, do:
590 .Bd -literal -offset 4n
591 cvs rtag -r RELENG_4 -b LOCAL_RELENG_4 src
594 After this, you can check out a copy from your local repository using the
595 new tag and begin making changes and committing them.
596 For more information on using CVS, see
602 utility may blow away changes made on a local branch in
604 This has been reported to occur when the master CVS repository is
605 directly manipulated or an RCS file is changed.
608 notices that the client and server have entirely
609 different RCS files, so it does a full replace instead of trying to
611 Ideally this situation should never arise, but in the real world it
612 happens all the time.
614 While this is the only scenario where the problem should crop up,
615 there have been some suspicious-sounding reports of
616 .Ev CVS_LOCAL_BRANCH_NUM
617 lossage that cannot be explained by this alone.
618 Bottom line is, if you value your local branch then you
619 should back it up before every update.
621 The advantage of using
623 to maintain an updated copy of the CVS
624 repository instead of using it to maintain source trees directly is that you
625 can then pick and choose when you bring your source tree (or pieces of your
626 source tree) up to date.
629 job to maintain an updated CVS repository, you can update
630 your source tree at any time without any network cost as follows:
631 .Bd -literal -offset 4n
632 (on the main development server)
634 cvs -d /home/ncvs update
636 cvs -d /home/ncvs update
638 cvs -d /home/ncvs update
641 It is that simple, and since you are exporting the whole lot to your
642 clients, your clients have immediate visibility into the updated
644 This is a good time to also remind you that most of the
646 operations you do will be done as
648 and that certain options are
649 required for CVS to operate properly on the
654 is necessary when running
656 These options are typically placed in your
658 (as already described)
659 so you do not have to re-specify them every time you run a
662 Maintaining the CVS repository also gives you far more flexibility
663 in regards to breaking out multiple versions of the source tree.
664 It is a good idea to give your
666 partition a lot of space (I recommend
667 8-12GB) precisely for that reason.
668 If you can make it 15GB I would do it.
675 This is because I generally want the source to not change out from under me
676 when I am developing code.
677 Instead I manually update the source every so often...\& when I feel it is
679 My recommendation is to only keep the CVS repository synchronized via
693 manual page was originally written by
694 .An Matthew Dillon Aq dillon@FreeBSD.org