path: root/static/freebsd/man7/build.7 3.html

<table class="head">
  <tr>
    <td class="head-ltitle">BUILD(7)</td>
    <td class="head-vol">Miscellaneous Information Manual</td>
    <td class="head-rtitle">BUILD(7)</td>
  </tr>
</table>
<div class="manual-text">
<section class="Sh">
<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1>
<p class="Pp"><code class="Nm">build</code> &#x2014; <span class="Nd">general
    instructions on how to build the <span class="Ux">FreeBSD</span>
    system</span></p>
</section>
<section class="Sh">
<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1>
<p class="Pp">The sources for the <span class="Ux">FreeBSD</span> system and its
    applications are contained in three directories, normally:</p>
<dl class="Bl-tag">
  <dt><span class="Pa">/usr/src</span></dt>
  <dd>&#x201C;base system&#x201D;, loosely defined as everything required to
      build the system to a useful state</dd>
  <dt><span class="Pa">/usr/doc</span></dt>
  <dd>system documentation, excluding manual pages</dd>
  <dt><span class="Pa">/usr/ports</span></dt>
  <dd>third-party software, with a consistent interface for building and
      installing them; see <a class="Xr">ports(7)</a></dd>
</dl>
<p class="Pp">These directories may be initially empty or non-existent until
    updated with Git (<span class="Pa">devel/git</span> from the
    <span class="Ux">FreeBSD</span> Ports Collection).</p>
<p class="Pp">The <a class="Xr">make(1)</a> command is used in each of these
    directories to build and install the things in that directory. Issuing the
    <a class="Xr">make(1)</a> command in any directory issues the
    <a class="Xr">make(1)</a> command recursively in all subdirectories. With no
    target specified, the items in the directories are built and no further
    action is taken.</p>
<p class="Pp">A source tree is allowed to be read-only. As described in
    <a class="Xr">make(1)</a>, objects are usually built in a separate object
    directory hierarchy specified by the environment variable
    <var class="Va">MAKEOBJDIRPREFIX</var>, or under
    <span class="Pa">/usr/obj</span> if variable
    <var class="Va">MAKEOBJDIRPREFIX</var> is not set. The canonical object
    directory is described in the documentation for the
    <code class="Cm">buildworld</code> target below.</p>
<p class="Pp">The <code class="Nm">build</code> may be controlled by defining
    <a class="Xr">make(1)</a> variables described in the
    <a class="Sx" href="#ENVIRONMENT">ENVIRONMENT</a> section below, and by the
    variables documented in <a class="Xr">make.conf(5)</a>.</p>
<p class="Pp">The default components included in the build are specified in the
    file <span class="Pa">/etc/src.conf</span> in the source tree. To override
    the default file, include the SRCCONF option in the make steps, pointing to
    a custom src.conf file. For more information see
    <a class="Xr">src.conf(5)</a>.</p>
<p class="Pp">The following list provides the names and actions for the targets
    supported by the build system:</p>
<dl class="Bl-tag">
  <dt id="analyze"><a class="permalink" href="#analyze"><code class="Cm">analyze</code></a></dt>
  <dd>Run Clang static analyzer against all objects and present output on
      stdout.</dd>
  <dt id="check"><a class="permalink" href="#check"><code class="Cm">check</code></a></dt>
  <dd>Run tests for a given subdirectory. The default directory used is
      <span class="Pa">${.OBJDIR}</span>, but the check directory can be changed
      with <span class="Pa">${CHECKDIR}</span>.</dd>
  <dt id="checkworld"><a class="permalink" href="#checkworld"><code class="Cm">checkworld</code></a></dt>
  <dd>Run the <span class="Ux">FreeBSD</span> test suite on installed
    world.</dd>
  <dt id="clean"><a class="permalink" href="#clean"><code class="Cm">clean</code></a></dt>
  <dd>Remove any files created during the build process.</dd>
  <dt id="cleandepend"><a class="permalink" href="#cleandepend"><code class="Cm">cleandepend</code></a></dt>
  <dd>Remove the <span class="Pa">${.OBJDIR}/${DEPENDFILE}*</span> files
      generated by prior &#x201C;<code class="Li">make</code>&#x201D; and
      &#x201C;<code class="Li">make depend</code>&#x201D; steps.</dd>
  <dt id="cleandir"><a class="permalink" href="#cleandir"><code class="Cm">cleandir</code></a></dt>
  <dd>Remove the canonical object directory if it exists, or perform actions
      equivalent to &#x201C;<code class="Li">make clean
      cleandepend</code>&#x201D; if it does not. This target will also remove an
      <span class="Pa">obj</span> link in <span class="Pa">${.CURDIR}</span> if
      that exists.
    <p class="Pp">It is advisable to run &#x201C;<code class="Li">make
        cleandir</code>&#x201D; twice: the first invocation will remove the
        canonical object directory and the second one will clean up
        <span class="Pa">${.CURDIR}</span>.</p>
  </dd>
  <dt id="depend"><a class="permalink" href="#depend"><code class="Cm">depend</code></a></dt>
  <dd>Generate a list of build dependencies in file
      <span class="Pa">${.OBJDIR}/${DEPENDFILE}</span>. Per-object dependencies
      are generated at build time and stored in
      <span class="Pa">${.OBJDIR}/${DEPENDFILE}.${OBJ}</span>.</dd>
  <dt id="install"><a class="permalink" href="#install"><code class="Cm">install</code></a></dt>
  <dd>Install the results of the build to the appropriate location in the
      installation directory hierarchy specified in variable
      <var class="Va">DESTDIR</var>.</dd>
  <dt id="obj"><a class="permalink" href="#obj"><code class="Cm">obj</code></a></dt>
  <dd>Create the canonical object directory associated with the current
      directory.</dd>
  <dt id="objlink"><a class="permalink" href="#objlink"><code class="Cm">objlink</code></a></dt>
  <dd>Create a symbolic link to the canonical object directory in
      <span class="Pa">${.CURDIR}</span>.</dd>
  <dt id="tags"><a class="permalink" href="#tags"><code class="Cm">tags</code></a></dt>
  <dd>Generate a tags file using the program specified in the
      <a class="Xr">make(1)</a> variable <var class="Va">CTAGS</var>. The build
      system supports <a class="Xr">ctags(1)</a> and <code class="Nm">GNU
      Global</code>.</dd>
</dl>
<p class="Pp">The other supported targets under directory
    <span class="Pa">/usr/src</span> are:</p>
