share/man/man7/development.7

   1 .\" Copyright (C) 1998 Matthew Dillon. All rights reserved.
   2 .\"
   3 .\" Redistribution and use in source and binary forms, with or without
   4 .\" modification, are permitted provided that the following conditions
   5 .\" are met:
   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.
  11 .\"
  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
  22 .\" SUCH DAMAGE.
  23 .\"
  24 .\" $FreeBSD$
  25 .\"
  26 .Dd March 7, 2013
  27 .Dt DEVELOPMENT 7
  28 .Os
  29 .Sh NAME
  30 .Nm development
  31 .Nd "introduction to development with the FreeBSD codebase"
  32 .Sh DESCRIPTION
  33 This manual page describes how an ordinary system operator,
  34 .Ux
  35 administrator, or developer
  36 can, without any special permission, obtain, maintain, and modify the
  37 .Fx
  38 codebase as well as how to maintain a master build which can
  39 then be exported to other machines in your network.
  40 This manual page
  41 is targeted to system operators, programmers, and developers.
  42 .Pp
  43 Please note that what is being described here is based on a complete
  44 .Fx
  45 environment, not just the
  46 .Fx
  47 kernel.
  48 The methods described
  49 here are as applicable to production installations as it is to development
  50 environments.
  51 .Sh SETTING UP THE ENVIRONMENT ON THE MASTER SERVER
  52 Your master server should always run a stable, production version of the
  53 .Fx
  54 operating system.
  55 This does not prevent you from doing -CURRENT
  56 builds or development.
  57 The last thing you want to do is to run an
  58 unstable environment on your master server which could lead to a situation
  59 where you lose the environment and/or cannot recover from a mistake.
  60 .Pp
  61 Create a partition called
  62 .Pa /FreeBSD .
  63 Approximately 20GB is recommended.
  64 This partition will contain nearly all the development environment,
  65 including the subversion tree, broken-out source, and possibly even object files.
  66 You are going to export this partition to your other machines via a
  67 READ-ONLY NFS export so do not mix it with other more security-sensitive
  68 partitions.
  69 .Pp
  70 You have to make a choice in regards to
  71 .Pa /usr/obj .
  72 You can put
  73 .Pa /usr/obj
  74 in
  75 .Pa /FreeBSD
  76 or you can make
  77 .Pa /usr/obj
  78 its own partition.
  79 I recommend making it a separate partition for several reasons.
  80 First,
  81 as a safety measure since this partition is written to a great deal.
  82 Second, because you typically do not have to back it up.
  83 Third, because it makes it far easier to mix and match the development
  84 environments which are described later in this document.
  85 I recommend a
  86 .Pa /usr/obj
  87 partition of at least 12GB.
  88 .Pp
  89 On the master server, use
  90 .Xr svn 1
  91 to pull down and maintain
  92 the
  93 .Fx
  94 source.
  95 The first pull will take a long time,
  96 it is several gigabytes, but once you have it,
  97 the updates will be quite small.
  98 Run all
  99 .Xr svn 1
 100 operations as
 101 .Dq Li root
 102 .Pp
 103 Keeping the broken-out source and ports in
 104 .Pa /FreeBSD
 105 allows you to export
 106 it to other machines via read-only NFS.
 107 This also means you only need to edit/maintain files in one place and all
 108 your clients automatically pick up the changes.
 109 .Bd -literal -offset 4n
 110 mkdir /FreeBSD
 111 cd /FreeBSD
 112 svn co https://svn.freebsd.org/ports/head ports
 113 svn co https://svn.freebsd.org/doc/head doc
 114 svn co https://svn.freebsd.org/base/head src
 115 cd /usr
 116 rm -rf src
 117 ln -s /FreeBSD/src src
 118 .Ed
 119 .Pp
 120 Note that exporting
 121 .Pa /usr/obj
 122 via read-only NFS to your other boxes will
 123 allow you to build on your main server and install from your other boxes.
 124 If you also want to do builds on some or all of the clients you can simply
 125 have
 126 .Pa /usr/obj
 127 be a local directory on those clients.
 128 You should never export
 129 .Pa /usr/obj
 130 read-write, it will lead to all sorts of
 131 problems and issues down the line and presents a security problem as well.
 132 It is far easier to do builds on the master server and then only do installs
 133 on the clients.
 134 .Pp
 135 I usually maintain my ports tree via svn or portsnap.
 136 With some fancy softlinks you can make the ports tree available both on your
 137 master server and on all of your other machines.
 138 Note that the ports tree exists only on the HEAD ports branch, so its always
 139 usable even on a -STABLE box.
 140 This is what you do:
 141 .Bd -literal -offset 4n
 142 (THESE COMMANDS ON THE MASTER SERVER AND ON ALL CLIENTS)
 143 cd /usr
 144 rm -rf ports
 145 ln -s /FreeBSD/ports ports
 146
 147 cd /usr/ports                           (this pushes into the softlink)
 148 rm -rf distfiles                        (ON MASTER SERVER ONLY)
 149 ln -s /usr/ports.distfiles distfiles    (ON MASTER SERVER ONLY)
 150
 151 mkdir /usr/ports.distfiles
 152 mkdir /usr/ports.workdir
 153 .Ed
 154 .Pp
 155 Since
 156 .Pa /usr/ports
 157 is softlinked into what will be read-only on all of your
 158 clients, you have to tell the ports system to use a different working
 159 directory to hold ports builds.
 160 You want to add a line to your
 161 .Xr make.conf 5
 162 file on the master server
 163 and on all your clients:
 164 .Bd -literal -offset 4n
 165 WRKDIRPREFIX=/usr/ports.workdir
 166 .Ed
 167 .Pp
 168 You should try to make the directory you use for the ports working directory
 169 as well as the directory used to hold distfiles consistent across all of your
 170 machines.
 171 If there is not enough room in
 172 .Pa /usr/ports.distfiles
 173 and
 174 .Pa /usr/ports.workdir
 175 I usually make those softlinks (since this is on
 176 .Pa /usr
 177 these are per-machine) to
 178 where the distfiles and working space really are.
 179 .Sh EXPORTING VIA NFS FROM THE MASTER SERVER
 180 The master server needs to export
 181 .Pa /FreeBSD
 182 and
 183 .Pa /usr/obj
 184 via NFS so all the
 185 rest of your machines can get at them.
 186 I strongly recommend using a read-only export for both security and safety.
 187 The environment I am describing in this manual page is designed primarily
 188 around read-only NFS exports.
 189 Your exports file on the master server should contain the following lines:
 190 .Bd -literal -offset 4n
 191 /FreeBSD -ro -alldirs -maproot=root: -network YOURLAN -mask YOURLANMASK
 192 /usr/obj -ro -alldirs -maproot=root: -network YOURLAN -mask YOURLANMASK
 193 .Ed
 194 .Pp
 195 Of course, NFS server operations must also be configured on that machine.
 196 This is typically done via your
 197 .Pa /etc/rc.conf :
 198 .Bd -literal -offset 4n
 199 nfs_server_enable="YES"
 200 nfs_server_flags="-u -t -n 4"
 201 .Ed
 202 .Sh THE CLIENT ENVIRONMENT
 203 All of your client machines can import the development/build environment
 204 directory simply by NFS mounting
 205 .Pa /FreeBSD
 206 and
 207 .Pa /usr/obj
 208 from the master server.
 209 A typical
 210 .Pa /etc/fstab
 211 entry on your client machines will be something like this:
 212 .Bd -literal -offset 4n
 213 masterserver:/FreeBSD     /FreeBSD        nfs     ro,bg    0       0
 214 masterserver:/usr/obj     /usr/obj        nfs     ro,bg    0       0
 215 .Ed
 216 .Pp
 217 And, of course, you should configure the client for NFS client operations
 218 via
 219 .Pa /etc/rc.conf .
 220 In particular, this will turn on
 221 .Xr nfsiod 8
 222 which will improve client-side NFS
 223 performance:
 224 .Bd -literal -offset 4n
 225 nfs_client_enable="YES"
 226 .Ed
 227 .Pp
 228 Each client should create softlinks for
 229 .Pa /usr/ports
 230 and
 231 .Pa /usr/src
 232 that point
 233 into the NFS-mounted environment.
 234 If a particular client is running -CURRENT,
 235 .Pa /usr/src
 236 should be a softlink to
 237 .Pa /FreeBSD/src .
 238 If it is running -STABLE,
 239 .Pa /usr/src
 240 should be a softlink to
 241 .Pa /FreeBSD/FreeBSD-4.x/src .
 242 I do not usually create a
 243 .Pa /usr/src2
 244 softlink on
 245 clients, that is used as a convenient shortcut when working on the source
 246 code on the master server only and could create massive confusion (of the
 247 human variety) on a client.
 248 .Bd -literal -offset 4n
 249 (ON EACH CLIENT)
 250 cd /usr
 251 rm -rf ports src
 252 ln -s /FreeBSD/ports ports
 253 ln -s /FreeBSD/src src
 254 .Ed
 255 .Pp
 256 Do not forget to create the working directories so you can build ports, as
 257 previously described.
 258 If these are not good locations, make them softlinks to the correct location.
 259 Remember that
 260 .Pa /usr/ports/distfiles
 261 is exported by
 262 the master server and is therefore going to point to the same place
 263 (typically
 264 .Pa /usr/ports.distfiles )
 265 on every machine.
 266 .Bd -literal -offset 4n
 267 mkdir /usr/ports.distfiles
 268 mkdir /usr/ports.workdir
 269 .Ed
 270 .Sh BUILDING KERNELS
 271 Here is how you build a -STABLE kernel (on your main development box).
 272 If you want to create a custom kernel, copy
 273 .Pa GENERIC
 274 to
 275 .Pa KERNELNAME
 276 and then edit it before configuring and building.
 277 The kernel configuration file lives in
 278 .Pa /usr/src/sys/i386/conf/KERNELNAME .
 279 .Bd -literal -offset 4n
 280 cd /usr/src
 281 make buildkernel KERNCONF=KERNELNAME
 282 .Ed
 283 .Pp
 284 .Sy WARNING!
 285 If you are familiar with the old config/cd/make method of building
 286 a -STABLE kernel, note that the
 287 .Xr config 8
 288 method will put the build environment in
 289 .Pa /usr/src/sys/i386/compile/KERNELNAME
 290 instead of in
 291 .Pa /usr/obj .
 292 .Pp
 293 Building a -CURRENT kernel
 294 .Bd -literal -offset 4n
 295 cd /usr/src2            (on the master server)
 296 make buildkernel KERNCONF=KERNELNAME
 297 .Ed
 298 .Sh INSTALLING KERNELS
 299 Installing a -STABLE kernel (typically done on a client,
 300 only do this on your main development server if you want to install a new
 301 kernel for your main development server):
 302 .Bd -literal -offset 4n
 303 cd /usr/src
 304 make installkernel KERNCONF=KERNELNAME
 305 .Ed
 306 .Pp
 307 If you are using the older config/cd/make build mechanism for -STABLE, you
 308 would install using:
 309 .Bd -literal -offset 4n
 310 cd /usr/src/sys/i386/compile/KERNELNAME
 311 make install
 312 .Ed
 313 .Pp
 314 Installing a -CURRENT kernel (typically done only on a client)
 315 .Bd -literal -offset 4n
 316 (remember /usr/src is pointing to the client's specific environment)
 317 cd /usr/src
 318 make installkernel KERNCONF=KERNELNAME
 319 .Ed
 320 .Sh BUILDING THE WORLD
 321 This environment is designed such that you do all builds on the master server,
 322 and then install from each client.
 323 You can do builds on a client only if
 324 .Pa /usr/obj
 325 is local to that client.
 326 Building the world is easy:
 327 .Bd -literal -offset 4n
 328 cd /usr/src
 329 make buildworld
 330 .Ed
 331 .Pp
 332 If you are on the master server you are running in a -STABLE environment, but
 333 that does not prevent you from building the -CURRENT world.
 334 Just
 335 .Xr cd 1
 336 into the appropriate source directory and you are set.
 337 Do not
 338 accidentally install it on your master server though!
 339 .Bd -literal -offset 4n
 340 cd /usr/src2
 341 make buildworld
 342 .Ed
 343 .Sh INSTALLING THE WORLD
 344 You can build on your main development server and install on clients.
 345 The main development server must export
 346 .Pa /FreeBSD
 347 and
 348 .Pa /usr/obj
 349 via read-only NFS to the clients.
 350 .Pp
 351 .Em NOTE!!!
 352 If
 353 .Pa /usr/obj
 354 is a softlink on the master server, it must also be the EXACT
 355 SAME softlink on each client.
 356 If
 357 .Pa /usr/obj
 358 is a directory in
 359 .Pa /usr
 360 or a mount point on the master server,
 361 then it must be (interchangeably) a directory in
 362 .Pa /usr
 363 or a mount point on
 364 each client.
 365 This is because the
 366 absolute paths are expected to be the same when building the world as when
 367 installing it, and you generally build it on your main development box
 368 and install it from a client.
 369 If you do not set up
 370 .Pa /usr/obj
 371 properly you will not be able to build on
 372 machine and install on another.
 373 .Bd -literal -offset 4n
 374 (ON THE CLIENT)
 375 (remember /usr/src is pointing to the client's specific environment)
 376 cd /usr/src
 377 make installworld
 378 .Ed
 379 .Pp
 380 .Sy WARNING!
 381 If builds work on the master server but installs do not work from the
 382 clients, for example you try to install and the client complains that
 383 the install tried to write into the read-only
 384 .Pa /usr/obj ,
 385 then it is likely
 386 that the
 387 .Xr make.conf 5
 388 file on the client does not match the one on the
 389 master server closely enough and the install is trying to install something
 390 that was not built.
 391 .Sh DOING DEVELOPMENT ON A CLIENT (NOT JUST INSTALLING)
 392 Developers often want to run buildkernel's or buildworld's on client
 393 boxes simply to life-test the box.
 394 You do this in the same manner that you buildkernel and buildworld on your
 395 master server.
 396 All you have to do is make sure that
 397 .Pa /usr/obj
 398 is pointing to local storage.
 399 If you followed my advise and made
 400 .Pa /usr/obj
 401 its own partition on the master
 402 server,
 403 then it is typically going to be an NFS mount on the client.
 404 Simply unmounting
 405 .Pa /usr/obj
 406 will leave you with a
 407 .Pa /usr/obj
 408 that is a
 409 subdirectory in
 410 .Pa /usr
 411 which is typically local to the client.
 412 You can then do builds to your heart's content!
 413 .Sh MAINTAINING A LOCAL BRANCH
 414 There is absolutely nothing preventing you
 415 from breaking out other versions of the source tree
 416 into
 417 .Pa /FreeBSD/XXX .
 418 In fact, my
 419 .Pa /FreeBSD
 420 partition also contains
 421 .Ox ,
 422 .Nx ,
 423 and various flavors of
 424 .Tn Linux .
 425 You may not necessarily be able to build
 426 .Pf non- Fx
 427 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.
 432 .Pp
 433 Many developers choose to maintain a local branch of
 434 .Fx
 435 to test patches or build a custom distribution.
 436 This can be done with svn or another source code management system
 437 (git, mercurial, Perforce, BitKeeper) with its own repository.
 438 .Sh "UPDATING VIA SVN"
 439 By using a
 440 .Xr cron 8
 441 job to maintain an updated svn repository,
 442 the source tree can be
 443 updated at any time as follows:
 444 .Bd -literal -offset 4n
 445 (on the main development server)
 446 cd /usr
 447 svn update src doc ports
 448 .Ed
 449 .Pp
 450 It is that simple, and since you are exporting the whole lot to your
 451 clients, your clients have immediate visibility into the updated
 452 source.
 453 This is a good time to also remind you that most of the
 454 .Xr svn 1
 455 operations you do will be done as
 456 .Dq Li root .
 457 .Pp
 458 .Xr cron 8 .
 459 .Sh SEE ALSO
 460 .Xr crontab 1 ,
 461 .Xr crontab 5 ,
 462 .Xr make.conf 5 ,
 463 .Xr build 7 ,
 464 .Xr firewall 7 ,
 465 .Xr release 7 ,
 466 .Xr tuning 7 ,
 467 .Xr diskless 8
 468 .Sh HISTORY
 469 The
 470 .Nm
 471 manual page was originally written by
 472 .An Matthew Dillon Aq dillon@FreeBSD.org
 473 and first appeared
 474 in
 475 .Fx 5.0 ,
 476 December 2002.
 477 It was since extensively modified by
 478 .An Eitan Adler Aq eadler@FreeBSD.org
 479 to reflect the repository conversion from
 480 .Xr cvs
 481 to
 482 .Xr svn .