Merge from vendor branch READLINE:
[dragonfly.git] / share / man / man7 / development.7
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 FreeBSD source tree.
4 .\"
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.5 2004/07/25 16:17:31 hmp Exp $
7 .\"
8 .Dd December 21, 2002
9 .Dt DEVELOPMENT 7
10 .Os
11 .Sh NAME
12 .Nm development
13 .Nd introduction to development with the FreeBSD codebase
14 .Sh DESCRIPTION
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
18 .Fx
19 codebase as well as how to maintaining a master build which can
20 then be exported to other machines in your network.
21 This manual page
22 is targeted to system operators, programmers, and developers.
23 .Pp
24 Please note that what is being described here is based on a complete
25 FreeBSD environment, not just the FreeBSD kernel.
26 The methods described
27 here are as applicable to production installations as it is to development
28 environments.
29 You need a good 12-17GB of disk space on one machine to make this work
30 conveniently.
31 .Sh SETTING UP THE ENVIRONMENT ON THE MASTER SERVER
32 Your master server should always run a stable, production version of the
33 .Fx
34 operating system.
35 This does not prevent you from doing -CURRENT
36 builds or development.
37 The last thing you want to do is to run an
38 unstable environment on your master server which could lead to a situation
39 where you lose the environment and/or cannot recover from a mistake.
40 .Pp
41 Create a huge partition called /FreeBSD.
42 8-12GB is recommended.
43 This partition will contain nearly all the development environment,
44 including the CVS tree, broken-out source, and possibly even object files.
45 You are going to export this partition to your other machines via a
46 READ-ONLY NFS export so do not mix it with other more security-sensitive
47 partitions.
48 .Pp
49 You have to make a choice in regards to
50 .Pa /usr/obj .
51 You can put
52 .Pa /usr/obj
53 in
54 .Pa /FreeBSD
55 or you can make
56 .Pa /usr/obj
57 its own partition.
58 I recommend making it a separate partition for several reasons.
59 First,
60 as a safety measure since this partition is written to a great deal.
61 Second, because you typically do not have to back it up.
62 Third, because it makes it far easier to mix and match the development
63 environments which are described later in this document.
64 I recommend a
65 .Pa /usr/obj
66 partition of at least 5GB.
67 .Pp
68 On the master server, use cvsup to automatically pull down and maintain
69 the
70 .Fx
71 CVS archive once a day.
72 The first pull will take a long time,
73 it is several gigabytes, but once you have it the daily syncs will be quite
74 small.
75 .Bd -literal -offset 4n
76 mkdir /FreeBSD/FreeBSD-CVS
77 rm -rf /home/ncvs
78 ln -s /FreeBSD/FreeBSD-CVS /home/ncvs
79 .Ed
80 .Pp
81 The cron job should look something like this (please randomize the time of
82 day!).
83 Note that you can use the cvsup file example directly from
84 /usr/share/examples without modification by supplying appropriate arguments
85 to cvsup.
86 .Bd -literal -offset 4n
87 33 6 * * *      /usr/local/bin/cvsup -g -r 20 -L 2 -h cvsup.freebsd.org /usr/share/examples/cvsup/cvs-supfile
88 .Ed
89 .Pp
90 Run the cvsup manually the first time to pull down the archive.
91 It could take
92 all day depending on how fast your connection is!
93 You will run all cvsup and cvs operations as root and you need to set
94 up a ~/.cvsrc (/root/.cvsrc) file, as shown below, for proper cvs operation.
95 Using ~/.cvsrc to specify cvs defaults is an excellent way
96 to "file and forget", but you should never forget that you put them in there.
97 .Bd -literal -offset 4n
98 # cvs -q
99 diff -u
100 update -Pd
101 checkout -P
102 .Ed
103 .Pp
104 Now use cvs to checkout a -STABLE source tree and a -CURRENT source tree,
105 as well as ports and docs, to create your initial source environment.
106 Keeping the broken-out source and ports in /FreeBSD allows you to export
107 it to other machines via read-only NFS.
108 This also means you only need to edit/maintain files in one place and all
109 your clients automatically pick up the changes.
110 .Bd -literal -offset 4n
111 mkdir /FreeBSD/FreeBSD-4.x
112 mkdir /FreeBSD/FreeBSD-current
113
114 cd /FreeBSD/FreeBSD-4.x
115 cvs -d /home/ncvs checkout -rRELENG_4 src
116
117 cd /FreeBSD/FreeBSD-current
118 cvs -d /home/ncvs checkout src
119 cvs -d /home/ncvs checkout ports
120 cvs -d /home/ncvs checkout doc
121 .Ed
122 .Pp
123 Now create a softlink for /usr/src and /usr/src2.
124 On the main server I always point /usr/src at -STABLE and /usr/src2 at
125 -CURRENT.
126 On client machines I usually do not have a /usr/src2 and I make
127 /usr/src point at whatever version of FreeBSD the client box is intended to
128 run.
129 .Bd -literal -offset 4n
130 cd /usr
131 rm -rf src src2
132 ln -s /FreeBSD/FreeBSD-4.x/src src      (could be -CURRENT on a client)
133 ln -s /FreeBSD/FreeBSD-current/src src2 (MASTER SERVER ONLY)
134 .Ed
135 .Pp
136 Now you have to make a choice for /usr/obj.
137 Well, hopefully you made it already and chose the partition method.
138 If you
139 chose poorly you probably intend to put it in /FreeBSD and, if so, this is
140 what you want to do:
141 .Bd -literal -offset 4n
142 (ONLY IF YOU MADE A POOR CHOICE AND PUT /usr/obj in /FreeBSD!)
143 mkdir /FreeBSD/obj
144 cd /usr
145 rm -rf obj
146 ln -s /FreeBSD/obj obj
147 .Ed
148 .Pp
149 Alternatively you may chose simply to leave /usr/obj in /usr.
150 If your
151 /usr is large enough this will work, but I do not recommend it for
152 safety reasons (/usr/obj is constantly being modified, /usr is not).
153 .Pp
154 Note that exporting /usr/obj via read-only NFS to your other boxes will
155 allow you to build on your main server and install from your other boxes.
156 If you also want to do builds on some or all of the clients you can simply
157 have /usr/obj be a local directory on those clients.
158 You should never export /usr/obj read-write, it will lead to all sorts of
159 problems and issues down the line and presents a security problem as well.
160 It is far easier to do builds on the master server and then only do installs
161 on the clients.
162 .Pp
163 I usually maintain my ports tree via CVS.
164 It is sitting right there in the master CVS archive and I've even told you
165 to check it out (see above).
166 With some fancy softlinks you can make the ports tree available both on your
167 master server and on all of your other machines.
168 Note that the ports tree exists only on the HEAD cvs branch, so its always
169 -CURRENT even on a -STABLE box.
170 This is what you do:
171 .Bd -literal -offset 4n
172 (THESE COMMANDS ON THE MASTER SERVER AND ON ALL CLIENTS)
173 cd /usr
174 rm -rf ports
175 ln -s /FreeBSD/FreeBSD-current/ports ports
176
177 cd /usr/ports                           (this pushes into the softlink)
178 rm -rf distfiles                        (ON MASTER SERVER ONLY)
179 ln -s /usr/ports.distfiles distfiles    (ON MASTER SERVER ONLY)
180
181 mkdir /usr/ports.distfiles
182 mkdir /usr/ports.workdir
183 .Ed
184 .Pp
185 Since /usr/ports is softlinked into what will be read-only on all of your
186 clients, you have to tell the ports system to use a different working
187 directory to hold ports builds.
188 You want to add a line to your /etc/make.conf file on the master server
189 and on all your clients:
190 .Bd -literal -offset 4n
191 WRKDIRPREFIX=/usr/ports.workdir
192 .Ed
193 .Pp
194 You should try to make the directory you use for the ports working directory
195 as well as the directory used to hold distfiles consistent across all of your
196 machines.
197 If there isn't enough room in /usr/ports.distfiles and /usr/ports.workdir I
198 usually make those softlinks (since this is on /usr these are per-machine) to
199 where the distfiles and working space really are.
200 .Sh EXPORTING VIA NFS FROM THE MASTER SERVER
201 The master server needs to export /FreeBSD and /usr/obj via NFS so all the
202 rest of your machines can get at them.
203 I strongly recommend using a read-only export for both security and safety.
204 The environment I am describing in this manual page is designed primarily
205 around read-only NFS exports.
206 Your exports file on the master server should contain the following lines:
207 .Bd -literal -offset 4n
208 /FreeBSD -ro -alldirs -maproot=root: -network YOURLAN -mask YOURLANMASK
209 /usr/obj -ro -alldirs -maproot=root: -network YOURLAN -mask YOURLANMASK
210 .Ed
211 .Pp
212 Of course, NFS server operations must also be configured on that machine.
213 This is typically done via your /etc/rc.conf:
214 .Bd -literal -offset 4n
215 nfs_server_enable="YES"
216 nfs_server_flags="-u -t -n 4"
217 .Ed
218 .Sh THE CLIENT ENVIRONMENT
219 All of your client machines can import the development/build environment
220 directory simply by NFS mounting /FreeBSD and /usr/obj from the master
221 server.
222 A typical /etc/fstab entry on your client machines will be something like this:
223 .Bd -literal -offset 4n
224 masterserver:/FreeBSD     /FreeBSD        nfs     ro,bg    0       0
225 masterserver:/usr/obj     /usr/obj        nfs     ro,bg    0       0
226 .Ed
227 .Pp
228 And, of course, you should configure the client for NFS client operations
229 via /etc/rc.conf.
230 In particular, this will turn on nfsiod which will improve client-side NFS
231 performance:
232 .Bd -literal -offset 4n
233 nfs_client_enable="YES"
234 .Ed
235 .Pp
236 Each client should create softlinks for /usr/ports and /usr/src that point
237 into the NFS-mounted environment.
238 If a particular client is running -CURRENT, /usr/src
239 should be a softlink to /FreeBSD/FreeBSD-current/src.
240 If it is running -STABLE, /usr/src should be a softlink to
241 /FreeBSD/FreeBSD-4.x/src.
242 I do not usually create a /usr/src2 softlink on
243 clients, that is used as a convenient shortcut when working on the source
244 code on the master server only and could create massive confusion (of the
245 human variety) on a client.
246 .Bd -literal -offset 4n
247 (ON EACH CLIENT)
248 cd /usr
249 rm -rf ports src
250 ln -s /FreeBSD/FreeBSD-current/ports ports
251 ln -s /FreeBSD/FreeBSD-XXX/src src
252 .Ed
253 .Pp
254 Don't forget to create the working directories so you can build ports, as
255 previously described.
256 If these are not good locations, make them softlinks to the correct location.
257 Remember that /usr/ports/distfiles is exported by
258 the master server and is therefore going to point to the same place
259 (typically /usr/ports.distfiles) on every machine.
260 .Bd -literal -offset 4n
261 mkdir /usr/ports.distfiles
262 mkdir /usr/ports.workdir
263 .Ed
264 .Sh BUILDING KERNELS
265 Here is how you build a -STABLE kernel (on your main development box).
266 If you want to create a custom kernel, cp GENERIC to YOURKERNEL and then
267 edit it before configuring and building.
268 The kernel configuration file lives in /usr/src/sys/i386/conf/KERNELNAME.
269 .Bd -literal -offset 4n
270 cd /usr/src
271 make buildkernel KERNCONF=KERNELNAME
272 .Ed
273 .Pp
274 .Sy WARNING!
275 If you are familiar with the old config/cd/make method of building
276 a -STABLE kernel, note that the config method will put the build
277 environment in /usr/src/sys/compile/KERNELNAME instead of in /usr/obj.
278 .Pp
279 Building a -CURRENT kernel
280 .Bd -literal -offset 4n
281 cd /usr/src2            (on the master server)
282 make buildkernel KERNCONF=KERNELNAME
283 .Ed
284 .Sh INSTALLING KERNELS
285 Installing a -STABLE kernel (typically done on a client.
286 Only do this on your main development server if you want to install a new
287 kernel for your main development server):
288 .Bd -literal -offset 4n
289 cd /usr/src
290 make installkernel KERNCONF=KERNELNAME
291 .Ed
292 .Pp
293 If you are using the older config/cd/make build mechanism for stable, you
294 would install using:
295 .Bd -literal -offset 4n
296 cd /usr/src/sys/compile/KERNELNAME
297 make install
298 .Ed
299 .Pp
300 Installing a -CURRENT kernel (typically done only on a client)
301 .Bd -literal -offset 4n
302 (remember /usr/src is pointing to the client's specific environment)
303 cd /usr/src
304 make installkernel KERNCONF=KERNELNAME
305 .Ed
306 .Pp
307 .Sh BUILDING THE WORLD
308 This environment is designed such that you do all builds on the master server,
309 and then install from each client.
310 You can do builds on a client only if /usr/obj is local to that client.
311 Building the world is easy:
312 .Bd -literal -offset 4n
313 cd /usr/src
314 make buildworld
315 .Ed
316 .Pp
317 If you are on the master server you are running in a -STABLE environment, but
318 that does not prevent you from building the -CURRENT world.
319 Just cd into the appropriate source directory and you are set.
320 Do not
321 accidentally install it on your master server though!
322 .Bd -literal -offset 4n
323 cd /usr/src2
324 make buildworld
325 .Ed
326 .Sh INSTALLING THE WORLD
327 You can build on your main development server and install on clients.
328 The main development server must export /FreeBSD and /usr/obj via
329 read-only NFS to the clients.
330 .Pp
331 .Em NOTE!!!
332 If /usr/obj is a softlink on the master server, it must also be the EXACT
333 SAME softlink on each client.
334 If /usr/obj is a directory in /usr or a mount point on the master server,
335 then it must be (interchangeably) a directory in /usr or a mount point on
336 each client.
337 This is because the
338 absolute paths are expected to be the same when building the world as when
339 installing it, and you generally build it on your main development box
340 and install it from a client.
341 If you do not setup /usr/obj properly you will not be able to build on
342 machine and install on another.
343 .Bd -literal -offset 4n
344 (ON THE CLIENT)
345 (remember /usr/src is pointing to the client's specific environment)
346 cd /usr/src
347 make installworld
348 .Ed
349 .Pp
350 .Sy WARNING!
351 If builds work on the master server but installs do not work from the
352 clients, for example you try to install and the client complains that
353 the install tried to write into the read-only /usr/obj, then it is likely
354 that the /etc/make.conf file on the client does not match the one on the
355 master server closely enough and the install is trying to install something
356 that was not built.
357 .Sh DOING DEVELOPMENT ON A CLIENT (NOT JUST INSTALLING)
358 Developers often want to run buildkernel's or buildworld's on client
359 boxes simply to life-test the box.
360 You do this in the same manner that you buildkernel and buildworld on your
361 master server.
362 All you have to do is make sure that /usr/obj is pointing to local storage.
363 If you followed my advise and made /usr/obj its own partition on the master
364 server,
365 then it is typically going to be an NFS mount on the client.
366 Simply unmounting /usr/obj will leave you with a /usr/obj that is a
367 subdirectory in /usr which is typically local to the client.
368 You can then do builds to your heart's content!
369 .Sh MAINTAINING A LOCAL BRANCH
370 I have described how to maintain two versions of the source tree, a stable
371 version in /FreeBSD/FreeBSD-4.x and a current version
372 in /FreeBSD/FreeBSD-current.
373 There is absolutely nothing preventing you
374 from breaking out other versions of the source tree
375 into /FreeBSD/XXX.
376 In fact, my /FreeBSD partition also contains
377 .Ox ,
378 .Nx ,
379 and various flavors of Linux.
380 You may not necessarily be able to build non-FreeBSD operating systems on
381 your master server, but being able
382 to collect and manage source distributions from a central server is a very
383 useful thing to be able to do and you can certainly export to machines
384 which can build those other operating systems.
385 .Pp
386 Many developers choose to maintain a local branch of
387 .Fx
388 to test patches or build a custom distribution.
389 This can be done with CVS or another source code management system
390 (SubVersion, Perforce, BitKeeper) with its own repository.
391 Since the main
392 .Fx
393 tree is based on CVS, the former is convenient.
394 .Pp
395 First, you need to modify your cvsup environment to avoid it modifying
396 the local changes you have committed to the repository.
397 It is important to remove the "delete" keyword from your supfile and to
398 add the CVSROOT subdirectory to your refuse file.
399 For more information, see
400 .Xr cvsup 1 .
401 .Pp
402 The
403 .Fx
404 version of CVS examines a custom environmental variable,
405 CVS_LOCAL_BRANCH_NUM, which specifies an integer to use when doing a cvs
406 tag/rtag.
407 Set this number to something high (say 1000) to avoid colliding
408 with potential future branches of the main repository.
409 For example,
410 branching a file with version 1.4 produces 1.4.1000.
411 Future commits to this branch will produce revisions 1.4.1000.1,
412 1.4.1000.2, etc.
413 .Pp
414 To fork your local branch, do:
415 .Bd -literal -offset 4n
416 cvs rtag -r RELENG_4 -b LOCAL_RELENG_4 src
417 .Ed
418 .Pp
419 After this, you can check out a copy from your local repository using the
420 new tag and begin making changes and committing them.
421 For more information on using cvs, see
422 .Xr cvs 1 .
423 .Pp
424 .Sy WARNING!
425 The cvsup utility may blow away changes made on a local branch in
426 some situations.
427 This has been reported to occur when the master CVS repository is
428 directly manipulated or an RCS file is changed.
429 At this point, cvsup notices that the client and server have entirely
430 different RCS files, so it does a full replace instead of trying to
431 send just deltas.
432 Ideally this situation should never arise, but in the real world it
433 happens all the time.
434 .Pp
435 While this is the only scenario where the problem should crop up,
436 there have been some suspicious-sounding reports of
437 CVS_LOCAL_BRANCH_NUM lossage that can't be explained by this alone.
438 Bottom line is, if you value your local branch then you
439 should back it up before every update.
440 .Sh UPDATING VIA CVS
441 The advantage of using cvsup to maintain an updated copy of the CVS
442 repository instead of using it to maintain source trees directly is that you
443 can then pick and choose when you bring your source tree (or pieces of your
444 source tree) up to date.
445 By using a cron job to maintain an updated CVS repository, you can update
446 your source tree at any time without any network cost as follows:
447 .Bd -literal -offset 4n
448 (on the main development server)
449 cd /usr/src
450 cvs -d /home/ncvs update
451 cd /usr/src2
452 cvs -d /home/ncvs update
453 cd /usr/ports
454 cvs -d /home/ncvs update
455 .Ed
456 .Pp
457 It is that simple, and since you are exporting the whole lot to your
458 clients, your clients have immediately visibility into the updated
459 source.
460 This is a good time to also remind you that most of the cvs operations
461 you do will be done as root, and that certain options are
462 required for CVS to operate properly on the
463 .Fx
464 repository.
465 For example,
466 .Fl Pd
467 is necessary when running "cvs update".
468 These options are typically placed in your ~/.cvsrc (as already described)
469 so you do not have to respecify them every time you run a CVS command.
470 Maintaining the CVS repository also gives you far more flexibility
471 in regards to breaking out multiple versions of the source tree.
472 It is a good idea to give your /FreeBSD partition a lot of space (I recommend
473 8-12GB) precisely for that reason.
474 If you can make it 15GB I would do it.
475 .Pp
476 I generally do not cvs update via a cron job.
477 This is because I generally want the source to not change out from under me
478 when I am developing code.
479 Instead I manually update the source every so often...\& when I feel it is
480 a good time.
481 My recommendation is to only keep the cvs repository synchronized via cron.
482 .Sh SEE ALSO
483 .Xr crontab 1 ,
484 .Xr crontab 5 ,
485 .Xr build 7 ,
486 .Xr firewall 7 ,
487 .Xr release 7 ,
488 .Xr tuning 7 ,
489 .Xr diskless 8
490 .Sh HISTORY
491 The
492 .Nm
493 manual page was originally written by
494 .An Matthew Dillon Aq dillon@FreeBSD.org
495 and first appeared
496 in
497 .Fx 5.0 ,
498 December 2002.