<dl class="Bl-tag">
  <dt id="buildenv"><a class="permalink" href="#buildenv"><code class="Cm">buildenv</code></a></dt>
  <dd>Spawn an interactive shell with environment variables set up for building
      the system or individual components. For cross-building the target
      architecture needs to be specified with <a class="Xr">make(1)</a>
      variables <var class="Va">TARGET_ARCH</var> and
      <var class="Va">TARGET</var>.
    <p class="Pp">This target is only useful after a complete toolchain
        (including the compiler, linker, assembler, headers and libraries) has
        been built; see the <code class="Cm">toolchain</code> target below.</p>
    <p class="Pp"><var class="Va">BUILDENV_SHELL</var>, which defaults to
        <span class="Pa">/bin/sh</span>, is executed. This can be set to a
        command that does something in this build environment, like cross build
        an application. If that application has dependencies, though, the
        <span class="Pa">devel/poudriere</span> package or port provides a more
        generic solution.</p>
  </dd>
  <dt id="buildenvvars"><a class="permalink" href="#buildenvvars"><code class="Cm">buildenvvars</code></a></dt>
  <dd>Print the shell variables that are set for a
      <code class="Cm">buildenv</code> environment and exit.</dd>
  <dt id="buildworld"><a class="permalink" href="#buildworld"><code class="Cm">buildworld</code></a></dt>
  <dd>Build everything but the kernel, configure files in
      <span class="Pa">etc</span>, and <span class="Pa">release</span>. The
      object directory can be changed from the default
      <span class="Pa">/usr/obj</span> by setting the
      <span class="Pa">MAKEOBJDIRPREFIX</span> <a class="Xr">make(1)</a>
      variable. The actual build location prefix used depends on the
      <var class="Va">WITH_UNIFIED_OBJDIR</var> option from
      <a class="Xr">src.conf(5)</a>. If enabled it is
      <span class="Pa">${MAKEOBJDIRPREFIX}${.CURDIR}/${TARGET}.${TARGET_ARCH}</span>
      for all builds. If disabled it is
      <span class="Pa">${MAKEOBJDIRPREFIX}${.CURDIR}</span> for native builds,
      and
      <span class="Pa">${MAKEOBJDIRPREFIX}/${TARGET}.${TARGET_ARCH}${.CURDIR}</span>
      for cross builds and native builds with variable
      <var class="Va">CROSS_BUILD_TESTING</var> set.</dd>
  <dt id="cleankernel"><a class="permalink" href="#cleankernel"><code class="Cm">cleankernel</code></a></dt>
  <dd>Attempts to clean up targets built by a preceding
      <code class="Cm">buildkernel</code>, or similar step, built from the same
      source directory and <var class="Va">KERNCONF</var>.</dd>
  <dt id="cleanworld"><a class="permalink" href="#cleanworld"><code class="Cm">cleanworld</code></a></dt>
  <dd>Attempt to clean up targets built by a preceding
      <code class="Cm">buildworld</code>, or similar step, built from this
      source directory.</dd>
  <dt id="cleanuniverse"><a class="permalink" href="#cleanuniverse"><code class="Cm">cleanuniverse</code></a></dt>
  <dd>When <var class="Va">WITH_UNIFIED_OBJDIR</var> is enabled, attempt to
      clean up targets built by a preceding <code class="Cm">buildworld</code>,
      <code class="Cm">universe</code>, or similar step, for any architecture
      built from this source directory.</dd>
  <dt id="distributeworld"><a class="permalink" href="#distributeworld"><code class="Cm">distributeworld</code></a></dt>
  <dd>Distribute everything compiled by a preceding
      <code class="Cm">buildworld</code> step. Files are placed in the directory
      hierarchy specified by <a class="Xr">make(1)</a> variable
      <var class="Va">DISTDIR</var>. This target is used while building a
      release; see <a class="Xr">release(7)</a>.</dd>
  <dt id="native-xtools"><a class="permalink" href="#native-xtools"><code class="Cm">native-xtools</code></a></dt>
  <dd>This target builds a cross-toolchain for the given
      <b class="Sy">TARGET</b> and <b class="Sy">TARGET_ARCH</b>, as well as a
      select list of static userland tools for the host system. This is intended
      to be used in a jail where QEMU is used to improve performance by avoiding
      emulating binaries that do not need to be emulated.
      <b class="Sy">TARGET</b> and <b class="Sy">TARGET_ARCH</b> should be
      defined.</dd>
  <dt id="native-xtools-install"><a class="permalink" href="#native-xtools-install"><code class="Cm">native-xtools-install</code></a></dt>
  <dd>Installs the results to <span class="Pa">${DESTDIR}/${NXTP}</span> where
      <var class="Va">NXTP</var> defaults to <span class="Pa">nxb-bin</span>.
      <b class="Sy">TARGET</b> and <b class="Sy">TARGET_ARCH</b> must be
      defined.</dd>
  <dt id="packages"><a class="permalink" href="#packages"><code class="Cm">packages</code></a></dt>
  <dd>Create a <a class="Xr">freebsd-base(7)</a> package repository containing
      packages that can be used to install or upgrade the base system. The
      repository is created in the object directory, under
      <span class="Pa">${REPODIR}/${PKG_ABI}</span> where
      <code class="Ev">REPODIR</code> is the base directory where the repository
      will be created, and <var class="Va">PKG_ABI</var> is the
      <a class="Xr">pkg(7)</a> ABI for the build target, for example,
      <span class="Pa">/usr/obj/${SRCDIR}/repo/FreeBSD:15:amd64</span>.</dd>
  <dt id="packageworld"><a class="permalink" href="#packageworld"><code class="Cm">packageworld</code></a></dt>
  <dd>Archive the results of <code class="Cm">distributeworld</code>, placing
      the results in <var class="Va">DISTDIR</var>. This target is used while
      building a <a class="Xr">release(7)</a> and is unrelated to building
      <a class="Xr">freebsd-base(7)</a> packages.</dd>
  <dt id="installworld"><a class="permalink" href="#installworld"><code class="Cm">installworld</code></a></dt>
  <dd>Install everything built by a preceding <code class="Cm">buildworld</code>
      step into the directory hierarchy pointed to by <a class="Xr">make(1)</a>
      variable <var class="Va">DESTDIR</var>.
    <p class="Pp">If installing onto an NFS file system and running
        <a class="Xr">make(1)</a> with the <code class="Fl">-j</code> option,
        make sure that <a class="Xr">rpc.lockd(8)</a> is running on both client
        and server. See <a class="Xr">rc.conf(5)</a> on how to make it start at
        boot time.</p>
  </dd>
  <dt id="toolchain"><a class="permalink" href="#toolchain"><code class="Cm">toolchain</code></a></dt>
  <dd>Create the build toolchain needed to build the rest of the system. For
      cross-architecture builds, this step creates a cross-toolchain.</dd>
  <dt id="universe"><a class="permalink" href="#universe"><code class="Cm">universe</code></a></dt>
  <dd>For each architecture, execute a <code class="Cm">buildworld</code>
      followed by a <code class="Cm">buildkernel</code> for all kernels for that
      architecture, including <span class="Pa">LINT</span>. This command takes a
      long time.</dd>
  <dt id="kernels"><a class="permalink" href="#kernels"><code class="Cm">kernels</code></a></dt>
  <dd>Like <code class="Cm">universe</code> with
      <var class="Va">WITHOUT_WORLDS</var> defined so only the kernels for each
      architecture are built.</dd>
  <dt id="worlds"><a class="permalink" href="#worlds"><code class="Cm">worlds</code></a></dt>
  <dd>Like <code class="Cm">universe</code> with
      <var class="Va">WITHOUT_KERNELS</var> defined so only the worlds for each
      architecture are built.</dd>
  <dt id="targets"><a class="permalink" href="#targets"><code class="Cm">targets</code></a></dt>
  <dd>Print a list of supported <var class="Va">TARGET</var> /
      <var class="Va">TARGET_ARCH</var> pairs for world and kernel targets.</dd>
  <dt id="tinderbox"><a class="permalink" href="#tinderbox"><code class="Cm">tinderbox</code></a></dt>
  <dd>Execute the same targets as <code class="Cm">universe</code>. In addition
      print a summary of all failed targets at the end and exit with an error if
      there were any.</dd>
  <dt id="toolchains"><a class="permalink" href="#toolchains"><code class="Cm">toolchains</code></a></dt>
  <dd>Create a build toolchain for each architecture supported by the build
      system.</dd>
  <dt id="xdev"><a class="permalink" href="#xdev"><code class="Cm">xdev</code></a></dt>
  <dd>Builds and installs a cross-toolchain and sysroot for the given
      <b class="Sy">TARGET</b> and <b class="Sy">TARGET_ARCH</b>. The sysroot
      contains target library and headers. The target is an alias for
      <code class="Cm">xdev-build</code> and
      <code class="Cm">xdev-install</code>. The location of the files installed
      can be controlled with <var class="Va">DESTDIR</var>. The target location
      in <var class="Va">DESTDIR</var> is
      <span class="Pa">${DESTDIR}/${XDTP}</span> where
      <var class="Va">XDTP</var> defaults to
      <span class="Pa">/usr/${XDDIR}</span> and <var class="Va">XDDIR</var>
      defaults to <span class="Pa">${TARGET_ARCH}-freebsd</span>.</dd>
  <dt id="update-packages"><a class="permalink" href="#update-packages"><code class="Cm">update-packages</code></a></dt>
  <dd>Create or update the <a class="Xr">freebsd-base(7)</a> package repository
      for the base system. If an old repository is being updated, then packages
      whose contents have not changed since the previous version will be copied
      into the new repository to avoid needless updating of the version
    number.</dd>
  <dt id="xdev-build"><a class="permalink" href="#xdev-build"><code class="Cm">xdev-build</code></a></dt>
  <dd>Builds for the <code class="Cm">xdev</code> target.</dd>
  <dt id="xdev-install"><a class="permalink" href="#xdev-install"><code class="Cm">xdev-install</code></a></dt>
  <dd>Installs the files for the <code class="Cm">xdev</code> target.</dd>
  <dt id="xdev-links"><a class="permalink" href="#xdev-links"><code class="Cm">xdev-links</code></a></dt>
  <dd>Installs autoconf-style symlinks to
      <span class="Pa">${DESTDIR}/usr/bin</span> pointing into the xdev
      toolchain in <span class="Pa">${DESTDIR}/${XDTP}</span>.</dd>
