Skip site navigation (1)Skip section navigation (2)

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
DEVELOPMENT(7)     FreeBSD Miscellaneous Information Manual     DEVELOPMENT(7)

NAME
     development - introduction to development with the FreeBSD codebase

DESCRIPTION
     This manual page describes how an ordinary system operator, UNIX
     administrator, or developer can, without any special permission, obtain,
     maintain, and modify the FreeBSD codebase as well as how to maintain a
     master build which can then be exported to other machines in your
     network.  This manual page is targeted to system operators, programmers,
     and developers.

     Please note that what is being described here is based on a complete
     FreeBSD environment, not just the FreeBSD kernel.  The methods described
     here are as applicable to production installations as it is to
     development environments.

SETTING UP THE ENVIRONMENT ON THE MASTER SERVER
     Your master server should always run a stable, production version of the
     FreeBSD operating system.  This does not prevent you from doing -CURRENT
     builds or development.  The last thing you want to do is to run an
     unstable environment on your master server which could lead to a
     situation where you lose the environment and/or cannot recover from a
     mistake.

     Create a partition called /FreeBSD.  Approximately 20GB is recommended.
     This partition will contain nearly all the development environment,
     including the subversion tree, broken-out source, and possibly even
     object files.  You are going to export this partition to your other
     machines via a READ-ONLY NFS export so do not mix it with other more
     security-sensitive partitions.

     You have to make a choice in regards to /usr/obj.  You can put /usr/obj
     in /FreeBSD or you can make /usr/obj its own partition.  I recommend
     making it a separate partition for several reasons.  First, as a safety
     measure since this partition is written to a great deal.  Second, because
     you typically do not have to back it up.  Third, because it makes it far
     easier to mix and match the development environments which are described
     later in this document.  I recommend a /usr/obj partition of at least
     12GB.

     On the master server, use svn(1) to pull down and maintain the FreeBSD
     source.  The first pull will take a long time, it is several gigabytes,
     but once you have it, the updates will be quite small.  Run all svn(1)
     operations as ``root''

     Keeping the broken-out source and ports in /FreeBSD allows you to export
     it to other machines via read-only NFS.  This also means you only need to
     edit/maintain files in one place and all your clients automatically pick
     up the changes.

         mkdir /FreeBSD
         cd /FreeBSD
         svn co https://svn.freebsd.org/ports/head ports
         svn co https://svn.freebsd.org/doc/head doc
         svn co https://svn.freebsd.org/base/head src
         cd /usr
         rm -rf src
         ln -s /FreeBSD/src src

     Note that exporting /usr/obj via read-only NFS to your other boxes will
     allow you to build on your main server and install from your other boxes.
     If you also want to do builds on some or all of the clients you can
     simply have /usr/obj be a local directory on those clients.  You should
     never export /usr/obj read-write, it will lead to all sorts of problems
     and issues down the line and presents a security problem as well.  It is
     far easier to do builds on the master server and then only do installs on
     the clients.

     I usually maintain my ports tree via svn or portsnap.  With some fancy
     softlinks you can make the ports tree available both on your master
     server and on all of your other machines.  Note that the ports tree
     exists only on the HEAD ports branch, so its always usable even on a
     -STABLE box.  This is what you do:

         (THESE COMMANDS ON THE MASTER SERVER AND ON ALL CLIENTS)
         cd /usr
         rm -rf ports
         ln -s /FreeBSD/ports ports

         cd /usr/ports                           (this pushes into the softlink)
         rm -rf distfiles                        (ON MASTER SERVER ONLY)
         ln -s /usr/ports.distfiles distfiles    (ON MASTER SERVER ONLY)

         mkdir /usr/ports.distfiles
         mkdir /usr/ports.workdir

     Since /usr/ports is softlinked into what will be read-only on all of your
     clients, you have to tell the ports system to use a different working
     directory to hold ports builds.  You want to add a line to your
     make.conf(5) file on the master server and on all your clients:

         WRKDIRPREFIX=/usr/ports.workdir

     You should try to make the directory you use for the ports working
     directory as well as the directory used to hold distfiles consistent
     across all of your machines.  If there is not enough room in
     /usr/ports.distfiles and /usr/ports.workdir I usually make those
     softlinks (since this is on /usr these are per-machine) to where the
     distfiles and working space really are.

