1 .\" Copyright (c) 1998 Matthew Dillon. Terms and conditions are those of
2 .\" the BSD Copyright as specified in the file "/usr/src/COPYRIGHT" in
3 .\" the DragonFly source tree.
5 .\" $FreeBSD: src/share/man/man7/development.7,v 1.4.2.2 2003/05/23 07:48:35 brueffer Exp $
6 .\" $DragonFly: src/share/man/man7/development.7,v 1.9 2007/12/15 16:49:43 thomas Exp $
13 .Nd introduction to development with the DragonFly codebase
15 This manual page describes how an ordinary sysop,
16 .Ux admin, or developer
17 can, without any special permission, obtain, maintain, and modify the
19 codebase as well as how to maintaining a master build which can
20 then be exported to other machines in your network.
22 is targeted to system operators, programmers, and developers.
24 Please note that what is being described here is based on a complete
26 environment, not just the
30 here are as applicable to production installations as it is to development
32 You need a good 12-17GB of disk space on one machine to make this work
34 .Sh SETTING UP THE ENVIRONMENT ON THE MASTER SERVER
35 Your master server should always run a stable, production version of the
38 This does not prevent you from doing -PREVIEW or -DEVELOPMENT
39 builds or development.
40 The last thing you want to do is to run an
41 unstable environment on your master server which could lead to a situation
42 where you lose the environment and/or cannot recover from a mistake.
44 Create a partition called
46 8-12GB is recommended.
47 This partition will contain nearly all the development environment,
48 including the CVS tree, broken-out source, and possibly even object files.
49 You are going to export this partition to your other machines via a
51 NFS export so do not mix it with other more security-sensitive
54 You have to make a choice in regards to
63 I recommend making it a separate partition for several reasons.
65 as a safety measure since this partition is written to a great deal.
66 Second, because you typically do not have to back it up.
67 Third, because it makes it far easier to mix and match the development
68 environments which are described later in this document.
71 partition of at least 5GB.
73 On the master server, use cvsup to automatically pull down and maintain
76 CVS archive once a day.
77 The first pull will take a long time,
78 it is several gigabytes, but once you have it the daily syncs will be quite
80 .Bd -literal -offset 4n
81 mkdir /DragonFly/DragonFly-CVS
83 ln -s /DragonFly/DragonFly-CVS /home/dcvs
86 The cron job should look something like this (please randomize the time of
88 Note that you can use the cvsup file example directly from
89 .Pa /usr/share/examples
90 without modification by supplying appropriate arguments
91 to cvsup. Please use a cvsup mirror, see the
94 .Bd -literal -offset 4n
95 33 6 * * * /usr/local/bin/cvsup -gr 20 -L 2 -h cvsup.dragonflybsd.org \\
96 /usr/share/examples/cvsup/DragonFly-cvs-supfile
99 Run the cvsup manually the first time to pull down the archive.
101 all day depending on how fast your connection is!
102 You will run all cvsup and cvs operations as root and you need to set
106 file, as shown below, for proper cvs operation.
109 to specify cvs defaults is an excellent way
110 to "file and forget", but you should never forget that you put them in there.
111 .Bd -literal -offset 4n
118 Now use cvs to checkout a -RELEASE source tree and a -DEVELOPMENT source tree,
119 as well as docs, to create your initial source environment.
120 Keeping the broken-out source in
123 it to other machines via read-only NFS.
124 This also means you only need to edit/maintain files in one place and all
125 your clients automatically pick up the changes.
126 .Bd -literal -offset 4n
127 mkdir /DragonFly/DragonFly-RELEASE
128 mkdir /DragonFly/DragonFly-DEVELOPMENT
130 cd /DragonFly/DragonFly-RELEASE
131 cvs -d /home/dcvs checkout -r DragonFly_RELEASE_1_10_Slip src
133 cd /DragonFly/DragonFly-DEVELOPMENT
134 cvs -d /home/dcvs checkout src
135 cvs -d /home/dcvs checkout doc
138 Now create a softlink for
142 On the main server I always point
148 On client machines I usually do not have a
152 point at whatever version of
154 the client box is intended to
156 .Bd -literal -offset 4n
159 ln -s /DragonFly/DragonFly-RELEASE/src src (could be -DEVELOPMENT on a client)
160 ln -s /DragonFly/DragonFly-DEVELOPMENT/src src2 (MASTER SERVER ONLY)
163 Now you have to make a choice for
165 Well, hopefully you made it already and chose the partition method.
167 chose poorly you probably intend to put it in
171 .Bd -literal -offset 4n
172 (ONLY IF YOU MADE A POOR CHOICE AND PUT /usr/obj in /DragonFly!)
176 ln -s /DragonFly/obj obj
179 Alternatively you may chose simply to leave
185 is large enough this will work, but I do not recommend it for
188 is constantly being modified,
194 via read-only NFS to your other boxes will
195 allow you to build on your main server and install from your other boxes.
196 If you also want to do builds on some or all of the clients you can simply
199 be a local directory on those clients.
200 You should never export
202 read-write, it will lead to all sorts of
203 problems and issues down the line and presents a security problem as well.
204 It is far easier to do builds on the master server and then only do installs
207 .Sh EXPORTING VIA NFS FROM THE MASTER SERVER
208 The master server needs to export
213 rest of your machines can get at them.
214 I strongly recommend using a read-only export for both security and safety.
215 The environment I am describing in this manual page is designed primarily
216 around read-only NFS exports.
219 file on the master server should contain the following lines:
220 .Bd -literal -offset 4n
221 /DragonFly -ro -alldirs -maproot=root: -network YOURLAN -mask YOURLANMASK
222 /usr/obj -ro -alldirs -maproot=root: -network YOURLAN -mask YOURLANMASK
225 Of course, NFS server operations must also be configured on that machine.
226 This is typically done via your
228 .Bd -literal -offset 4n
229 nfs_server_enable="YES"
231 .Sh THE CLIENT ENVIRONMENT
232 All of your client machines can import the development/build environment
233 directory simply by NFS mounting
241 entry on your client machines will be something like this:
242 .Bd -literal -offset 4n
243 masterserver:/DragonFly /DragonFly nfs ro,bg 0 0
244 masterserver:/usr/obj /usr/obj nfs ro,bg 0 0
247 And, of course, you should configure the client for NFS client operations
250 In particular, this will turn on nfsiod which will improve client-side NFS
252 .Bd -literal -offset 4n
253 nfs_client_enable="YES"
256 Each client should create softlink for
259 into the NFS-mounted environment.
260 If a particular client is running -DEVELOPMENT,
262 should be a softlink to
263 .Pa /DragonFly/DragonFly-DEVELOPMENT/src .
264 If it is running -RELEASE,
266 should be a softlink to
267 .Pa /DragonFly/DragonFly-RELEASE/src .
268 I do not usually create a
271 clients, that is used as a convenient shortcut when working on the source
272 code on the master server only and could create massive confusion (of the
273 human variety) on a client.
274 .Bd -literal -offset 4n
277 ln -s /DragonFly/DragonFly-XXX/src src
281 Here is how you build a -RELEASE kernel (on your main development box).
282 If you want to create a custom kernel, copy
287 edit it before configuring and building.
288 The kernel configuration file lives in
289 .Pa /sys/config/KERNELNAME .
290 .Bd -literal -offset 4n
292 make buildkernel KERNCONF=KERNELNAME
295 Building a -DEVELOPMENT kernel
296 .Bd -literal -offset 4n
297 cd /usr/src2 (on the master server)
298 make buildkernel KERNCONF=KERNELNAME
300 .Sh INSTALLING KERNELS
301 Installing a -RELEASE kernel (typically done on a client.
302 Only do this on your main development server if you want to install a new
303 kernel for your main development server):
304 .Bd -literal -offset 4n
306 make installkernel KERNCONF=KERNELNAME
309 Installing a -DEVELOPMENT kernel (typically done only on a client)
310 .Bd -literal -offset 4n
311 (remember /usr/src is pointing to the client's specific environment)
313 make installkernel KERNCONF=KERNELNAME
315 .Sh BUILDING THE WORLD
316 This environment is designed such that you do all builds on the master server,
317 and then install from each client.
318 You can do builds on a client only if
320 is local to that client.
321 Building the world is easy:
322 .Bd -literal -offset 4n
327 If you are on the master server you are running in a -RELEASE environment, but
328 that does not prevent you from building the -DEVELOPMENT world.
329 Just cd into the appropriate source directory and you are set.
331 accidentally install it on your master server though!
332 .Bd -literal -offset 4n
336 .Sh INSTALLING THE WORLD
337 You can build on your main development server and install on clients.
338 The main development server must export
343 read-only NFS to the clients.
348 is a softlink on the master server, it must also be the EXACT
349 SAME softlink on each client.
354 or a mount point on the master server,
355 then it must be (interchangeably) a directory in
360 absolute paths are expected to be the same when building the world as when
361 installing it, and you generally build it on your main development box
362 and install it from a client.
365 properly you will not be able to build on
366 machine and install on another.
367 .Bd -literal -offset 4n
371 is pointing to the client's specific environment)
377 If builds work on the master server but installs do not work from the
378 clients, for example you try to install and the client complains that
379 the install tried to write into the read-only
384 file on the client does not match the one on the
385 master server closely enough and the install is trying to install something
387 .Sh DOING DEVELOPMENT ON A CLIENT (NOT JUST INSTALLING)
388 Developers often want to run buildkernel's or buildworld's on client
389 boxes simply to life-test the box.
390 You do this in the same manner that you buildkernel and buildworld on your
392 All you have to do is make sure that
394 is pointing to local storage.
395 If you followed my advise and made
397 its own partition on the master
399 then it is typically going to be an NFS mount on the client.
402 will leave you with a
407 which is typically local to the client.
408 You can then do builds to your heart's content!
409 .Sh MAINTAINING A LOCAL BRANCH
410 I have described how to maintain two versions of the source tree, a stable
412 .Pa /DragonFly/DragonFly-RELEASE
413 and a current version
415 .Pa /DragonFly/DragonFly-DEVELOPMENT .
416 There is absolutely nothing preventing you
417 from breaking out other versions of the source tree
422 partition also contains
426 and various flavors of Linux.
427 You may not necessarily be able to build non-DragonFly operating systems on
428 your master server, but being able
429 to collect and manage source distributions from a central server is a very
430 useful thing to be able to do and you can certainly export to machines
431 which can build those other operating systems.
433 Many developers choose to maintain a local branch of
435 to test patches or build a custom distribution.
436 This can be done with CVS or another source code management system
437 (SubVersion, Perforce, BitKeeper) with its own repository.
440 tree is based on CVS, the former is convenient.
442 First, you need to modify your cvsup environment to avoid it modifying
443 the local changes you have committed to the repository.
444 It is important to remove the "delete" keyword from your supfile and to
445 add the CVSROOT subdirectory to your refuse file.
446 For more information, see
451 version of CVS examines a custom environmental variable,
452 CVS_LOCAL_BRANCH_NUM, which specifies an integer to use when doing a cvs
454 Set this number to something high (say 1000) to avoid colliding
455 with potential future branches of the main repository.
457 branching a file with version 1.4 produces 1.4.1000.
458 Future commits to this branch will produce revisions 1.4.1000.1,
461 To fork your local branch, do:
462 .Bd -literal -offset 4n
463 cvs rtag -r DragonFly_RELEASE_1_10_Slip -b LOCAL_DragonFly_RELEASE_1_10 src
466 After this, you can check out a copy from your local repository using the
467 new tag and begin making changes and committing them.
468 For more information on using cvs, see
472 The cvsup utility may blow away changes made on a local branch in
474 This has been reported to occur when the master CVS repository is
475 directly manipulated or an RCS file is changed.
476 At this point, cvsup notices that the client and server have entirely
477 different RCS files, so it does a full replace instead of trying to
479 Ideally this situation should never arise, but in the real world it
480 happens all the time.
482 While this is the only scenario where the problem should crop up,
483 there have been some suspicious-sounding reports of
484 CVS_LOCAL_BRANCH_NUM lossage that can't be explained by this alone.
485 Bottom line is, if you value your local branch then you
486 should back it up before every update.
488 The advantage of using cvsup to maintain an updated copy of the CVS
489 repository instead of using it to maintain source trees directly is that you
490 can then pick and choose when you bring your source tree (or pieces of your
491 source tree) up to date.
492 By using a cron job to maintain an updated CVS repository, you can update
493 your source tree at any time without any network cost as follows:
494 .Bd -literal -offset 4n
495 (on the main development server)
497 cvs -d /home/dcvs update
499 cvs -d /home/dcvs update
502 It is that simple, and since you are exporting the whole lot to your
503 clients, your clients have immediately visibility into the updated
505 This is a good time to also remind you that most of the cvs operations
506 you do will be done as root, and that certain options are
507 required for CVS to operate properly on the
512 is necessary when running "cvs update".
513 These options are typically placed in your
515 (as already described)
516 so you do not have to respecify them every time you run a CVS command.
517 Maintaining the CVS repository also gives you far more flexibility
518 in regards to breaking out multiple versions of the source tree.
519 It is a good idea to give your
521 partition a lot of space (I recommend
522 8-12GB) precisely for that reason.
523 If you can make it 15GB I would do it.
525 I generally do not cvs update via a cron job.
526 This is because I generally want the source to not change out from under me
527 when I am developing code.
528 Instead I manually update the source every so often...\& when I feel it is
530 My recommendation is to only keep the cvs repository synchronized via cron.
547 manual page was originally written by
548 .An Matthew Dillon Aq dillon@FreeBSD.org
projects / dragonfly.git / blob