</dl>
<p class="Pp">Kernel specific build targets in <span class="Pa">/usr/src</span>
    are:</p>
<dl class="Bl-tag">
  <dt id="buildkernel"><a class="permalink" href="#buildkernel"><code class="Cm">buildkernel</code></a></dt>
  <dd>Rebuild the kernel and the kernel modules. The object directory can be
      changed from the default <span class="Pa">/usr/obj</span> by setting the
      <span class="Pa">MAKEOBJDIRPREFIX</span> <a class="Xr">make(1)</a>
      variable.</dd>
  <dt id="installkernel"><a class="permalink" href="#installkernel"><code class="Cm">installkernel</code></a></dt>
  <dd>Install the kernel and the kernel modules to directory
      <span class="Pa">${DESTDIR}/boot/kernel</span>, renaming any pre-existing
      directory with this name to <span class="Pa">kernel.old</span> if it
      contained the currently running kernel. The target directory under
      <span class="Pa">${DESTDIR}</span> may be modified using the
      <var class="Va">INSTKERNNAME</var> or <var class="Va">KODIR</var>
      <a class="Xr">make(1)</a> variables.</dd>
  <dt id="distributekernel"><a class="permalink" href="#distributekernel"><code class="Cm">distributekernel</code></a></dt>
  <dd>Install the kernel to the directory
      <span class="Pa">${DISTDIR}/kernel/boot/kernel</span>. This target is used
      while building a release; see <a class="Xr">release(7)</a>.</dd>
  <dt id="packagekernel"><a class="permalink" href="#packagekernel"><code class="Cm">packagekernel</code></a></dt>
  <dd>Archive the results of <code class="Cm">distributekernel</code>, placing
      the results in <var class="Va">DISTDIR</var>. This target is used while
      building a <a class="Xr">release(7)</a> and is unrelated to building
      <a class="Xr">freebsd-base(7)</a> packages.</dd>
  <dt id="kernel"><a class="permalink" href="#kernel"><code class="Cm">kernel</code></a></dt>
  <dd>Equivalent to <code class="Cm">buildkernel</code> followed by
      <code class="Cm">installkernel</code></dd>
  <dt id="kernel-toolchain"><a class="permalink" href="#kernel-toolchain"><code class="Cm">kernel-toolchain</code></a></dt>
  <dd>Rebuild the tools needed for kernel compilation. Use this if you did not
      do a <code class="Cm">buildworld</code> first.</dd>
  <dt id="reinstallkernel"><a class="permalink" href="#reinstallkernel"><code class="Cm">reinstallkernel</code></a></dt>
  <dd>Reinstall the kernel and the kernel modules, overwriting the contents of
      the target directory. As with the <code class="Cm">installkernel</code>
      target, the target directory can be specified using the
      <a class="Xr">make(1)</a> variable
    <var class="Va">INSTKERNNAME</var>.</dd>
</dl>
<p class="Pp">Convenience targets for cleaning up the install destination
    directory denoted by variable <var class="Va">DESTDIR</var> include:</p>
