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.8 2007/12/15 12:20:06 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 /DragonFly.
45 8-12GB is recommended.
46 This partition will contain nearly all the development environment,
47 including the CVS tree, broken-out source, and possibly even object files.
48 You are going to export this partition to your other machines via a
50 NFS export so do not mix it with other more security-sensitive
53 You have to make a choice in regards to
62 I recommend making it a separate partition for several reasons.
64 as a safety measure since this partition is written to a great deal.
65 Second, because you typically do not have to back it up.
66 Third, because it makes it far easier to mix and match the development
67 environments which are described later in this document.
70 partition of at least 5GB.
72 On the master server, use cvsup to automatically pull down and maintain
75 CVS archive once a day.
76 The first pull will take a long time,
77 it is several gigabytes, but once you have it the daily syncs will be quite
79 .Bd -literal -offset 4n
80 mkdir /DragonFly/DragonFly-CVS
82 ln -s /DragonFly/DragonFly-CVS /home/dcvs
85 The cron job should look something like this (please randomize the time of
87 Note that you can use the cvsup file example directly from
88 /usr/share/examples without modification by supplying appropriate arguments
89 to cvsup. Please use a cvsup mirror, see the
92 .Bd -literal -offset 4n
93 33 6 * * * /usr/local/bin/cvsup -gr 20 -L 2 -h cvsup.dragonflybsd.org \\
94 /usr/share/examples/cvsup/DragonFly-cvs-supfile
97 Run the cvsup manually the first time to pull down the archive.
99 all day depending on how fast your connection is!
100 You will run all cvsup and cvs operations as root and you need to set
101 up a ~/.cvsrc (/root/.cvsrc) file, as shown below, for proper cvs operation.
102 Using ~/.cvsrc to specify cvs defaults is an excellent way
103 to "file and forget", but you should never forget that you put them in there.
104 .Bd -literal -offset 4n
111 Now use cvs to checkout a -RELEASE source tree and a -DEVELOPMENT source tree,
112 as well as docs, to create your initial source environment.
113 Keeping the broken-out source in /DragonFly allows you to export
114 it to other machines via read-only NFS.
115 This also means you only need to edit/maintain files in one place and all
116 your clients automatically pick up the changes.
117 .Bd -literal -offset 4n
118 mkdir /DragonFly/DragonFly-RELEASE
119 mkdir /DragonFly/DragonFly-DEVELOPMENT
121 cd /DragonFly/DragonFly-RELEASE
122 cvs -d /home/dcvs checkout -r DragonFly_RELEASE_1_10_Slip src
124 cd /DragonFly/DragonFly-DEVELOPMENT
125 cvs -d /home/dcvs checkout src
126 cvs -d /home/dcvs checkout doc
129 Now create a softlink for /usr/src and /usr/src2.
130 On the main server I always point /usr/src at -RELEASE and /usr/src2 at
132 On client machines I usually do not have a /usr/src2 and I make
133 /usr/src point at whatever version of
135 the client box is intended to
137 .Bd -literal -offset 4n
140 ln -s /DragonFly/DragonFly-RELEASE/src src (could be -DEVELOPMENT on a client)
141 ln -s /DragonFly/DragonFly-DEVELOPMENT/src src2 (MASTER SERVER ONLY)
144 Now you have to make a choice for /usr/obj.
145 Well, hopefully you made it already and chose the partition method.
147 chose poorly you probably intend to put it in /DragonFly and, if so, this is
149 .Bd -literal -offset 4n
150 (ONLY IF YOU MADE A POOR CHOICE AND PUT /usr/obj in /DragonFly!)
154 ln -s /DragonFly/obj obj
157 Alternatively you may chose simply to leave /usr/obj in /usr.
159 /usr is large enough this will work, but I do not recommend it for
160 safety reasons (/usr/obj is constantly being modified, /usr is not).
162 Note that exporting /usr/obj via read-only NFS to your other boxes will
163 allow you to build on your main server and install from your other boxes.
164 If you also want to do builds on some or all of the clients you can simply
165 have /usr/obj be a local directory on those clients.
166 You should never export /usr/obj read-write, it will lead to all sorts of
167 problems and issues down the line and presents a security problem as well.
168 It is far easier to do builds on the master server and then only do installs
171 .Sh EXPORTING VIA NFS FROM THE MASTER SERVER
172 The master server needs to export /DragonFly and /usr/obj via NFS so all the
173 rest of your machines can get at them.
174 I strongly recommend using a read-only export for both security and safety.
175 The environment I am describing in this manual page is designed primarily
176 around read-only NFS exports.
177 Your /etc/exports file on the master server should contain the following lines:
178 .Bd -literal -offset 4n
179 /DragonFly -ro -alldirs -maproot=root: -network YOURLAN -mask YOURLANMASK
180 /usr/obj -ro -alldirs -maproot=root: -network YOURLAN -mask YOURLANMASK
183 Of course, NFS server operations must also be configured on that machine.
184 This is typically done via your /etc/rc.conf:
185 .Bd -literal -offset 4n
186 nfs_server_enable="YES"
188 .Sh THE CLIENT ENVIRONMENT
189 All of your client machines can import the development/build environment
190 directory simply by NFS mounting /DragonFly and /usr/obj from the master
192 A typical /etc/fstab entry on your client machines will be something like this:
193 .Bd -literal -offset 4n
194 masterserver:/DragonFly /DragonFly nfs ro,bg 0 0
195 masterserver:/usr/obj /usr/obj nfs ro,bg 0 0
198 And, of course, you should configure the client for NFS client operations
200 In particular, this will turn on nfsiod which will improve client-side NFS
202 .Bd -literal -offset 4n
203 nfs_client_enable="YES"
206 Each client should create softlink for /usr/src that point
207 into the NFS-mounted environment.
208 If a particular client is running -DEVELOPMENT, /usr/src
209 should be a softlink to /DragonFly/DragonFly-DEVELOPMENT/src.
210 If it is running -RELEASE, /usr/src should be a softlink to
211 /DragonFly/DragonFly-RELEASE/src.
212 I do not usually create a /usr/src2 softlink on
213 clients, that is used as a convenient shortcut when working on the source
214 code on the master server only and could create massive confusion (of the
215 human variety) on a client.
216 .Bd -literal -offset 4n
219 ln -s /DragonFly/DragonFly-XXX/src src
223 Here is how you build a -RELEASE kernel (on your main development box).
224 If you want to create a custom kernel, cp GENERIC to YOURKERNEL and then
225 edit it before configuring and building.
226 The kernel configuration file lives in /usr/src/sys/config/KERNELNAME.
227 .Bd -literal -offset 4n
229 make buildkernel KERNCONF=KERNELNAME
232 Building a -DEVELOPMENT kernel
233 .Bd -literal -offset 4n
234 cd /usr/src2 (on the master server)
235 make buildkernel KERNCONF=KERNELNAME
237 .Sh INSTALLING KERNELS
238 Installing a -RELEASE kernel (typically done on a client.
239 Only do this on your main development server if you want to install a new
240 kernel for your main development server):
241 .Bd -literal -offset 4n
243 make installkernel KERNCONF=KERNELNAME
246 Installing a -DEVELOPMENT kernel (typically done only on a client)
247 .Bd -literal -offset 4n
248 (remember /usr/src is pointing to the client's specific environment)
250 make installkernel KERNCONF=KERNELNAME
252 .Sh BUILDING THE WORLD
253 This environment is designed such that you do all builds on the master server,
254 and then install from each client.
255 You can do builds on a client only if /usr/obj is local to that client.
256 Building the world is easy:
257 .Bd -literal -offset 4n
262 If you are on the master server you are running in a -RELEASE environment, but
263 that does not prevent you from building the -DEVELOPMENT world.
264 Just cd into the appropriate source directory and you are set.
266 accidentally install it on your master server though!
267 .Bd -literal -offset 4n
271 .Sh INSTALLING THE WORLD
272 You can build on your main development server and install on clients.
273 The main development server must export /DragonFly and /usr/obj via
274 read-only NFS to the clients.
277 If /usr/obj is a softlink on the master server, it must also be the EXACT
278 SAME softlink on each client.
279 If /usr/obj is a directory in /usr or a mount point on the master server,
280 then it must be (interchangeably) a directory in /usr or a mount point on
283 absolute paths are expected to be the same when building the world as when
284 installing it, and you generally build it on your main development box
285 and install it from a client.
286 If you do not setup /usr/obj properly you will not be able to build on
287 machine and install on another.
288 .Bd -literal -offset 4n
290 (remember /usr/src is pointing to the client's specific environment)
296 If builds work on the master server but installs do not work from the
297 clients, for example you try to install and the client complains that
298 the install tried to write into the read-only /usr/obj, then it is likely
299 that the /etc/make.conf file on the client does not match the one on the
300 master server closely enough and the install is trying to install something
302 .Sh DOING DEVELOPMENT ON A CLIENT (NOT JUST INSTALLING)
303 Developers often want to run buildkernel's or buildworld's on client
304 boxes simply to life-test the box.
305 You do this in the same manner that you buildkernel and buildworld on your
307 All you have to do is make sure that /usr/obj is pointing to local storage.
308 If you followed my advise and made /usr/obj its own partition on the master
310 then it is typically going to be an NFS mount on the client.
311 Simply unmounting /usr/obj will leave you with a /usr/obj that is a
312 subdirectory in /usr which is typically local to the client.
313 You can then do builds to your heart's content!
314 .Sh MAINTAINING A LOCAL BRANCH
315 I have described how to maintain two versions of the source tree, a stable
316 version in /DragonFly/DragonFly-RELEASE and a current version
317 in /DragonFly/DragonFly-DEVELOPMENT.
318 There is absolutely nothing preventing you
319 from breaking out other versions of the source tree
321 In fact, my /DragonFly partition also contains
325 and various flavors of Linux.
326 You may not necessarily be able to build non-DragonFly operating systems on
327 your master server, but being able
328 to collect and manage source distributions from a central server is a very
329 useful thing to be able to do and you can certainly export to machines
330 which can build those other operating systems.
332 Many developers choose to maintain a local branch of
334 to test patches or build a custom distribution.
335 This can be done with CVS or another source code management system
336 (SubVersion, Perforce, BitKeeper) with its own repository.
339 tree is based on CVS, the former is convenient.
341 First, you need to modify your cvsup environment to avoid it modifying
342 the local changes you have committed to the repository.
343 It is important to remove the "delete" keyword from your supfile and to
344 add the CVSROOT subdirectory to your refuse file.
345 For more information, see
350 version of CVS examines a custom environmental variable,
351 CVS_LOCAL_BRANCH_NUM, which specifies an integer to use when doing a cvs
353 Set this number to something high (say 1000) to avoid colliding
354 with potential future branches of the main repository.
356 branching a file with version 1.4 produces 1.4.1000.
357 Future commits to this branch will produce revisions 1.4.1000.1,
360 To fork your local branch, do:
361 .Bd -literal -offset 4n
362 cvs rtag -r DragonFly_RELEASE_1_10_Slip -b LOCAL_DragonFly_RELEASE_1_10 src
365 After this, you can check out a copy from your local repository using the
366 new tag and begin making changes and committing them.
367 For more information on using cvs, see
371 The cvsup utility may blow away changes made on a local branch in
373 This has been reported to occur when the master CVS repository is
374 directly manipulated or an RCS file is changed.
375 At this point, cvsup notices that the client and server have entirely
376 different RCS files, so it does a full replace instead of trying to
378 Ideally this situation should never arise, but in the real world it
379 happens all the time.
381 While this is the only scenario where the problem should crop up,
382 there have been some suspicious-sounding reports of
383 CVS_LOCAL_BRANCH_NUM lossage that can't be explained by this alone.
384 Bottom line is, if you value your local branch then you
385 should back it up before every update.
387 The advantage of using cvsup to maintain an updated copy of the CVS
388 repository instead of using it to maintain source trees directly is that you
389 can then pick and choose when you bring your source tree (or pieces of your
390 source tree) up to date.
391 By using a cron job to maintain an updated CVS repository, you can update
392 your source tree at any time without any network cost as follows:
393 .Bd -literal -offset 4n
394 (on the main development server)
396 cvs -d /home/dcvs update
398 cvs -d /home/dcvs update
401 It is that simple, and since you are exporting the whole lot to your
402 clients, your clients have immediately visibility into the updated
404 This is a good time to also remind you that most of the cvs operations
405 you do will be done as root, and that certain options are
406 required for CVS to operate properly on the
411 is necessary when running "cvs update".
412 These options are typically placed in your ~/.cvsrc (as already described)
413 so you do not have to respecify them every time you run a CVS command.
414 Maintaining the CVS repository also gives you far more flexibility
415 in regards to breaking out multiple versions of the source tree.
416 It is a good idea to give your /DragonFly partition a lot of space (I recommend
417 8-12GB) precisely for that reason.
418 If you can make it 15GB I would do it.
420 I generally do not cvs update via a cron job.
421 This is because I generally want the source to not change out from under me
422 when I am developing code.
423 Instead I manually update the source every so often...\& when I feel it is
425 My recommendation is to only keep the cvs repository synchronized via cron.
441 manual page was originally written by
442 .An Matthew Dillon Aq dillon@FreeBSD.org