EXPORTING VIA NFS FROM THE MASTER SERVER
     The master server needs to export /FreeBSD and /usr/obj via NFS so all
     the rest of your machines can get at them.  I strongly recommend using a
     read-only export for both security and safety.  The environment I am
     describing in this manual page is designed primarily around read-only NFS
     exports.  Your exports file on the master server should contain the
     following lines:

         /FreeBSD -ro -alldirs -maproot=root: -network YOURLAN -mask YOURLANMASK
         /usr/obj -ro -alldirs -maproot=root: -network YOURLAN -mask YOURLANMASK

     Of course, NFS server operations must also be configured on that machine.
     This is typically done via your /etc/rc.conf:

         nfs_server_enable="YES"
         nfs_server_flags="-u -t -n 4"

THE CLIENT ENVIRONMENT
     All of your client machines can import the development/build environment
     directory simply by NFS mounting /FreeBSD and /usr/obj from the master
     server.  A typical /etc/fstab entry on your client machines will be
     something like this:

         masterserver:/FreeBSD     /FreeBSD        nfs     ro,bg    0       0
         masterserver:/usr/obj     /usr/obj        nfs     ro,bg    0       0

     And, of course, you should configure the client for NFS client operations
     via /etc/rc.conf.  In particular, this will turn on nfsiod(8) which will
     improve client-side NFS performance:

         nfs_client_enable="YES"

     Each client should create softlinks for /usr/ports and /usr/src that
     point into the NFS-mounted environment.  If a particular client is
     running -CURRENT, /usr/src should be a softlink to /FreeBSD/src.  If it
     is running -STABLE, /usr/src should be a softlink to
     /FreeBSD/FreeBSD-4.x/src.  I do not usually create a /usr/src2 softlink
     on clients, that is used as a convenient shortcut when working on the
     source code on the master server only and could create massive confusion
     (of the human variety) on a client.

         (ON EACH CLIENT)
         cd /usr
         rm -rf ports src
         ln -s /FreeBSD/ports ports
         ln -s /FreeBSD/src src

     Do not forget to create the working directories so you can build ports,
     as previously described.  If these are not good locations, make them
     softlinks to the correct location.  Remember that /usr/ports/distfiles is
     exported by the master server and is therefore going to point to the same
     place (typically /usr/ports.distfiles) on every machine.

         mkdir /usr/ports.distfiles
         mkdir /usr/ports.workdir

BUILDING KERNELS
     Here is how you build a -STABLE kernel (on your main development box).
     If you want to create a custom kernel, copy GENERIC to KERNELNAME and
     then edit it before configuring and building.  The kernel configuration
     file lives in /usr/src/sys/i386/conf/KERNELNAME.

         cd /usr/src
         make buildkernel KERNCONF=KERNELNAME

     WARNING! If you are familiar with the old config/cd/make method of
     building a -STABLE kernel, note that the config(8) method will put the
     build environment in /usr/src/sys/i386/compile/KERNELNAME instead of in
     /usr/obj.

     Building a -CURRENT kernel

         cd /usr/src2            (on the master server)
         make buildkernel KERNCONF=KERNELNAME