<dl class="Bl-tag">
  <dt id="check-old"><a class="permalink" href="#check-old"><code class="Cm">check-old</code></a></dt>
  <dd>Print a list of old files and directories in the system.</dd>
  <dt id="check-old-libs"><a class="permalink" href="#check-old-libs"><code class="Cm">check-old-libs</code></a></dt>
  <dd>Print a list of obsolete base system libraries.</dd>
  <dt id="delete-old"><a class="permalink" href="#delete-old"><code class="Cm">delete-old</code></a></dt>
  <dd>Delete obsolete base system files and directories interactively. When
      <code class="Li">-DBATCH_DELETE_OLD_FILES</code> is specified at the
      command line, the delete operation will be non-interactive. The variables
      <var class="Va">DESTDIR</var>, <var class="Va">TARGET_ARCH</var> and
      <var class="Va">TARGET</var> should be set as with
      &#x201C;<code class="Li">make installworld</code>&#x201D;.</dd>
  <dt id="delete-old-libs"><a class="permalink" href="#delete-old-libs"><code class="Cm">delete-old-libs</code></a></dt>
  <dd>Delete obsolete base system libraries interactively. This target should
      only be used if no third party software uses these libraries. When
      <code class="Li">-DBATCH_DELETE_OLD_FILES</code> is specified at the
      command line, the delete operation will be non-interactive. The variables
      <var class="Va">DESTDIR</var>, <var class="Va">TARGET_ARCH</var> and
      <var class="Va">TARGET</var> should be set as with
      &#x201C;<code class="Li">make installworld</code>&#x201D;.</dd>
</dl>
</section>
<section class="Sh">
<h1 class="Sh" id="ENVIRONMENT"><a class="permalink" href="#ENVIRONMENT">ENVIRONMENT</a></h1>
<p class="Pp">Variables that influence all builds include:</p>
<dl class="Bl-tag">
  <dt id="DEBUG_FLAGS"><var class="Va">DEBUG_FLAGS</var></dt>
  <dd>Defines a set of debugging flags that will be used to build all userland
      binaries under <span class="Pa">/usr/src</span>. When
      <var class="Va">DEBUG_FLAGS</var> is defined, the
      <code class="Cm">install</code> and <code class="Cm">installworld</code>
      targets install binaries from the current
      <var class="Va">MAKEOBJDIRPREFIX</var> without stripping, so that
      debugging information is retained in the installed binaries.</dd>
  <dt id="DESTDIR"><var class="Va">DESTDIR</var></dt>
  <dd>The directory hierarchy prefix where built objects will be installed. If
      not set, <var class="Va">DESTDIR</var> defaults to the empty string. If
      set, <var class="Va">DESTDIR</var> must specify an absolute path.</dd>
  <dt id="MAKEOBJDIRPREFIX"><var class="Va">MAKEOBJDIRPREFIX</var></dt>
  <dd>Defines the prefix for directory names in the tree of built objects.
      Defaults to <span class="Pa">/usr/obj</span> if not defined. This variable
      should only be set in the environment or
      <span class="Pa">/etc/src-env.conf</span> and not via
      <span class="Pa">/etc/make.conf</span> or
      <span class="Pa">/etc/src.conf</span> or the command line.
      <var class="Va">MAKEOBJDIRPREFIX</var> must specify an absolute path.</dd>
  <dt id="WITHOUT_WERROR"><var class="Va">WITHOUT_WERROR</var></dt>
  <dd>If defined, compiler warnings will not cause the build to halt, even if
      the makefile says otherwise.</dd>
  <dt id="WITH_CTF"><var class="Va">WITH_CTF</var></dt>
  <dd>If defined, the build process will run the DTrace CTF conversion tools on
      built objects.</dd>
</dl>
<p class="Pp">Additionally, builds in <span class="Pa">/usr/src</span> are
    influenced by the following <a class="Xr">make(1)</a> variables:</p>
