share/man/man7/build.7

   1 .\" Copyright (c) 2000
   2 .\"     Mike W. Meyer
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" $FreeBSD: src/share/man/man7/build.7,v 1.19.2.1 2002/03/18 08:33:02 murray Exp $
  26 .\"
  27 .Dd December 13, 2014
  28 .Dt BUILD 7
  29 .Os
  30 .Sh NAME
  31 .Nm build
  32 .Nd information on how to build the system
  33 .Sh DESCRIPTION
  34 The source for the
  35 .Dx
  36 system and applications is located in
  37 .Pa /usr/src .
  38 This directory contains the
  39 .Dq "base system"
  40 sources, which is loosely defined as the things required to rebuild
  41 the system to a useful state.
  42 It also contains the source for the system documentation, including
  43 manual pages.
  44 Refer to
  45 .Xr development 7
  46 for more information on how to obtain the
  47 .Dx
  48 sources.
  49 .Pp
  50 Third party applications have to be built using the
  51 .Xr dports 7
  52 system.
  53 The file
  54 .Pa /usr/Makefile
  55 has targets for obtaining the dports tree.
  56 Typing
  57 .Li make
  58 in
  59 .Pa /usr
  60 gives specifics on how to obtain the tree for building packages.
  61 .Pp
  62 The
  63 .Xr make 1
  64 command is used in
  65 .Pa /usr/src
  66 to build and install the things in that directory.
  67 Issuing the
  68 .Xr make 1
  69 command in any directory or
  70 subdirectory of those directories has the same effect as issuing the
  71 same command in all subdirectories of that directory.
  72 With no target specified, the things in that directory are just built.
  73 The following list provides the names and actions for other targets:
  74 .Bl -tag -width ".Cm install"
  75 .It Cm clean
  76 Removes any files created during the build process.
  77 .It Cm install
  78 Installs the results of the build for this directory.
  79 .El
  80 .Pp
  81 The other
  82 .Pa /usr/src
  83 make targets are:
  84 .Bl -tag -width ".Cm installworld-force"
  85 .It Cm buildworld
  86 Rebuild everything but the kernel.
  87 .It Cm quickworld
  88 Same as
  89 .Cm buildworld ,
  90 but skip bootstrap, build and cross-build tool steps.
  91 This target can be used for incremental upgrades once a full build of the
  92 world has been done with
  93 .Cm buildworld .
  94 .It Cm realquickworld
  95 Same as
  96 .Cm quickworld ,
  97 but also skip the depend step.
  98 .It Cm crossworld
  99 Just do the bootstrap, build and cross-build steps.
 100 .It Cm installworld
 101 Install everything built by
 102 .Cm buildworld .
 103 .It Cm installworld-force
 104 Force an
 105 .Cm installworld .
 106 This will install to a temporary directory, then copy the main binaries
 107 and libraries with a static
 108 .Xr cpdup 1
 109 to
 110 .Ev DESTDIR
 111 and finally will issue a normal
 112 .Cm installworld
 113 and
 114 .Cm upgrade .
 115 It is a special case to be used on older systems as a last resort when
 116 the normal
 117 .Cm installworld
 118 doesn't work.
 119 .It Cm world
 120 .Cm buildworld +
 121 .Cm installworld .
 122 .It Cm buildkernel
 123 Rebuild the kernel and the kernel-modules.
 124 .It Cm nativekernel
 125 Rebuild the kernel and the kernel-modules using native tools.
 126 .It Cm quickkernel
 127 Same as
 128 .Cm buildkernel ,
 129 but skip the depend step and do not clean out the
 130 obj modules.
 131 This target can be used for incremental upgrades once a full
 132 build of the kernel has been done with
 133 .Cm buildkernel .
 134 .It Cm installkernel
 135 Install the kernel and the kernel-modules.
 136 .It Cm reinstallkernel
 137 Reinstall the kernel and the kernel-modules.
 138 .It Cm kernel
 139 .Cm buildkernel +
 140 .Cm installkernel .
 141 .It Cm preupgrade
 142 Perform certain upgrades that have to be done before
 143 .Cm installworld .
 144 .Cm installworld
 145 will complain if they have not been done.
 146 .It Cm upgrade
 147 Upgrade the files in /etc and also setup the rest of the system for
 148 the version of
 149 .Dx
 150 just installed.
 151 .It Cm rescue
 152 Create a rescue initrd.
 153 .It Cm most
 154 Build user commands, no libraries or include files.
 155 .It Cm installmost
 156 Install user commands, no libraries or include files.
 157 .It Cm backupworld
 158 Manually archive binaries from installed world to location specified by
 159 .Ev WORLD_BACKUP .
 160 .It Cm backup-clean
 161 Delete archive created by
 162 .Cm backupworld .
 163 .It Cm backup-auto-clean
 164 Delete archive created automatically during
 165 .Cm installworld .
 166 .It Cm restoreworld
 167 Restore binaries from archive created by
 168 .Cm backupworld .
 169 .It Cm restoreworld-auto
 170 Restore binaries from archive created automatically during
 171 .Cm installworld .
 172 The archive location is specified by
 173 .Ev AUTO_BACKUP .
 174 .El
 175 .Sh ENVIRONMENT
 176 .Bl -tag -width ".Ev MAKEOBJDIRPREFIX"
 177 .It Ev TARGET_ARCH , TARGET_PLATFORM
 178 The target machine processor architecture and hardware platform.
 179 These have to be set for cross-building.
 180 .Ev TARGET_ARCH
 181 is analogous to the
 182 .Dq Nm uname Fl p
 183 output.
 184 To build for the 32 bit
 185 .Tn Intel
 186 architecture known as IA-32, x86 or x86-32, use:
 187 .Bd -literal -offset indent
 188 TARGET_ARCH=i386
 189 TARGET_PLATFORM=pc32
 190 .Ed
 191 .Pp
 192 For the 64 bit
 193 .Tn AMD
 194 architecture known as AMD64, x86-64 or Intel 64, use:
 195 .Bd -literal -offset indent
 196 TARGET_ARCH=x86_64
 197 TARGET_PLATFORM=pc64
 198 .Ed
 199 .It Ev DESTDIR
 200 An existing directory to be the root of
 201 the hierarchy where the resulting binaries will be
 202 installed (the default is
 203 .Pa / ) .
 204 .It Ev MAKEOBJDIRPREFIX
 205 The directory hierarchy where the object files will be built (the default is
 206 .Pa /usr/obj ) .
 207 .It Ev __MAKE_CONF
 208 Used to override the path of
 209 .Xr make.conf 5
 210 (the default is
 211 .Pa /etc/make.conf ) .
 212 .It Ev KERNCONF
 213 The name of the kernel configuration file from which the kernel should
 214 be built (the default is
 215 .Li GENERIC ) .
 216 .It Ev KERNCONFDIR
 217 The directory where the kernel configuration files are kept (the default is
 218 .Pa /usr/src/sys/config ) .
 219 .It Ev DESTLABEL
 220 Common suffix added to kernel and modules directory names, prefixed by
 221 a single dot.  For example,
 222 .Bd -literal -offset indent
 223 make DESTLABEL=test installkernel
 224 .Ed
 225 .Pp
 226 installs them as
 227 .Pa /boot/kernel.test/kernel
 228 and
 229 .Pa /boot/kernel.test ,
 230 respectively.
 231 .It Ev DESTKERNDIR
 232 Where to install the kernel and the modules (the default is
 233 .Pa /boot ) ,
 234 in the directory hierarchy specified by the environment variable
 235 .Ev DESTDIR .
 236 .It Ev DESTKERNNAME
 237 The name of the installed kernel file (the default is
 238 .Pa kernel ) ,
 239 under the directory specified by
 240 .Ev DESTKERNDIR .
 241 This overrides the effect of
 242 .Ev DESTLABEL .
 243 .It Ev DESTMODULESNAME
 244 The name of the directory to install the kernel modules (the default is
 245 .Pa modules ) ,
 246 under the directory specified by
 247 .Ev DESTKERNDIR .
 248 This overrides the effect of
 249 .Ev DESTLABEL .
 250 .It Ev WORLD_BACKUP
 251 Directory for manual backup of binaries of installed world (default:
 252 .Pa /var/backups/world_backup ) .
 253 .It Ev AUTO_BACKUP
 254 Directory for automatic backup of binaries of installed world (default:
 255 .Ev MAKEOBJDIRPREFIX Ns /world_binaries/ Ns Ev DESTDIR ) .
 256 .It Ev NO_BACKUP
 257 When defined, the automatic backup feature of
 258 .Cm installworld
 259 is inhibited.
 260 .El
 261 .Sh FILES
 262 .Bl -tag -width ".Pa /usr/src/Makefile_upgrade.inc" -compact
 263 .It Pa /etc/make.conf
 264 .It Pa /etc/defaults/make.conf
 265 .It Pa /usr/src/share/doc/Makefile
 266 .It Pa /usr/src/Makefile
 267 .It Pa /usr/src/Makefile.inc1
 268 .It Pa /usr/src/Makefile_upgrade.inc
 269 .El
 270 .Sh EXAMPLES
 271 The
 272 .Dq approved
 273 method of updating your system from the latest sources is:
 274 .Bd -literal -offset indent
 275 make buildworld
 276 make buildkernel KERNCONF=FOO
 277 make installkernel KERNCONF=FOO
 278 make installworld
 279 make upgrade
 280 .Ed
 281 .Pp
 282 After running these commands a system reboot is required,
 283 otherwise many programs which have been rebuilt (such as
 284 .Xr ps 1 ,
 285 .Xr top 1 ,
 286 etc.) may not work with the old kernel which is still running.
 287 .Sh CAVEATS
 288 The build and install order in the
 289 .Sx EXAMPLES
 290 section enforces that the new kernel is installed before the new
 291 world.
 292 Sometimes it might be necessary to reboot the system between those two
 293 steps.
 294 In this case
 295 .Dq Nm make Cm installworld
 296 will tell you to do so.
 297 .Sh SEE ALSO
 298 .Xr cc 1 ,
 299 .Xr install 1 ,
 300 .Xr make 1 ,
 301 .Xr wmake 1 ,
 302 .Xr make.conf 5 ,
 303 .Xr development 7 ,
 304 .Xr dports 7 ,
 305 .Xr release 7 ,
 306 .Xr config 8 ,
 307 .Xr reboot 8 ,
 308 .Xr shutdown 8
 309 .Sh AUTHORS
 310 .An -nosplit
 311 .An Mike W. Meyer Aq Mt mwm@mired.org
 312 and
 313 .An Sascha Wildner Aq Mt swildner@gmail.com .