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