<dl class="Bl-tag">
  <dt id="CROSS_TOOLCHAIN"><var class="Va">CROSS_TOOLCHAIN</var></dt>
  <dd>Requests use of an external toolchain to build either the world or kernel.
      This value of this variable can either be the full path to a file, or the
      base name of a file in
      <span class="Pa">${LOCALBASE}/share/toolchains</span>. The file should be
      a make file which sets variables to request an external toolchain such as
      <var class="Va">XCC</var>.
    <p class="Pp">External toolchains are available in ports for both LLVM and
        GCC/binutils. For external toolchains available in ports,
        <var class="Va">CROSS_TOOLCHAIN</var> should be set to the name of the
        package. LLVM toolchain packages use the name llvm&lt;major version&gt;.
        GCC toolchains provide separate packages for each architecture and use
        the name ${MACHINE_ARCH}-gcc&lt;major version&gt;.</p>
  </dd>
  <dt id="INSTKERNNAME"><var class="Va">INSTKERNNAME</var></dt>
  <dd>If set, specify an alternative name to build and install for the various
      kernel make targets. Defaults to
      &#x201C;<code class="Li">kernel</code>&#x201D;.</dd>
  <dt id="KERNCONF"><var class="Va">KERNCONF</var></dt>
  <dd>Specify one or more space-separated kernels to build and install for the
      various kernel make targets. If multiple kernels are specified, the first
      listed kernel installs to <span class="Pa">/boot/${INSTKERNNAME}</span>,
      and subsequent kernels install to
      <span class="Pa">/boot/${INSTKERNNAME}.NAME</span>.
    <p class="Pp">If unset, it defaults to GENERIC, except on POWER
        architectures, where it defaults to GENERIC64 for powerpc64, and
        GENERIC64LE for powerpc64le.</p>
  </dd>
  <dt id="KERNBUILDDIR"><var class="Va">KERNBUILDDIR</var></dt>
  <dd>Overrides the default directory to get all the opt_*.h files for building
      a kernel module. Useful for stand-alone modules that depend on
      <a class="Xr">config(8)</a> options. Automatically set for modules built
      with a kernel.</dd>
  <dt id="KERNCONFDIR"><var class="Va">KERNCONFDIR</var></dt>
  <dd>Overrides the directory in which <var class="Va">KERNCONF</var> and any
      files included by <var class="Va">KERNCONF</var> should be found. Defaults
      to <span class="Pa">sys/${ARCH}/conf</span>.</dd>
  <dt id="KERNFAST"><var class="Va">KERNFAST</var></dt>
  <dd>If set, the build target <code class="Cm">buildkernel</code> defaults to
      setting <var class="Va">NO_KERNELCLEAN</var>,
      <var class="Va">NO_KERNELCONFIG</var>, and
      <var class="Va">NO_KERNELOBJ</var>. When set to a value other than
      <code class="Cm">1</code> then <var class="Va">KERNCONF</var> is set to
      the value of <var class="Va">KERNFAST</var>.</dd>
  <dt id="KODIR"><var class="Va">KODIR</var></dt>
  <dd>If set, this variable specifies an alternative directory to install the
      kernel.</dd>
  <dt id="LOCAL_DIRS"><var class="Va">LOCAL_DIRS</var></dt>
  <dd>If set, this variable supplies a list of additional directories relative
      to the root of the source tree to build as part of the
      <code class="Cm">everything</code> target. The directories are built in
      parallel with each other, and with the base system directories. Insert a
      <var class="Va">.WAIT</var> directive at the beginning of the
      <var class="Va">LOCAL_DIRS</var> list to ensure all base system
      directories are built first. <var class="Va">.WAIT</var> may also be used
      as needed elsewhere within the list.</dd>
  <dt id="LOCAL_ITOOLS"><var class="Va">LOCAL_ITOOLS</var></dt>
  <dd>If set, this variable supplies a list of additional tools that are used by
      the <code class="Cm">installworld</code> and
      <code class="Cm">distributeworld</code> targets.</dd>
  <dt id="LOCAL_LIB_DIRS"><var class="Va">LOCAL_LIB_DIRS</var></dt>
  <dd>If set, this variable supplies a list of additional directories relative
      to the root of the source tree to build as part of the
      <code class="Cm">libraries</code> target. The directories are built in
      parallel with each other, and with the base system libraries. Insert a
      <var class="Va">.WAIT</var> directive at the beginning of the
      <var class="Va">LOCAL_DIRS</var> list to ensure all base system libraries
      are built first. <var class="Va">.WAIT</var> may also be used as needed
      elsewhere within the list.</dd>
  <dt id="LOCAL_MTREE"><var class="Va">LOCAL_MTREE</var></dt>
  <dd>If set, this variable supplies a list of additional mtrees relative to the
      root of the source tree to use as part of the
      <code class="Cm">hierarchy</code> target.</dd>
  <dt id="LOCAL_LEGACY_DIRS"><var class="Va">LOCAL_LEGACY_DIRS</var></dt>
  <dd>If set, this variable supplies a list of additional directories relative
      to the root of the source tree to build as part of the
      <code class="Cm">legacy</code> target.</dd>
  <dt id="LOCAL_BSTOOL_DIRS"><var class="Va">LOCAL_BSTOOL_DIRS</var></dt>
  <dd>If set, this variable supplies a list of additional directories relative
      to the root of the source tree to build as part of the
      <code class="Cm">bootstrap-tools</code> target.</dd>
  <dt id="LOCAL_TOOL_DIRS"><var class="Va">LOCAL_TOOL_DIRS</var></dt>
  <dd>If set, this variable supplies a list of additional directories relative
      to the root of the source tree to build as part of the
      <code class="Cm">build-tools</code> target.</dd>
  <dt id="LOCAL_XTOOL_DIRS"><var class="Va">LOCAL_XTOOL_DIRS</var></dt>
  <dd>If set, this variable supplies a list of additional directories relative
      to the root of the source tree to build as part of the
      <code class="Cm">cross-tools</code> target.</dd>
  <dt id="OBJROOT"><var class="Va">OBJROOT</var></dt>
  <dd>The object directory root is defined as
      <span class="Pa">${OBJDIR}/${SRCDIR}/</span>. See
      <span class="Pa">share/mk/src.sys.obj.mk</span>.</dd>
  <dt id="PKG_FORMAT"><var class="Va">PKG_FORMAT</var></dt>
  <dd>Specify a package compression format when building
      <a class="Xr">freebsd-base(7)</a> packages. Default:
      &#x2018;<code class="Li">tzst</code>&#x2019;. Consider using
      &#x2018;<code class="Li">tar</code>&#x2019; to disable compression.
      Accepted options are documented in the <code class="Fl">-f</code>
      description of <a class="Xr">pkg-create(8)</a>.</dd>
  <dt id="PORTS_MODULES"><var class="Va">PORTS_MODULES</var></dt>
  <dd>A list of ports with kernel modules that should be built and installed as
      part of the <code class="Cm">buildkernel</code> and
      <code class="Cm">installkernel</code> process. This is currently
      incompatible with building <a class="Xr">freebsd-base(7)</a> packages.
      Each port must be specified as
      <var class="Ar">category</var><code class="Li">/</code><var class="Ar">port</var>[<code class="Li">@</code><var class="Ar">flavor</var>],
      e.g.
    <div class="Bd Pp Li">
    <pre>PORTS_MODULES=graphics/gpu-firmware-intel-kmod@kabylake
PORTS_MODULES+=graphics/drm-66-kmod</pre>
    </div>
  </dd>
  <dt id="LOCAL_MODULES"><var class="Va">LOCAL_MODULES</var></dt>
  <dd>A list of external kernel modules that should be built and installed as
      part of the <code class="Cm">buildkernel</code> and
      <code class="Cm">installkernel</code> process. Defaults to the list of
      sub-directories of <var class="Va">LOCAL_MODULES_DIR</var>.</dd>
  <dt id="LOCAL_MODULES_DIR"><var class="Va">LOCAL_MODULES_DIR</var></dt>
  <dd>The directory in which to search for the kernel modules specified by
      <var class="Va">LOCAL_MODULES</var>. Each kernel module should consist of
      a directory containing a makefile. Defaults to
      <span class="Pa">${LOCALBASE}/sys/modules</span>.</dd>
  <dt id="SRCCONF"><var class="Va">SRCCONF</var></dt>
  <dd>Specify a file to override the default
      <span class="Pa">/etc/src.conf</span>. The src.conf file controls the
      components to build. See <a class="Xr">src.conf(5)</a></dd>
  <dt id="REPODIR"><var class="Va">REPODIR</var></dt>
  <dd>The root directory used to create the package repository for building
      <a class="Xr">packages(7)</a>. Defaults to
      <span class="Pa">${OBJROOT}/repo/</span>. This can also be set in
      <a class="Xr">src-env.conf(5)</a>.</dd>
  <dt id="STRIPBIN"><var class="Va">STRIPBIN</var></dt>
  <dd>Command to use at install time when stripping binaries. Be sure to add any
      additional tools required to run <var class="Va">STRIPBIN</var> to the
      <var class="Va">LOCAL_ITOOLS</var> <a class="Xr">make(1)</a> variable
      before running the <code class="Cm">distributeworld</code> or
      <code class="Cm">installworld</code> targets. See
      <a class="Xr">install(1)</a> for more details.</dd>
  <dt id="SUBDIR_OVERRIDE"><var class="Va">SUBDIR_OVERRIDE</var></dt>
  <dd>Override the default list of sub-directories and only build the
      sub-directory named in this variable. If combined with
      <code class="Cm">buildworld</code> then all libraries and includes, and
      some of the build tools will still build as well. Specifying
      <code class="Cm">-DNO_LIBS</code>, and <code class="Cm">-DWORLDFAST</code>
      will only build the specified directory as was done historically. When
      combined with <code class="Cm">buildworld</code> it is necessary to
      override <var class="Va">LOCAL_LIB_DIRS</var> with any custom directories
      containing libraries. This allows building a subset of the system in the
      same way as <code class="Cm">buildworld</code> does using its sysroot
      handling. This variable can also be useful when debugging failed builds.
    <div class="Bd Pp Bd-indent Li">
    <pre>make some-target SUBDIR_OVERRIDE=foo/bar</pre>
    </div>
  </dd>
  <dt id="SYSDIR"><var class="Va">SYSDIR</var></dt>
  <dd>Specify the location of the kernel source to override the default
      <span class="Pa">/usr/src/sys</span>. The kernel source is located in the
      <span class="Pa">sys</span> subdirectory of the source tree checked out
      from the <span class="Pa">src.git</span> repository.</dd>
  <dt id="TARGET"><var class="Va">TARGET</var></dt>
  <dd>The target hardware platform. This is analogous to the
      &#x201C;<code class="Nm">uname</code> <code class="Fl">-m</code>&#x201D;
      output. This is necessary to cross-build some target architectures. For
      example, cross-building for ARM64 machines requires
      <var class="Va">TARGET_ARCH</var>=<code class="Li">aarch64</code> and
      <var class="Va">TARGET</var>=<code class="Li">arm64</code>. If not set,
      <var class="Va">TARGET</var> defaults to the current hardware platform,
      unless <var class="Va">TARGET_ARCH</var> is also set, in which case it
      defaults to the appropriate value for that architecture.</dd>
  <dt id="TARGET_ARCH"><var class="Va">TARGET_ARCH</var></dt>
  <dd>The target machine processor architecture. This is analogous to the
      &#x201C;<code class="Nm">uname</code> <code class="Fl">-p</code>&#x201D;
      output. Set this to cross-build for a different architecture. If not set,
      <var class="Va">TARGET_ARCH</var> defaults to the current machine
      architecture, unless <var class="Va">TARGET</var> is also set, in which
      case it defaults to the appropriate value for that platform. Typically,
      one only needs to set <var class="Va">TARGET</var>.</dd>
