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