INSTALLING KERNELS
     Installing a -STABLE kernel (typically done on a client, only do this on
     your main development server if you want to install a new kernel for your
     main development server):

         cd /usr/src
         make installkernel KERNCONF=KERNELNAME

     If you are using the older config/cd/make build mechanism for -STABLE,
     you would install using:

         cd /usr/src/sys/i386/compile/KERNELNAME
         make install

     Installing a -CURRENT kernel (typically done only on a client)

         (remember /usr/src is pointing to the client's specific environment)
         cd /usr/src
         make installkernel KERNCONF=KERNELNAME

BUILDING THE WORLD
     This environment is designed such that you do all builds on the master
     server, and then install from each client.  You can do builds on a client
     only if /usr/obj is local to that client.  Building the world is easy:

         cd /usr/src
         make buildworld

     If you are on the master server you are running in a -STABLE environment,
     but that does not prevent you from building the -CURRENT world.  Just
     cd(1) into the appropriate source directory and you are set.  Do not
     accidentally install it on your master server though!

         cd /usr/src2
         make buildworld

INSTALLING THE WORLD
     You can build on your main development server and install on clients.
     The main development server must export /FreeBSD and /usr/obj via read-
     only NFS to the clients.

     NOTE!!! If /usr/obj is a softlink on the master server, it must also be
     the EXACT SAME softlink on each client.  If /usr/obj is a directory in
     /usr or a mount point on the master server, then it must be
     (interchangeably) a directory in /usr or a mount point on each client.
     This is because the absolute paths are expected to be the same when
     building the world as when installing it, and you generally build it on
     your main development box and install it from a client.  If you do not
     set up /usr/obj properly you will not be able to build on machine and
     install on another.

         (ON THE CLIENT)
         (remember /usr/src is pointing to the client's specific environment)
         cd /usr/src
         make installworld

     WARNING! If builds work on the master server but installs do not work
     from the clients, for example you try to install and the client complains
     that the install tried to write into the read-only /usr/obj, then it is
     likely that the make.conf(5) file on the client does not match the one on
     the master server closely enough and the install is trying to install
     something that was not built.

DOING DEVELOPMENT ON A CLIENT (NOT JUST INSTALLING)
     Developers often want to run buildkernel's or buildworld's on client
     boxes simply to life-test the box.  You do this in the same manner that
     you buildkernel and buildworld on your master server.  All you have to do
     is make sure that /usr/obj is pointing to local storage.  If you followed
     my advise and made /usr/obj its own partition on the master server, then
     it is typically going to be an NFS mount on the client.  Simply
     unmounting /usr/obj will leave you with a /usr/obj that is a subdirectory
     in /usr which is typically local to the client.  You can then do builds
     to your heart's content!

MAINTAINING A LOCAL BRANCH
     There is absolutely nothing preventing you from breaking out other
     versions of the source tree into /FreeBSD/XXX.  In fact, my /FreeBSD
     partition also contains OpenBSD, NetBSD, and various flavors of Linux.
     You may not necessarily be able to build non-FreeBSD operating systems on
     your master server, but being able to collect and manage source
     distributions from a central server is a very useful thing to be able to
     do and you can certainly export to machines which can build those other
     operating systems.

     Many developers choose to maintain a local branch of FreeBSD to test
     patches or build a custom distribution.  This can be done with svn or
     another source code management system (git, mercurial, Perforce,
     BitKeeper) with its own repository.

UPDATING VIA SVN
     By using a cron(8) job to maintain an updated svn repository, the source
     tree can be updated at any time as follows:

         (on the main development server)
         cd /usr
         svn update src doc ports

     It is that simple, and since you are exporting the whole lot to your
     clients, your clients have immediate visibility into the updated source.
     This is a good time to also remind you that most of the svn(1) operations
     you do will be done as ``root''.

     cron(8).

SEE ALSO
     crontab(1), crontab(5), make.conf(5), build(7), firewall(7), release(7),
     tuning(7), diskless(8)

HISTORY
     The development manual page was originally written by Matthew Dillon
     <dillon@FreeBSD.org> and first appeared in FreeBSD 5.0, December 2002.
     It was since extensively modified by Eitan Adler <eadler@FreeBSD.org> to
     reflect the repository conversion from cvs to svn.

FreeBSD 11.0-PRERELEASE          March 7, 2013         FreeBSD 11.0-PRERELEASE

NAME | DESCRIPTION | SETTING UP THE ENVIRONMENT ON THE MASTER SERVER | EXPORTING VIA NFS FROM THE MASTER SERVER | THE CLIENT ENVIRONMENT | BUILDING KERNELS | INSTALLING KERNELS | BUILDING THE WORLD | INSTALLING THE WORLD | DOING DEVELOPMENT ON A CLIENT (NOT JUST INSTALLING) | MAINTAINING A LOCAL BRANCH | UPDATING VIA SVN | SEE ALSO | HISTORY

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=development&sektion=7&manpath=FreeBSD+10.3-RELEASE+and+Ports>

home | help