</dl>
<p class="Pp">Builds under directory <span class="Pa">/usr/src</span> are also
    influenced by defining one or more of the following symbols, using the
    <code class="Fl">-D</code> option of <a class="Xr">make(1)</a>:</p>
<dl class="Bl-tag">
  <dt id="LOADER_DEFAULT_INTERP"><var class="Va">LOADER_DEFAULT_INTERP</var></dt>
  <dd>Defines what interpreter the default loader program will have. Valid
      values include &#x201C;4th&#x201D;, &#x201C;lua&#x201D;, and
      &#x201C;simp&#x201D;. This creates the default link for
      <span class="Pa">/boot/loader</span> to the loader with that interpreter.
      It also determines what interpreter is compiled into
      <span class="Pa">userboot</span>.</dd>
  <dt id="NO_CLEANDIR"><var class="Va">NO_CLEANDIR</var></dt>
  <dd>If set, the build targets that clean parts of the object tree use the
      equivalent of &#x201C;make clean&#x201D; instead of &#x201C;make
      cleandir&#x201D;.</dd>
  <dt id="NO_CLEAN"><var class="Va">NO_CLEAN</var></dt>
  <dd>If set, no object tree files are cleaned at all. This is the default when
      <var class="Va">WITH_META_MODE</var> is used with
      <a class="Xr">filemon(4)</a> loaded. See <a class="Xr">src.conf(5)</a> for
      more details. Setting <var class="Va">NO_CLEAN</var> implies
      <var class="Va">NO_KERNELCLEAN</var>, so when
      <var class="Va">NO_CLEAN</var> is set no kernel objects are cleaned
      either.</dd>
  <dt id="NO_CTF"><var class="Va">NO_CTF</var></dt>
  <dd>If set, the build process does not run the DTrace CTF conversion tools on
      built objects.</dd>
  <dt id="NO_SHARE"><var class="Va">NO_SHARE</var></dt>
  <dd>If set, the build does not descend into the
      <span class="Pa">/usr/src/share</span> subdirectory (i.e., manual pages,
      locale data files, timezone data files and other
      <span class="Pa">/usr/src/share</span> files will not be rebuild from
      their sources).</dd>
  <dt id="NO_KERNELCLEAN"><var class="Va">NO_KERNELCLEAN</var></dt>
  <dd>If set, the build process does not run &#x201C;make clean&#x201D; as part
      of the <code class="Cm">buildkernel</code> target.</dd>
  <dt id="NO_KERNELCONFIG"><var class="Va">NO_KERNELCONFIG</var></dt>
  <dd>If set, the build process does not run <a class="Xr">config(8)</a> as part
      of the <code class="Cm">buildkernel</code> target.</dd>
  <dt id="NO_KERNELOBJ"><var class="Va">NO_KERNELOBJ</var></dt>
  <dd>If set, the build process does not run &#x201C;make obj&#x201D; as part of
      the <code class="Cm">buildkernel</code> target.</dd>
  <dt id="NO_LIBS"><var class="Va">NO_LIBS</var></dt>
  <dd>If set, the libraries phase will be skipped.</dd>
  <dt id="NO_OBJWALK"><var class="Va">NO_OBJWALK</var></dt>
  <dd>If set, no object directories will be created. This should only be used if
      object directories were created in a previous build and no new directories
      are connected.</dd>
  <dt id="UNIVERSE_TOOLCHAIN"><var class="Va">UNIVERSE_TOOLCHAIN</var></dt>
  <dd>Requests use of the toolchain built as part of the
      <code class="Cm">universe</code> target as an external toolchain.</dd>
  <dt id="WORLDFAST"><var class="Va">WORLDFAST</var></dt>
  <dd>If set, the build target <code class="Cm">buildworld</code> defaults to
      setting <var class="Va">NO_CLEAN</var>, <var class="Va">NO_OBJWALK</var>,
      and will skip most bootstrap phases. It will only bootstrap libraries and
      build all of userland. This option should be used only when it is known
      that none of the bootstrap needs changed and that no new directories have
      been connected to the build.</dd>
</dl>
<p class="Pp">Builds under directory <span class="Pa">/usr/doc</span> are
    influenced by the following <a class="Xr">make(1)</a> variables:</p>
<dl class="Bl-tag">
  <dt id="DOC_LANG"><var class="Va">DOC_LANG</var></dt>
  <dd>If set, restricts the documentation build to the language subdirectories
      specified as its content. The default action is to build documentation for
      all languages.</dd>
</dl>
<p class="Pp">Builds using the <code class="Cm">universe</code> and related
    targets are influenced by the following <a class="Xr">make(1)</a>
  variables:</p>
