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 June 27, 2018
  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 do not clean out the obj modules.
 130 This target can be used for incremental upgrades once a full
 131 build of the kernel has been done with
 132 .Cm buildkernel .
 133 .It Cm realquickkernel
 134 Same as
 135 .Cm quickkernel ,
 136 but also skip the depend step.
 137 .It Cm installkernel
 138 Install the kernel and the kernel-modules.
 139 .It Cm reinstallkernel
 140 Reinstall the kernel and the kernel-modules.
 141 .It Cm kernel
 142 .Cm buildkernel +
 143 .Cm installkernel .
 144 .It Cm preupgrade
 145 Perform certain upgrades that have to be done before
 146 .Cm installworld ,
 147 such as adding new users and groups.
 148 .Cm installworld
 149 will complain if they have not been done.
 150 .It Cm upgrade
 151 Upgrade the files in /etc and also setup the rest of the system for
 152 the version of
 153 .Dx
 154 just installed.
 155 .It Cm rescue
 156 Build and install the statically linked rescue tools.
 157 .It Cm initrd
 158 Create the initial ramdisk based on the above rescue tools and install.
 159 .It Cm backupworld
 160 Manually archive binaries from installed world to location specified by
 161 .Ev WORLD_BACKUP .
 162 .It Cm backup-clean
 163 Delete archive created by
 164 .Cm backupworld .
 165 .It Cm backup-auto-clean
 166 Delete archive created automatically during
 167 .Cm installworld .
 168 .It Cm restoreworld
 169 Restore binaries from archive created by
 170 .Cm backupworld .
 171 .It Cm restoreworld-auto
 172 Restore binaries from archive created automatically during
 173 .Cm installworld .
 174 The archive location is specified by
 175 .Ev AUTO_BACKUP .
 176 .El
 177 .Sh ENVIRONMENT
 178 .Bl -tag -width ".Ev MAKEOBJDIRPREFIX"
 179 .It Ev TARGET_ARCH , TARGET_PLATFORM
 180 The target machine processor architecture and hardware platform.
 181 These have to be set for cross-building.
 182 .Ev TARGET_ARCH
 183 is analogous to the
 184 .Dq Nm uname Fl p
 185 output.
 186 For the 64 bit
 187 .Tn AMD
 188 architecture known as AMD64, x86-64 or Intel 64, use:
 189 .Bd -literal -offset indent
 190 TARGET_ARCH=x86_64
 191 TARGET_PLATFORM=pc64
 192 .Ed
 193 .It Ev DESTDIR
 194 An existing directory to be the root of
 195 the hierarchy where the resulting binaries will be
 196 installed (the default is
 197 .Pa / ) .
 198 .It Ev MAKEOBJDIRPREFIX
 199 The directory hierarchy where the object files will be built (the default is
 200 .Pa /usr/obj ) .
 201 .It Ev __MAKE_CONF
 202 Used to override the path of
 203 .Xr make.conf 5
 204 (the default is
 205 .Pa /etc/make.conf ) .
 206 .It Ev KERNCONF
 207 The name of one or more kernel configurations from which kernels should
 208 be built (the default is
 209 .Li X86_64_GENERIC ) .
 210 .It Ev KERNCONFDIR
 211 The directory where the kernel configuration files are kept (the default is
 212 .Pa /usr/src/sys/config ) .
 213 .It Ev DESTLABEL
 214 Common suffix added to kernel and modules directory names, prefixed by
 215 a single dot.  For example,
 216 .Bd -literal -offset indent
 217 make DESTLABEL=test installkernel
 218 .Ed
 219 .Pp
 220 installs them as
 221 .Pa /boot/kernel.test/kernel
 222 and
 223 .Pa /boot/kernel.test ,
 224 respectively.
 225 .It Ev DESTKERNDIR
 226 Where to install the kernel and the modules (the default is
 227 .Pa /boot ) ,
 228 in the directory hierarchy specified by the environment variable
 229 .Ev DESTDIR .
 230 .It Ev DESTKERNNAME
 231 The name of the installed kernel file (the default is
 232 .Pa kernel ) ,
 233 under the directory specified by
 234 .Ev DESTKERNDIR .
 235 This overrides the effect of
 236 .Ev DESTLABEL .
 237 .It Ev DESTMODULESNAME
 238 The name of the directory to install the kernel modules (the default is
 239 .Pa modules ) ,
 240 under the directory specified by
 241 .Ev DESTKERNDIR .
 242 This overrides the effect of
 243 .Ev DESTLABEL .
 244 .It Ev WORLD_BACKUP
 245 Directory for manual backup of binaries of installed world (default:
 246 .Pa /var/backups/world_backup ) .
 247 .It Ev AUTO_BACKUP
 248 Directory for automatic backup of binaries of installed world (default:
 249 .Ev MAKEOBJDIRPREFIX Ns /world_binaries/ Ns Ev DESTDIR ) .
 250 .It Ev NO_BACKUP
 251 When defined, the automatic backup feature of
 252 .Cm installworld
 253 is inhibited.
 254 .It Ev COPTFLAGS
 255 Overrides the default optimization flags for kernel and module compiles.
 256 .It Ev KCFLAGS
 257 Allows you to add additional compiler flags for kernel and module compiles.
 258 But use
 259 .Ev COPTFLAGS
 260 to specify any optimization overrides, as some modules may have to override
 261 it to enforce a lower optimization level.
 262 .El
 263 .Sh OTHER
 264 There are two other mechanisms that users should be aware of.  First,
 265 when you issue a
 266 .Cm installkernel
 267 .Dx
 268 will make a backup of the current kernel in
 269 .Pa /boot/kernel.old .
 270 Because people often do multiple installkernel operations, this backup
 271 kernel can also get lost in the noise.
 272 It is usually prudent to make a backup of the old kernel manually
 273 every once in a while when you know that it is a good kernel.  you can
 274 do this after issuing the
 275 .Cm installkernel
 276 by running the command:
 277 .Bd -literal -offset indent
 278 cpdup /boot/kernel.old /boot/kernel.bak
 279 .Ed
 280 .Pp
 281 The advantage of this is that no installation mechanism will overwrite
 282 your
 283 .Pa /boot/kernel.bak ,
 284 and in addition to that the loader's boot menu will check for its
 285 existence and present a menu option 'b' to allow you to boot from it.
 286 .Pp
 287 The second mechanism is related to the two-stage root mount.
 288 When using an encrypted root, the system will actually boot from a
 289 small initial ramdisk (a.k.a. initrd) image stored as
 290 .Pa /boot/kernel/initrd.img.gz .
 291 This image will handle the encrypted configuration, mount, and chroot
 292 to the real root.
 293 This image is also used as the rescue ramdisk boot menu option.
 294 This image is NOT updated automatically by
 295 .Cm installworld
 296 or
 297 .Cm installkernel .
 298 Instead, updating this image has to be done by running the manual command:
 299 .Bd -literal -offset indent
 300 make initrd
 301 .Ed
 302 .Pp
 303 It is usually a good idea to run this command after rebooting into the new
 304 world that you installed (so you know the world you installed is good).
 305 This command will update the initrd image in
 306 .Pa /boot/kernel .
 307 .Sh FILES
 308 .Bl -tag -width ".Pa /usr/src/Makefile_upgrade.inc" -compact
 309 .It Pa /etc/make.conf
 310 .It Pa /etc/defaults/make.conf
 311 .It Pa /usr/src/share/doc/Makefile
 312 .It Pa /usr/src/Makefile
 313 .It Pa /usr/src/Makefile.inc1
 314 .It Pa /usr/src/Makefile_upgrade.inc
 315 .El
 316 .Sh EXAMPLES
 317 The
 318 .Dq approved
 319 method of updating your system from the latest sources is:
 320 .Bd -literal -offset indent
 321 make buildworld
 322 make buildkernel KERNCONF=FOO
 323 make installkernel KERNCONF=FOO
 324 make installworld
 325 make upgrade
 326 .Ed
 327 .Pp
 328 After running these commands a system reboot is required,
 329 otherwise many programs which have been rebuilt (such as
 330 .Xr ps 1 ,
 331 .Xr top 1 ,
 332 etc.) may not work with the old kernel which is still running.
 333 .Pp
 334 The above mentioned build and install order enforces that the new kernel
 335 is installed before the new world.
 336 Sometimes it might be necessary to reboot the system between those two
 337 steps.
 338 In this case
 339 .Dq Nm make Cm installworld
 340 will tell you to do so.
 341 .Sh SEE ALSO
 342 .Xr cc 1 ,
 343 .Xr install 1 ,
 344 .Xr make 1 ,
 345 .Xr wmake 1 ,
 346 .Xr make.conf 5 ,
 347 .Xr development 7 ,
 348 .Xr dports 7 ,
 349 .Xr release 7 ,
 350 .Xr config 8 ,
 351 .Xr reboot 8 ,
 352 .Xr shutdown 8
 353 .Sh AUTHORS
 354 .An -nosplit
 355 .An Mike W. Meyer Aq Mt mwm@mired.org
 356 and
 357 .An Sascha Wildner Aq Mt swildner@gmail.com .