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