<dl class="Bl-tag">
  <dt id="JFLAG"><var class="Va">JFLAG</var></dt>
  <dd>Pass the value of this variable to each <a class="Xr">make(1)</a>
      invocation used to build worlds and kernels. This can be used to enable
      multiple jobs within a single architecture's build while still building
      each architecture serially.</dd>
  <dt id="MAKE_JUST_KERNELS"><var class="Va">MAKE_JUST_KERNELS</var></dt>
  <dd>Only build kernels for each supported architecture.</dd>
  <dt id="MAKE_JUST_WORLDS"><var class="Va">MAKE_JUST_WORLDS</var></dt>
  <dd>Only build worlds for each supported architecture.</dd>
  <dt id="WITHOUT_WORLDS"><var class="Va">WITHOUT_WORLDS</var></dt>
  <dd>Only build kernels for each supported architecture.</dd>
  <dt id="WITHOUT_KERNELS"><var class="Va">WITHOUT_KERNELS</var></dt>
  <dd>Only build worlds for each supported architecture.</dd>
  <dt id="UNIVERSE_TARGET"><var class="Va">UNIVERSE_TARGET</var></dt>
  <dd>Execute the specified <a class="Xr">make(1)</a> target for each supported
      architecture instead of the default action of building a world and one or
      more kernels. This variable implies
    <var class="Va">WITHOUT_KERNELS</var>.</dd>
  <dt id="USE_GCC_TOOLCHAINS"><var class="Va">USE_GCC_TOOLCHAINS</var></dt>
  <dd>Use external GCC toolchains to build the requested targets. If the
      required toolchain package for a supported architecture is not installed,
      the build for that architecture is skipped.
    <p class="Pp">A specific version of GCC can be used by setting the value of
        this variable to the desired version (for example,
        &#x201C;gcc14&#x201D;); otherwise a default version of GCC is used.</p>
  </dd>
  <dt id="TARGETS"><var class="Va">TARGETS</var></dt>
  <dd>Only build the listed targets instead of each supported architecture.</dd>
  <dt id="EXTRA_TARGETS"><var class="Va">EXTRA_TARGETS</var></dt>
  <dd>In addition to the supported architectures, build the semi-supported
      architectures. A semi-supported architecture has build support in the
      <span class="Ux">FreeBSD</span> tree, but receives significantly less
      testing and is generally for fringe uses that do not have a wide
    appeal.</dd>
</dl>
</section>
<section class="Sh">
<h1 class="Sh" id="FILES"><a class="permalink" href="#FILES">FILES</a></h1>
<dl class="Bl-tag Bl-compact">
  <dt><span class="Pa">/usr/doc/Makefile</span></dt>
  <dd style="width: auto;">&#x00A0;</dd>
  <dt><span class="Pa">/usr/doc/share/mk/doc.project.mk</span></dt>
  <dd style="width: auto;">&#x00A0;</dd>
  <dt><span class="Pa">/usr/ports/Mk/bsd.port.mk</span></dt>
  <dd style="width: auto;">&#x00A0;</dd>
  <dt><span class="Pa">/usr/ports/Mk/bsd.sites.mk</span></dt>
  <dd style="width: auto;">&#x00A0;</dd>
  <dt><span class="Pa">/usr/src/Makefile</span></dt>
  <dd style="width: auto;">&#x00A0;</dd>
  <dt><span class="Pa">/usr/src/Makefile.inc1</span></dt>
  <dd><a class="Xr">make(1)</a> infrastructure for each tree</dd>
  <dt><span class="Pa">/usr/ports/UPDATING</span></dt>
  <dd style="width: auto;">&#x00A0;</dd>
  <dt><span class="Pa">/usr/src/UPDATING</span></dt>
  <dd>notable changes in each tree</dd>
  <dt><span class="Pa">/usr/share/examples/etc/make.conf</span></dt>
  <dd>example <a class="Xr">make.conf(5)</a></dd>
  <dt><span class="Pa">/etc/src.conf</span></dt>
  <dd>src build configuration, see <a class="Xr">src.conf(5)</a></dd>
</dl>
</section>
<section class="Sh">
<h1 class="Sh" id="EXAMPLES"><a class="permalink" href="#EXAMPLES">EXAMPLES</a></h1>
<p class="Pp">This section describes best practices for common situations. When
    manual intervention is necessary, it will be mentioned in
    <span class="Pa">UPDATING</span>. Make sure you have full backups before
    proceeding!</p>
<section class="Ss">
<h2 class="Ss" id="Example_1:_Build_and_upgrade_system_in_place"><a class="permalink" href="#Example_1:_Build_and_upgrade_system_in_place">Example
  1: Build and upgrade system in place</a></h2>
<p class="Pp">If using installed drivers such as graphics or virtual machine
    guest drivers, check out the <a class="Xr">ports(7)</a> tree, and specify
    the drivers in <a class="Xr">src.conf(5)</a> so they are built and installed
    automatically after the kernel:</p>
<div class="Bd Pp Bd-indent Li">
<pre>git clone https://git.FreeBSD.org/ports.git /usr/ports
cat &lt;&lt; EOF &gt;&gt; /etc/src.conf
PORTS_MODULES+=graphics/drm-kmod emulators/virtualbox-ose-kmod
EOF</pre>
</div>
<p class="Pp">Check out the CURRENT branch, build it, and install, overwriting
    the current system:</p>
<div class="Bd Pp Bd-indent Li">
<pre>git clone https://git.FreeBSD.org/src.git /usr/src
cd /usr/src
make buildworld buildkernel
make installkernel
shutdown -r now</pre>
</div>
<p class="Pp">For major version upgrades, boot into single-user mode. After
    restarting, install userspace, and merge configurations. After verifying
    that you do not need them, delete old files:</p>
<div class="Bd Pp Bd-indent Li">
<pre>cd /usr/src
etcupdate -p
make installworld
etcupdate -B
make delete-old
shutdown -r now</pre>
</div>
<p class="Pp">After testing the new system and verifying that your applications
    do not depend on them, delete the old libraries:</p>
<p class="Pp"></p>
<div class="Bd Bd-indent"><code class="Li">make delete-old-libs</code></div>
</section>
<section class="Ss">
<h2 class="Ss" id="Example_2:_Build_and_upgrade_a_custom_kernel"><a class="permalink" href="#Example_2:_Build_and_upgrade_a_custom_kernel">Example
  2: Build and upgrade a custom kernel</a></h2>
<p class="Pp">Create a custom kernel configuration,
    <var class="Va">MYKERNEL</var>, by including an existing configuration and
    using <code class="Cm">device</code>/<code class="Cm">nodevice</code> and
    <code class="Cm">options</code>/<code class="Cm">nooption</code> to select
    and configure components:</p>
<div class="Bd Pp Bd-indent Li">
<pre>cd /usr/src
cat &lt;&lt; EOF &gt; sys/amd64/conf/MYKERNEL
include GENERIC
ident MYKERNEL
nodevice sound
EOF</pre>
</div>
<p class="Pp">After creating the new kernel configuration, build a fresh
    toolchain, build the kernel, and install it directly, moving the old kernel
    to <span class="Pa">/boot/kernel.old/</span>:</p>
<div class="Bd Pp Bd-indent Li">
<pre>make kernel-toolchain
make -DALWAYS_CHECK_MAKE buildkernel KERNCONF=MYKERNEL
make -DALWAYS_CHECK_MAKE installkernel KERNCONF=MYKERNEL
shutdown -r now</pre>
</div>
<p class="Pp">To package the kernel into a <a class="Xr">freebsd-base(7)</a>
    package instead of installing it directly, use
    <code class="Cm">update-packages</code> instead of
    <code class="Cm">installkernel</code>:</p>
<div class="Bd Pp Bd-indent Li">
<pre>make buildworld buildkernel KERNCONF=MYKERNEL
make update-packages KERNCONF=MYKERNEL</pre>
</div>
<p class="Pp">To install the kernel directly to an alternate location, use the
    <var class="Va">INSTKERNNAME</var> variable and boot it once to test via
    <a class="Xr">nextboot(8)</a>:</p>
<div class="Bd Pp Bd-indent Li">
<pre>make installkernel KERNCONF=MYKERNEL INSTKERNNAME=testkernel
nextboot -k testkernel
shutdown -r now</pre>
</div>
</section>
<section class="Ss">
<h2 class="Ss" id="Example_3:_Build_and_upgrade_a_single_piece_of_userspace"><a class="permalink" href="#Example_3:_Build_and_upgrade_a_single_piece_of_userspace">Example
  3: Build and upgrade a single piece of userspace</a></h2>
<p class="Pp">Rebuild and reinstall a single piece of userspace, in this case
    <a class="Xr">ls(1)</a>:</p>
<div class="Bd Pp Bd-indent Li">
<pre>cd /usr/src/bin/ls
make clean all
make install</pre>
</div>
</section>
<section class="Ss">
<h2 class="Ss" id="Example_4:_Build_and_upgrade_a_loadable_kernel_module"><a class="permalink" href="#Example_4:_Build_and_upgrade_a_loadable_kernel_module">Example
  4: Build and upgrade a loadable kernel module</a></h2>
<p class="Pp">Rebuild and reinstall a single loadable kernel module, in this
    case <a class="Xr">sound(4)</a>:</p>
<div class="Bd Pp Bd-indent Li">
<pre>cd /usr/src/sys/modules/sound
make all install clean cleandepend KMODDIR=/boot/kernel</pre>
</div>
</section>
<section class="Ss">
<h2 class="Ss" id="Example_5:_Quickly_rebuild_a_kernel_in_place"><a class="permalink" href="#Example_5:_Quickly_rebuild_a_kernel_in_place">Example
  5: Quickly rebuild a kernel in place</a></h2>
<p class="Pp">Quickly rebuild and reinstall the kernel, only recompiling the
    files changed since last build; note that this will only work if the full
    kernel build has been completed in the past, not on a fresh source tree:</p>
<div class="Bd Pp Bd-indent Li">
<pre>cd /usr/src
make kernel KERNFAST=1</pre>
</div>
</section>
<section class="Ss">
<h2 class="Ss" id="Example_6:_Cross-compiling_for_different_architectures"><a class="permalink" href="#Example_6:_Cross-compiling_for_different_architectures">Example
  6: Cross-compiling for different architectures</a></h2>
<p class="Pp">To rebuild parts of <span class="Ux">FreeBSD</span> for another
    CPU architecture, first prepare your source tree by building the
    cross-toolchain:</p>
<div class="Bd Pp Bd-indent Li">
<pre>cd src
make toolchain TARGET_ARCH=aarch64</pre>
</div>
<p class="Pp">The following sequence of commands can be used to cross-build the
    system for the arm64 (aarch64) architecture on a different host
    architecture, such as amd64:</p>
<div class="Bd Pp Bd-indent Li">
<pre>cd /usr/src
make TARGET_ARCH=aarch64 buildworld buildkernel
make TARGET_ARCH=aarch64 DESTDIR=/client installworld installkernel</pre>
</div>
<p class="Pp">Afterwards, to build and install a single piece of userspace,
  use:</p>
<div class="Bd Pp Bd-indent Li">
<pre>cd src/bin/ls
make buildenv TARGET_ARCH=aarch64
make clean all install DESTDIR=/client</pre>
</div>
<p class="Pp">Likewise, to quickly rebuild and reinstall the kernel, use:</p>
<div class="Bd Pp Bd-indent Li">
<pre>cd src
make buildenv TARGET_ARCH=aarch64
make kernel KERNFAST=1 DESTDIR=/client</pre>
</div>
</section>
</section>
<section class="Sh">
<h1 class="Sh" id="DIAGNOSTICS"><a class="permalink" href="#DIAGNOSTICS">DIAGNOSTICS</a></h1>
<dl class="Bl-diag">
  <dt>Bad system call (core dumped)</dt>
  <dd></dd>
  <dt>rescue/sh check failed, installation aborted</dt>
  <dd>
    <p class="Pp">The kernel was not updated due to incorrect build procedure.
        Study the examples above.</p>
  </dd>
</dl>
</section>
<section class="Sh">
<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
  ALSO</a></h1>
<p class="Pp"><a class="Xr">cc(1)</a>, <a class="Xr">install(1)</a>,
    <a class="Xr">make(1)</a>, <a class="Xr">make.conf(5)</a>,
    <a class="Xr">src.conf(5)</a>, <a class="Xr">arch(7)</a>,
    <a class="Xr">development(7)</a>, <a class="Xr">freebsd-base(7)</a>,
    <a class="Xr">pkg(7)</a>, <a class="Xr">ports(7)</a>,
    <a class="Xr">release(7)</a>, <a class="Xr">tests(7)</a>,
    <a class="Xr">config(8)</a>, <a class="Xr">etcupdate(8)</a>,
    <a class="Xr">nextboot(8)</a>, <a class="Xr">shutdown(8)</a></p>
</section>
<section class="Sh">
<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1>
<p class="Pp">The <code class="Nm">build</code> manpage first appeared in
    <span class="Ux">FreeBSD 4.3</span>.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1>
<p class="Pp"><span class="An">Mike W. Meyer</span>
    &lt;<a class="Mt" href="mailto:mwm@mired.org">mwm@mired.org</a>&gt;</p>
</section>
<section class="Sh">
<h1 class="Sh" id="CAVEATS"><a class="permalink" href="#CAVEATS">CAVEATS</a></h1>
<p class="Pp">Old objects can cause obscure build problems; try
    &#x2018;<code class="Li">make cleandir cleandir</code>&#x2019;.</p>
<p class="Pp">Environment poisoning can cause obscure build problems; try
    prefixing <a class="Xr">make(1)</a> commands with
    &#x2018;<code class="Li">env -i</code>&#x2019;</p>
<p class="Pp">When doing a major release upgrade, booting into single user mode
    for <code class="Cm">installworld</code> is required.</p>
<p class="Pp">Updating the boot <a class="Xr">loader(8)</a> is architecture
    specific. Consult <a class="Xr">boot(8)</a> for your architecture for more
    details.</p>
</section>
</div>
<table class="foot">
  <tr>
    <td class="foot-date">April 22, 2026</td>
    <td class="foot-os">FreeBSD 15.0</td>
  </tr>
</table>