Sync em(4) manpage with the one in Intel em 6.2.9
[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 2003/05/23 07:48:35 brueffer Exp $
6 .\" $DragonFly: src/share/man/man7/development.7,v 1.7 2006/10/24 17:09:45 swildner Exp $
7 .\"
8 .Dd December 21, 2002
10 .Os
11 .Sh NAME
12 .Nm development
13 .Nd introduction to development with the FreeBSD 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
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.
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 /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
114 cd /FreeBSD/FreeBSD-4.x
115 cvs -d /home/ncvs checkout -rRELENG_4 src
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
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
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
173 cd /usr
174 rm -rf ports
175 ln -s /FreeBSD/FreeBSD-current/ports ports
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)
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.
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
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
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
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/config/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
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
307 This environment is designed such that you do all builds on the master server,
308 and then install from each client.
309 You can do builds on a client only if /usr/obj is local to that client.
310 Building the world is easy:
311 .Bd -literal -offset 4n
312 cd /usr/src
313 make buildworld
314 .Ed
315 .Pp
316 If you are on the master server you are running in a -STABLE environment, but
317 that does not prevent you from building the -CURRENT world.
318 Just cd into the appropriate source directory and you are set.
319 Do not
320 accidentally install it on your master server though!
321 .Bd -literal -offset 4n
322 cd /usr/src2
323 make buildworld
324 .Ed
326 You can build on your main development server and install on clients.
327 The main development server must export /FreeBSD and /usr/obj via
328 read-only NFS to the clients.
329 .Pp
330 .Em NOTE!!!
331 If /usr/obj is a softlink on the master server, it must also be the EXACT
332 SAME softlink on each client.
333 If /usr/obj is a directory in /usr or a mount point on the master server,
334 then it must be (interchangeably) a directory in /usr or a mount point on
335 each client.
336 This is because the
337 absolute paths are expected to be the same when building the world as when
338 installing it, and you generally build it on your main development box
339 and install it from a client.
340 If you do not setup /usr/obj properly you will not be able to build on
341 machine and install on another.
342 .Bd -literal -offset 4n
344 (remember /usr/src is pointing to the client's specific environment)
345 cd /usr/src
346 make installworld
347 .Ed
348 .Pp
349 .Sy WARNING!
350 If builds work on the master server but installs do not work from the
351 clients, for example you try to install and the client complains that
352 the install tried to write into the read-only /usr/obj, then it is likely
353 that the /etc/make.conf file on the client does not match the one on the
354 master server closely enough and the install is trying to install something
355 that was not built.
357 Developers often want to run buildkernel's or buildworld's on client
358 boxes simply to life-test the box.
359 You do this in the same manner that you buildkernel and buildworld on your
360 master server.
361 All you have to do is make sure that /usr/obj is pointing to local storage.
362 If you followed my advise and made /usr/obj its own partition on the master
363 server,
364 then it is typically going to be an NFS mount on the client.
365 Simply unmounting /usr/obj will leave you with a /usr/obj that is a
366 subdirectory in /usr which is typically local to the client.
367 You can then do builds to your heart's content!
369 I have described how to maintain two versions of the source tree, a stable
370 version in /FreeBSD/FreeBSD-4.x and a current version
371 in /FreeBSD/FreeBSD-current.
372 There is absolutely nothing preventing you
373 from breaking out other versions of the source tree
374 into /FreeBSD/XXX.
375 In fact, my /FreeBSD partition also contains
376 .Ox ,
377 .Nx ,
378 and various flavors of Linux.
379 You may not necessarily be able to build non-FreeBSD operating systems on
380 your master server, but being able
381 to collect and manage source distributions from a central server is a very
382 useful thing to be able to do and you can certainly export to machines
383 which can build those other operating systems.
384 .Pp
385 Many developers choose to maintain a local branch of
386 .Fx
387 to test patches or build a custom distribution.
388 This can be done with CVS or another source code management system
389 (SubVersion, Perforce, BitKeeper) with its own repository.
390 Since the main
391 .Fx
392 tree is based on CVS, the former is convenient.
393 .Pp
394 First, you need to modify your cvsup environment to avoid it modifying
395 the local changes you have committed to the repository.
396 It is important to remove the "delete" keyword from your supfile and to
397 add the CVSROOT subdirectory to your refuse file.
398 For more information, see
399 .Xr cvsup 1 .
400 .Pp
401 The
402 .Fx
403 version of CVS examines a custom environmental variable,
404 CVS_LOCAL_BRANCH_NUM, which specifies an integer to use when doing a cvs
405 tag/rtag.
406 Set this number to something high (say 1000) to avoid colliding
407 with potential future branches of the main repository.
408 For example,
409 branching a file with version 1.4 produces 1.4.1000.
410 Future commits to this branch will produce revisions 1.4.1000.1,
411 1.4.1000.2, etc.
412 .Pp
413 To fork your local branch, do:
414 .Bd -literal -offset 4n
415 cvs rtag -r RELENG_4 -b LOCAL_RELENG_4 src
416 .Ed
417 .Pp
418 After this, you can check out a copy from your local repository using the
419 new tag and begin making changes and committing them.
420 For more information on using cvs, see
421 .Xr cvs 1 .
422 .Pp
423 .Sy WARNING!
424 The cvsup utility may blow away changes made on a local branch in
425 some situations.
426 This has been reported to occur when the master CVS repository is
427 directly manipulated or an RCS file is changed.
428 At this point, cvsup notices that the client and server have entirely
429 different RCS files, so it does a full replace instead of trying to
430 send just deltas.
431 Ideally this situation should never arise, but in the real world it
432 happens all the time.
433 .Pp
434 While this is the only scenario where the problem should crop up,
435 there have been some suspicious-sounding reports of
436 CVS_LOCAL_BRANCH_NUM lossage that can't be explained by this alone.
437 Bottom line is, if you value your local branch then you
438 should back it up before every update.
440 The advantage of using cvsup to maintain an updated copy of the CVS
441 repository instead of using it to maintain source trees directly is that you
442 can then pick and choose when you bring your source tree (or pieces of your
443 source tree) up to date.
444 By using a cron job to maintain an updated CVS repository, you can update
445 your source tree at any time without any network cost as follows:
446 .Bd -literal -offset 4n
447 (on the main development server)
448 cd /usr/src
449 cvs -d /home/ncvs update
450 cd /usr/src2
451 cvs -d /home/ncvs update
452 cd /usr/ports
453 cvs -d /home/ncvs update
454 .Ed
455 .Pp
456 It is that simple, and since you are exporting the whole lot to your
457 clients, your clients have immediately visibility into the updated
458 source.
459 This is a good time to also remind you that most of the cvs operations
460 you do will be done as root, and that certain options are
461 required for CVS to operate properly on the
462 .Fx
463 repository.
464 For example,
465 .Fl Pd
466 is necessary when running "cvs update".
467 These options are typically placed in your ~/.cvsrc (as already described)
468 so you do not have to respecify them every time you run a CVS command.
469 Maintaining the CVS repository also gives you far more flexibility
470 in regards to breaking out multiple versions of the source tree.
471 It is a good idea to give your /FreeBSD partition a lot of space (I recommend
472 8-12GB) precisely for that reason.
473 If you can make it 15GB I would do it.
474 .Pp
475 I generally do not cvs update via a cron job.
476 This is because I generally want the source to not change out from under me
477 when I am developing code.
478 Instead I manually update the source every so often...\& when I feel it is
479 a good time.
480 My recommendation is to only keep the cvs repository synchronized via cron.
481 .Sh SEE ALSO
482 .Xr crontab 1 ,
483 .Xr crontab 5 ,
484 .Xr build 7 ,
485 .Xr firewall 7 ,
486 .Xr release 7 ,
487 .Xr tuning 7 ,
488 .Xr diskless 8
490 The
491 .Nm
492 manual page was originally written by
493 .An Matthew Dillon Aq
494 and first appeared
495 in
496 .Fx 5.0 ,
497 December 2002.