svn commit: r50251 - head/en_US.ISO8859-1/books/handbook/cutting-edge
Warren Block
wblock at FreeBSD.org
Fri May 12 17:30:57 UTC 2017
Author: wblock
Date: Fri May 12 17:30:55 2017
New Revision: 50251
URL: https://svnweb.freebsd.org/changeset/doc/50251
Log:
Rewrite the Build from Source section, simplifying and clarifying.
Differential Revision: https://reviews.freebsd.org/D7665
Modified:
head/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml
Modified: head/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml Thu May 11 11:59:31 2017 (r50250)
+++ head/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml Fri May 12 17:30:55 2017 (r50251)
@@ -1067,1044 +1067,445 @@ before running "/usr/sbin/freebsd-update
</listitem>
</orderedlist>
</sect2>
-
- <sect2 xml:id="stable">
- <title>Using &os.stable;</title>
-
- <para>&os.stable; is the development branch from which major
- releases are made. Changes go into this branch at a slower
- pace and with the general assumption that they have first been
- tested in &os.current;. This is <emphasis>still</emphasis> a
- development branch and, at any given time, the sources for
- &os.stable; may or may not be suitable for general use. It is
- simply another engineering development track, not a resource
- for end-users. Users who do not have the resources to perform
- testing should instead run the most recent release of
- &os;.</para>
-
- <para>Those interested in tracking or contributing to the &os;
- development process, especially as it relates to the next
- release of &os;, should consider following &os.stable;.</para>
-
- <para>While the &os.stable; branch should compile and run at all
- times, this cannot be guaranteed. Since more people run
- &os.stable; than &os.current;, it is inevitable that bugs and
- corner cases will sometimes be found in &os.stable; that were
- not apparent in &os.current;. For this reason, one should not
- blindly track &os.stable;. It is particularly important
- <emphasis>not</emphasis> to update any production servers to
- &os.stable; without thoroughly testing the code in a
- development or testing environment.</para>
-
- <para>To track &os.stable;:</para>
-
- <indexterm>
- <primary>-STABLE</primary>
- <secondary>using</secondary>
- </indexterm>
- <orderedlist>
- <listitem>
- <para>Join the &a.stable.name; list in order to stay
- informed of build dependencies that may appear in
- &os.stable; or any other issues requiring special
- attention. Developers will also make announcements in
- this mailing list when they are contemplating some
- controversial fix or update, giving the users a chance to
- respond if they have any issues to raise concerning the
- proposed change.</para>
-
- <para>Join the relevant <application>svn</application> list
- for the branch being tracked. For example, users
- tracking the 9-STABLE branch should join the
- &a.svn-src-stable-9.name; list. This list records the
- commit log entry for each change as it is made, along
- with any pertinent information on possible
- side effects.</para>
-
- <para>To join these lists, go to &a.mailman.lists.link;,
- click on the list to subscribe to, and follow the
- instructions. In order to track changes for the whole
- source tree, subscribe to &a.svn-src-all.name;.</para>
- </listitem>
-
- <listitem>
- <para>To install a new &os.stable; system, install the most
- recent &os.stable; release from the <link
- linkend="mirrors">&os; mirror sites</link> or use a
- monthly snapshot built from &os.stable;. Refer to <link
- xlink:href="&url.base;/snapshots/">www.freebsd.org/snapshots</link>
- for more information about snapshots.</para>
-
- <para>To compile or upgrade to an existing &os; system to
- &os.stable;, use <link linkend="svn">svn</link>
- <indexterm>
- <primary>Subversion</primary>
- </indexterm> to check out the source for the desired
- branch. Branch names, such as
- <literal>stable/9</literal>, are listed at <link
- xlink:href="&url.base;/releng/">www.freebsd.org/releng</link>.</para>
- </listitem>
-
- <listitem>
- <para>Before compiling or upgrading to &os.stable;
- <indexterm>
- <primary>-STABLE</primary>
- <secondary>compiling</secondary>
- </indexterm>, read <filename>/usr/src/Makefile</filename>
- carefully and follow the instructions in <xref
- linkend="makeworld"/>. Read &a.stable; and
- <filename>/usr/src/UPDATING</filename> to keep up-to-date
- on other bootstrapping procedures that sometimes become
- necessary on the road to the next release.</para>
- </listitem>
- </orderedlist>
- </sect2>
</sect1>
- <sect1 xml:id="synching">
- <title>Synchronizing Source</title>
+ <sect1 xml:id="updating-src">
+ <title>Updating &os; from Source</title>
- <para>There are various methods for staying up-to-date with the
- &os; sources. This section describes the primary service,
- <application>Subversion</application>.</para>
-
- <warning>
- <para>While it is possible to update only parts of the source
- tree, the only supported update procedure is to update the
- entire tree and recompile all the programs that run in user
- space, such as those in <filename>/bin</filename> and
- <filename>/sbin</filename>, and kernel sources. Updating only
- part of the source tree, only the kernel, or only the userland
- programs will often result in problems ranging from compile
- errors to kernel panics or data corruption.</para>
- </warning>
-
- <indexterm>
- <primary>Subversion</primary>
- </indexterm>
-
- <para><application>Subversion</application> uses the
- <emphasis>pull</emphasis> model of updating sources. The user,
- or a <command>cron</command> script, invokes the
- <command>svn</command> program which updates the local version
- of the source. <application>Subversion</application> is the
- preferred method for updating local source trees as updates are
- up-to-the-minute and the user controls when updates are
- downloaded. It is easy to restrict updates to specific files or
- directories and the requested updates are generated on the fly
- by the server. How to synchronize source using
- <application>Subversion</application> is described in <xref
- linkend="svn"/>.</para>
-
- <para>If a user inadvertently wipes out portions of the local
- archive, <application>Subversion</application> will detect and
- rebuild the damaged portions during an update.</para>
- </sect1>
-
- <sect1 xml:id="makeworld">
- <title>Rebuilding World</title>
-
- <indexterm>
- <primary>Rebuilding <quote>world</quote></primary>
- </indexterm>
- <para>Once the local source tree is synchronized against a
- particular version of &os; such as &os.stable; or &os.current;,
- the source tree can be used to rebuild the system. This process
- is known as rebuilding world.</para>
-
- <para><emphasis>Before</emphasis> rebuilding world, be sure to
- perform the following tasks:</para>
-
- <procedure>
- <title>Perform These Tasks <emphasis>Before</emphasis>
- Building World</title>
-
- <step>
- <para>Backup all important data to another system or removable
- media, verify the integrity of the backup, and have a
- bootable installation media at hand. It cannot be stressed
- enough how important it is to make a backup of the system
- <emphasis>before</emphasis> rebuilding the system. While
- rebuilding world is an easy task, there will inevitably be
- times when mistakes in the source tree render the system
- unbootable. You will probably never have to use the backup,
- but it is better to be safe than sorry!</para>
- </step>
-
- <step>
- <indexterm><primary>mailing list</primary></indexterm>
- <para>Review the recent &a.stable.name; or &a.current.name;
- entries, depending upon the branch being tracked. Be aware
- of any known problems and which systems are affected. If a
- known issue affects the version of synchronized code, wait
- for an <quote>all clear</quote> announcement to be posted
- stating that the problem has been solved. Resynchronize the
- sources to ensure that the local version of source has the
- needed fix.</para>
- </step>
-
- <step>
- <para>Read <filename>/usr/src/UPDATING</filename> for any
- extra steps necessary for that version of the source. This
- file contains important information about potential problems
- and may specify the order to run certain commands. Many
- upgrades require specific additional steps such as renaming
- or deleting specific files prior to installing the new
- world. These will be listed at the end of this file where
- the currently recommended upgrade sequence is explicitly
- spelled out. If <filename>UPDATING</filename> contradicts
- any steps in this chapter, the instructions in
- <filename>UPDATING</filename> take precedence and should be
- followed.</para>
- </step>
- </procedure>
-
- <warning>
- <title>Do Not Use <command>make world</command></title>
-
- <para>Some older documentation recommends using <command>make
- world</command>. However, that command skips some important
- steps and should only be used by experts. For almost all
- circumstances <command>make world</command> is the wrong thing
- to do, and the procedure described here should be used
- instead.</para>
- </warning>
-
- <sect2 xml:id="canonical-build">
- <title>Overview of Process</title>
-
- <para>The build world process assumes an upgrade from an older
- &os; version using the source of a newer version that was
- obtained using the instructions in <xref
- linkend="synching"/>.</para>
-
- <para>In &os;, the term <quote>world</quote> includes the
- kernel, core system binaries, libraries, programming files,
- and built-in compiler. The order in which these components
- are built and installed is important.</para>
-
- <para>For example, the old compiler might have a bug and not be
- able to compile the new kernel. Since the new kernel should
- be built with the new compiler, the new compiler must be
- built, but not necessarily installed, before the new kernel is
- built.</para>
-
- <para>The new world might rely on new kernel features, so the
- new kernel must be installed before the new world is
- installed. The old world might not run correctly on the new
- kernel, so the new world must be installed immediately upon
- installing the new kernel.</para>
-
- <para>Some configuration changes must be made before the new
- world is installed, but others might break the old world.
- Hence, two different configuration upgrade steps are used.
- For the most part, the update process only replaces or adds
- files and existing old files are not deleted. Since this can
- cause problems, <filename>/usr/src/UPDATING</filename> will
- indicate if any files need to be manually deleted and at which
- step to do so.</para>
-
- <para>These concerns have led to the recommended upgrade
- sequence described in the following procedure.</para>
-
- <note>
- <para>It is a good idea to save the output from running
- <command>make</command> to a file. If something goes wrong,
- a copy of the error message can be posted to one of the &os;
- mailing lists.</para>
-
- <para>The easiest way to do this is to use
- <command>script</command> with a parameter that specifies
- the name of the file to save all output to. Do not save the
- output to <filename>/tmp</filename> as this directory may be
- cleared at next reboot. A better place to save the file is
- <filename>/var/tmp</filename>. Run this command immediately
- before rebuilding the world, and then type
- <userinput>exit</userinput> when the process has
- finished:</para>
-
- <screen>&prompt.root; <userinput>script <replaceable>/var/tmp/mw.out</replaceable></userinput>
-Script started, output file is /var/tmp/mw.out</screen>
- </note>
+ <para>Updating &os; by compiling from source offers several
+ advantages over binary updates. Code can be built with options
+ to take advantage of specific hardware. Parts of the base
+ system can be built with non-default settings, or left out
+ entirely where they are not needed or desired. The build
+ process takes longer to update a system than binary updates, but
+ allows complete customization to produce a tailored version of
+ &os;.</para>
+
+ <sect2 xml:id="updating-src-quick-start">
+ <title>Quick Start</title>
+
+ <para>This is a quick reference for the typical steps used to
+ update &os; by building from source. Later sections describe
+ the process in more detail.</para>
<procedure>
- <title>Overview of Build World Process</title>
+ <step xml:id="updating-src-quick-start-preparing">
+ <title>Preparing</title>
- <para>The commands used in the build world process should be
- run in the order specified here. This section summarizes
- the function of each command.</para>
+ <para>The very first time a computer is updated from source,
+ run</para>
- <step>
- <para>If the build world process has previously been run on
- this system, a copy of the previous build may still exist
- in <filename>/usr/obj</filename>. To
- speed up the new build world process, and possibly save
- some dependency headaches, remove this directory if it
- already exists:</para>
-
- <screen>&prompt.root; <userinput>chflags -R noschg /usr/obj/*</userinput>
-&prompt.root; <userinput>rm -rf /usr/obj</userinput></screen>
- </step>
-
- <step>
- <para>Compile the new compiler and a few related tools, then
- use the new compiler to compile the rest of the new world.
- The result is saved to <filename
- >/usr/obj</filename>.</para>
-
- <screen>&prompt.root; <userinput>cd /usr/src</userinput>
-&prompt.root; <userinput>make buildworld</userinput></screen>
- </step>
-
- <step>
- <para>Use the new compiler residing in <filename
- >/usr/obj</filename> to build the new
- kernel, in order to protect against compiler-kernel
- mismatches. This is necessary, as certain memory
- structures may have changed, and programs like
- <command>ps</command> and <command>top</command> will fail
- to work if the kernel and source code versions are not the
- same.</para>
-
- <screen>&prompt.root; <userinput>make buildkernel</userinput></screen>
- </step>
-
- <step>
- <para>Install the new kernel and kernel modules, making it
- possible to boot with the newly updated kernel. If
- <varname>kern.securelevel</varname> has been raised above
- <literal>1</literal> <emphasis>and</emphasis>
- <literal>noschg</literal> or similar flags have been set
- on the kernel binary, drop the system into single-user
- mode first. Otherwise, this command can be run from
- multi-user mode without problems. See &man.init.8; for
- details about <varname>kern.securelevel</varname> and
- &man.chflags.1; for details about the various file
- flags.</para>
-
- <screen>&prompt.root; <userinput>make installkernel</userinput></screen>
- </step>
-
- <step>
- <para>Drop the system into single-user mode in order to
- minimize problems from updating any binaries that are
- already running. It also minimizes any problems from
- running the old world on a new kernel.</para>
-
- <screen>&prompt.root; <userinput>shutdown now</userinput></screen>
-
- <para>Once in single-user mode, run these commands if the
- system is formatted with UFS:</para>
-
- <screen>&prompt.root; <userinput>mount -u /</userinput>
-&prompt.root; <userinput>mount -a -t ufs</userinput>
-&prompt.root; <userinput>swapon -a</userinput></screen>
-
- <para>If the system is instead formatted with ZFS, run these
- two commands. This example assumes a zpool name of
- <literal>zroot</literal>:</para>
-
- <screen>&prompt.root; <userinput>zfs set readonly=off zroot</userinput>
-&prompt.root; <userinput>zfs mount -a</userinput></screen>
- </step>
-
- <step>
- <para>Optional: If a keyboard mapping other than the default
- US English is desired, it can be changed with
- &man.kbdmap.1;:</para>
+ <screen>&prompt.root; <userinput>etcupdate extract</userinput></screen>
- <screen>&prompt.root; <userinput>kbdmap</userinput></screen>
+ <para>This creates a checkpoint for later comparison and
+ merging of system settings.</para>
+
+ <para><emphasis>This step is only done once on a particular
+ computer.</emphasis> &man.etcupdate.8; does not need any
+ additional updates after the first
+ <emphasis>extract</emphasis>.</para>
+ </step>
+
+ <step>
+ <title>Update and Build</title>
+
+ <screen>&prompt.root; <userinput>svn update /usr/src</userinput> <co xml:id="updating-src-qs-svnup"/>
+<emphasis>check <filename>/usr/src/UPDATING</filename></emphasis> <co xml:id="updating-src-qs-review-updating"/>
+&prompt.root; <userinput>cd /usr/src</userinput> <co xml:id="updating-src-qs-cd"/>
+&prompt.root; <userinput>make -j<replaceable>4</replaceable> buildworld</userinput> <co xml:id="updating-src-qs-buildworld"/>
+&prompt.root; <userinput>make -j<replaceable>4</replaceable> kernel</userinput> <co xml:id="updating-src-qs-kernel"/>
+&prompt.root; <userinput>make installworld</userinput> <co xml:id="updating-src-qs-installworld"/>
+&prompt.root; <userinput>etcupdate</userinput> <co xml:id="updating-src-qs-etcupdate"/>
+&prompt.root; <userinput>shutdown -r now</userinput> <co xml:id="updating-src-qs-shutdown"/></screen>
+
+ <calloutlist>
+ <callout arearefs="updating-src-qs-svnup">
+ <para>Get the latest version of the source. See
+ <xref linkend="updating-src-obtaining-src"/> for
+ more information on obtaining and updating
+ source.</para>
+ </callout>
+
+ <callout arearefs="updating-src-qs-review-updating">
+ <para>Any manual steps required before or after building
+ from source are shown in
+ <filename>/usr/src/UPDATING</filename>.</para>
+ </callout>
+
+ <callout arearefs="updating-src-qs-cd">
+ <para>Go to the source directory.</para>
+ </callout>
+
+ <callout arearefs="updating-src-qs-buildworld">
+ <para>Compile the world, everything except the
+ kernel.</para>
+ </callout>
+
+ <callout arearefs="updating-src-qs-kernel">
+ <para>Compile and install the kernel. This is
+ equivalent to
+ <buildtarget>buildkernel</buildtarget>
+ <buildtarget>installkernel</buildtarget>.</para>
+ </callout>
+
+ <callout arearefs="updating-src-qs-installworld">
+ <para>Install the world.</para>
+ </callout>
+
+ <callout arearefs="updating-src-qs-etcupdate">
+ <para>Update and merge configuration files in
+ <filename>/etc/</filename>.</para>
+ </callout>
+
+ <callout arearefs="updating-src-qs-shutdown">
+ <para>Restart the system to use the newly-built world
+ and kernel.</para>
+ </callout>
+ </calloutlist>
</step>
+ </procedure>
+ </sect2>
- <step>
- <para>Then, for either file system, if the
- <acronym>CMOS</acronym> clock is set to local time (this
- is true if the output of &man.date.1; does not show the
- correct time and zone), run:</para>
-
- <screen>&prompt.root; <userinput>adjkerntz -i</userinput></screen>
- </step>
-
- <step>
- <para>Remaking the world will not update certain
- directories, such as <filename>/etc</filename>,
- <filename>/var</filename> and <filename>/usr</filename>,
- with new or changed configuration files. The next step is
- to perform some initial configuration file updates
- to <filename>/etc</filename> in
- preparation for the new world. The following command
- compares only those files that are essential for the
- success of <buildtarget>installworld</buildtarget>. For
- instance, this step may add new groups, system accounts,
- or startup scripts which have been added to &os; since the
- last update. This is necessary so that the
- <buildtarget>installworld</buildtarget> step will be able
- to use any new system accounts, groups, and scripts.
- Refer to <xref linkend="mergemaster"/> for more detailed
- instructions about this command:</para>
-
- <screen>&prompt.root; <userinput>mergemaster -p</userinput></screen>
- </step>
-
- <step>
- <para>Install the new world and system binaries from
- <filename>/usr/obj</filename>.</para>
-
- <screen>&prompt.root; <userinput>cd /usr/src</userinput>
-&prompt.root; <userinput>make installworld</userinput></screen>
- </step>
+ <sect2 xml:id="updating-src-preparing">
+ <title>Preparing for a Source Update</title>
- <step>
- <para>Update any remaining configuration files.</para>
+ <para>If this is the first time that a source update has
+ ever been done on this computer, run
+ <command>etcupdate extract</command> to create a record of
+ system settings for later update and merging. This step only
+ needs to be done once on a particular computer.</para>
+
+ <para>Read <filename>/usr/src/UPDATING</filename>. Any manual
+ steps that must be performed before or after an update are
+ described in this file.</para>
+ </sect2>
- <screen>&prompt.root; <userinput>mergemaster -iF</userinput></screen>
- </step>
+ <sect2 xml:id="updating-src-obtaining-src">
+ <title>Updating the Source</title>
- <step>
- <para>Delete any obsolete files. This is important as they
- may cause problems if left on the disk.</para>
+ <para>&os; source code is located in
+ <filename>/usr/src/</filename>. The preferred method of
+ updating this source is through the
+ <application>Subversion</application> version control system.
+ Verify that the source code is under version control:</para>
+
+ <screen>&prompt.root; <userinput>svn info /usr/src</userinput>
+Path: /usr/src
+Working Copy Root Path: /usr/src
+...</screen>
+
+ <para>This indicates that <filename>/usr/src/</filename>
+ is under version control and can be updated with
+ &man.svn.1;:</para>
+
+ <screen xml:id="synching">&prompt.root; <userinput>svn update /usr/src</userinput></screen>
+
+ <para>The update process can take some time if the directory has
+ not been updated recently. After it finishes, the source code
+ is up to date and the build process described in the next
+ section can begin.</para>
+
+ <note xml:id="updating-src-obtaining-src-checkout">
+ <title>Obtaining the Source</title>
+
+ <para>If the output says
+ <literal>'/usr/src' is not a working copy</literal>, the
+ files there are missing or were installed with a different
+ method. A new checkout of the source is required.</para>
+
+ <table xml:id="updating-src-obtaining-src-repopath">
+ <title>&os; Versions and Repository Paths</title>
+
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry><command>uname -r</command> Output</entry>
+ <entry>Repository Path</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry><literal><replaceable>X.Y</replaceable>-RELEASE</literal></entry>
+ <entry><literal>base/releng/</literal><replaceable>X</replaceable></entry>
+ <entry>The Release version plus only critical security
+ and bug fix patches. This branch is recommended
+ for most users.</entry>
+ </row>
+
+ <row>
+ <entry><literal><replaceable>X.Y</replaceable>-STABLE</literal></entry>
+ <entry><literal>base/stable/</literal><replaceable>X</replaceable></entry>
+ <entry>
+ <para>The Release version plus all additional
+ development on that branch.
+ <emphasis>STABLE</emphasis> refers to the
+ Applications Binary Interface
+ (<acronym>ABI</acronym>) not changing, so software
+ compiled for earlier versions still runs. For
+ example, software compiled to run on &os; 10.1
+ will still run on &os; 10-STABLE compiled
+ later.</para>
+
+ <para>STABLE branches occasionally have bugs or
+ incompatibilities which might affect users,
+ although these are typically fixed quickly.</para>
+ </entry>
+ </row>
+
+ <row>
+ <entry><literal><replaceable>X</replaceable>-CURRENT</literal></entry>
+ <entry><literal>base/head/</literal></entry>
+ <entry>The latest unreleased development version of
+ &os;. The CURRENT branch can have major bugs or
+ incompatibilities and is recommended only for
+ advanced users.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>Determine which version of &os; is being used with
+ &man.uname.1;:</para>
+
+ <screen>&prompt.root; <userinput>uname -r</userinput>
+10.3-RELEASE</screen>
+
+ <para>Based on
+ <xref linkend="updating-src-obtaining-src-repopath"/>, the
+ source used to update <literal>10.3-RELEASE</literal> has a
+ repository path of <literal>base/releng/10</literal>. That
+ path is used when checking out the source:</para>
+
+ <screen>&prompt.root; <userinput>mv /usr/src /usr/src.bak</userinput> <co xml:id="updating-src-obtaining-src-mv"/>
+&prompt.root; <userinput>svn checkout https://svn.freebsd.org/base/<replaceable>releng/10</replaceable> /usr/src</userinput> <co xml:id="updating-src-obtaining-src-checkout-cmd"/></screen>
+
+ <calloutlist>
+ <callout arearefs="updating-src-obtaining-src-mv">
+ <para>Move the old directory out of the way. If there are
+ no local modifications in this directory, it can be
+ deleted.</para>
+ </callout>
+
+ <callout arearefs="updating-src-obtaining-src-checkout-cmd">
+ <para>The path from
+ <xref linkend="updating-src-obtaining-src-repopath"/> is
+ added to the repository <acronym>URL</acronym>. The
+ third parameter is the destination directory for the
+ source code on the local system.</para>
+ </callout>
+ </calloutlist>
+ </note>
+ </sect2>
- <screen>&prompt.root; <userinput>make delete-old</userinput></screen>
- </step>
+ <sect2 xml:id="updating-src-building">
+ <title>Building from Source</title>
- <step>
- <para>A full reboot is now needed to load the new kernel and
- new world with the new configuration files.</para>
+ <para xml:id="makeworld">The <emphasis>world</emphasis>, or all
+ of the operating system except the kernel, is compiled. This
+ is done first to provide up-to-date tools to build the kernel.
+ Then the kernel itself is built:</para>
- <screen>&prompt.root; <userinput>reboot</userinput></screen>
- </step>
+ <screen>&prompt.root; <userinput>cd /usr/src</userinput>
+&prompt.root; <userinput>make buildworld</userinput>
+&prompt.root; <userinput>make buildkernel</userinput></screen>
- <step>
- <para>Make sure that all installed ports have first been
- rebuilt before old libraries are removed using the
- instructions in <xref linkend="ports-upgrading"/>. When
- finished, remove any obsolete libraries to avoid conflicts
- with newer ones. For a more detailed description of this
- step, refer to <xref linkend="make-delete-old"/>.</para>
+ <para>The compiled code is written to
+ <filename>/usr/obj</filename>.</para>
- <screen>&prompt.root; <userinput>make delete-old-libs</userinput></screen>
- </step>
- </procedure>
+ <para>These are the basic steps. Additional options to control
+ the build are described below.</para>
- <indexterm><primary>single-user mode</primary></indexterm>
+ <sect3 xml:id="updating-src-building-clean-build">
+ <title>Performing a Clean Build</title>
+
+ <para>Some versions of the &os; build system leave
+ previously-compiled code in the temporary object directory,
+ <filename>/usr/obj</filename>. This can speed up later
+ builds by avoiding recompiling code that has not changed.
+ To force a clean rebuild of everything, remove
+ <filename>/usr/obj</filename> before starting a build.
+ This is roughly equivalent to performing a
+ <command>make clean</command>, but much faster:</para>
+
+ <screen>&prompt.root; <userinput>rm -rf /usr/obj/*</userinput></screen>
+ </sect3>
+
+ <sect3 xml:id="updating-src-building-jobs">
+ <title>Setting the Number of Jobs</title>
+
+ <para>Increasing the number of build jobs on multi-core
+ processors can improve build speed. Determine the number of
+ cores with <command>sysctl hw.ncpu</command>. Processors
+ vary, as do the build systems used with different versions
+ of &os;, so testing is the only sure method to tell how a
+ different number of jobs affects the build speed. For a
+ starting point, consider values between half and double the
+ number of cores. The number of jobs is specified with
+ <option>-j</option>.</para>
+
+ <example xml:id="updating-src-building-jobs-example">
+ <title>Increasing the Number of Build Jobs</title>
+
+ <para>Building the world and kernel with four jobs:</para>
+
+ <screen>&prompt.root; <userinput>make -j4 buildworld buildkernel</userinput></screen>
+ </example>
+ </sect3>
+
+ <sect3 xml:id="updating-src-building-go-fast">
+ <title>go-fast</title>
+
+ <para>Go-fast: Describe other go-fast options like NO_CLEAN
+ here. Preferably avoid having different sections for
+ different versions of &os;.</para>
+ </sect3>
+
+ <sect3 xml:id="updating-src-building-only-kernel">
+ <title>Building Only the Kernel</title>
+
+ <para>A <buildtarget>buildworld</buildtarget> must be
+ completed if the source code has changed. After that, a
+ <buildtarget>buildkernel</buildtarget> to build a kernel can
+ be run at any time. To build just the kernel:</para>
+
+ <screen>&prompt.root; <userinput>cd /usr/src</userinput>
+&prompt.root; <userinput>make buildkernel</userinput></screen>
+ </sect3>
+
+ <sect3 xml:id="updating-src-building-custom-kernel">
+ <title>Building a Custom Kernel</title>
+
+ <para>The standard &os; kernel is based on a
+ <emphasis>kernel config file</emphasis> called
+ <filename>GENERIC</filename>. The
+ <filename>GENERIC</filename> kernel includes the most
+ commonly-needed device drivers and options. Sometimes it
+ is useful or necessary to build a custom kernel, adding or
+ removing device drivers or options to fit a specific
+ need.</para>
+
+ <para>For example, someone developing a small embedded
+ computer with severely limited <acronym>RAM</acronym> could
+ remove unneeded device drivers or options to make the kernel
+ slightly smaller.</para>
+
+ <para>Kernel config files are located in
+ <filename>/usr/src/sys/<replaceable>arch</replaceable>/conf/</filename>,
+ where <replaceable>arch</replaceable> is the output from
+ <command>uname -m</command>. On most computers, that is
+ <literal>amd64</literal>, giving a config file directory of
+ <filename>/usr/src/sys/<replaceable>amd64</replaceable>/conf/</filename>.</para>
+
+ <para>A custom config file can be created by copying the
+ <filename>GENERIC</filename> config file. In this example,
+ the new custom kernel is for a storage server, so is named
+ <filename>STORAGESERVER</filename>:</para>
+
+ <screen>&prompt.root; <userinput>cd /usr/src/sys/amd64/conf</userinput>
+&prompt.root; <userinput>cp GENERIC STORAGESERVER</userinput></screen>
+
+ <para><filename>STORAGESERVER</filename> is then edited,
+ adding or removing devices or options as shown in
+ &man.config.5;.</para>
+
+ <para>The custom kernel is built by setting
+ <varname>KERNCONF</varname> to the kernel config file on the
+ command line:</para>
- <para>If the system can have a window of down-time, consider
- compiling the system in single-user mode instead of compiling
- the system in multi-user mode, and then dropping into
- single-user mode for the installation. Reinstalling the
- system touches a lot of important system files, all the
- standard system binaries, libraries, and include files.
- Changing these on a running system, particularly one with
- active users, is asking for trouble.</para>
+ <screen>&prompt.root; <userinput>make buildkernel KERNCONF=STORAGESERVER</userinput></screen>
+ </sect3>
</sect2>
- <sect2 xml:id="src-updating">
- <title>Configuration Files</title>
-
- <indexterm>
- <primary><filename>make.conf</filename></primary>
- </indexterm>
-
- <para>This build world process uses several configuration
- files.</para>
-
- <para>The <filename>Makefile</filename> located in
- <filename>/usr/src</filename> describes how the programs that
- comprise &os; should be built and the order in which they
- should be built.</para>
-
- <para>The options available to <command>make</command> are
- described in &man.make.conf.5; and some common examples are
- included in
- <filename>/usr/share/examples/etc/make.conf</filename>. Any
- options which are added to <filename>/etc/make.conf</filename>
- will control the how <command>make</command> runs and builds
- programs. These options take effect every time
- <command>make</command> is used, including compiling
- applications from the Ports Collection, compiling custom C
- programs, or building the &os; operating system. Changes to
- some settings can have far-reaching and potentially surprising
- effects. Read the comments in both locations and keep in mind
- that the defaults have been chosen for a combination of
- performance and safety.</para>
-
- <indexterm>
- <primary><filename>src.conf</filename></primary>
- </indexterm>
-
- <para>How the operating system is built from source code is
- controlled by <filename>/etc/src.conf</filename>. Unlike
- <filename>/etc/make.conf</filename>, the contents of
- <filename>/etc/src.conf</filename> only take effect when the
- &os; operating system itself is being built. Descriptions of
- the many options available for this file are shown in
- &man.src.conf.5;. Be cautious about disabling seemingly
- unneeded kernel modules and build options. Sometimes there
- are unexpected or subtle interactions.</para>
- </sect2>
+ <sect2 xml:id="updating-src-installing">
+ <title>Installing the Compiled Code</title>
- <sect2 xml:id="make-buildworld">
- <title>Variables and Targets</title>
+ <para>After the <buildtarget>buildworld</buildtarget> and
+ <buildtarget>buildkernel</buildtarget> steps have been
+ completed, the new kernel and world are installed:</para>
- <para>The general format for using <command>make</command> is as
- follows:</para>
+ <screen>&prompt.root; <userinput>cd /usr/src</userinput>
+&prompt.root; <userinput>make installkernel installworld</userinput></screen>
- <screen>&prompt.root; <userinput>make -<replaceable>x</replaceable> -D<replaceable>VARIABLE</replaceable> <replaceable>target</replaceable></userinput></screen>
+ <para>If a custom kernel was built, <varname>KERNCONF</varname>
+ must also be set to use the new custom kernel:</para>
- <para>In this example,
- <option>-<replaceable>x</replaceable></option> is an option
- passed to <command>make</command>. Refer to &man.make.1; for
- examples of the available options.</para>
-
- <para>To pass a variable, specify the variable name with
- <option>-D<replaceable>VARIABLE</replaceable></option>. The
- behavior of the <filename>Makefile</filename> is controlled by
- variables. These can either be set in
- <filename>/etc/make.conf</filename> or they can be specified
- when using <command>make</command>. For example, this
- variable specifies that profiled libraries should not be
- built:</para>
-
- <screen>&prompt.root; <userinput>make -DNO_PROFILE <replaceable>target</replaceable></userinput></screen>
-
- <para>It corresponds with this setting in
- <filename>/etc/make.conf</filename>:</para>
-
- <programlisting>NO_PROFILE= true # Avoid compiling profiled libraries</programlisting>
-
- <para>The <replaceable>target</replaceable> tells
- <command>make</command> what to do and the
- <filename>Makefile</filename> defines the available targets.
- Some targets are used by the build process to break out the
- steps necessary to rebuild the system into a number of
- sub-steps.</para>
-
- <para>Having separate options is useful for two reasons. First,
- it allows for a build that does not affect any components of a
- running system. Because of this,
- <buildtarget>buildworld</buildtarget> can be safely run on a
- machine running in multi-user mode. It is still recommended
- that <buildtarget>installworld</buildtarget> be run in part in
- single-user mode, though.</para>
-
- <para>Secondly, it allows <acronym>NFS</acronym> mounts to be
- used to upgrade multiple machines on a network, as described
- in <xref linkend="small-lan"/>.</para>
-
- <para>It is possible to specify <option>-j</option> which will
- cause <command>make</command> to spawn several simultaneous
- processes. Since much of the compiling process is
- <acronym>I/O</acronym>-bound rather than
- <acronym>CPU</acronym>-bound, this is useful on both single
- <acronym>CPU</acronym> and multi-<acronym>CPU</acronym>
- machines.</para>
-
- <para>On a single-<acronym>CPU</acronym> machine, run the
- following command to have up to 4 processes running at any one
- time. Empirical evidence posted to the mailing lists shows
- this generally gives the best performance benefit.</para>
-
- <screen>&prompt.root; <userinput>make -j4 buildworld</userinput></screen>
-
- <para>On a multi-<acronym>CPU</acronym> machine, try values
- between <literal>6</literal> and <literal>10</literal> to see
- how they speed things up.</para>
-
- <indexterm>
- <primary>rebuilding <quote>world</quote></primary>
- <secondary>timings</secondary>
- </indexterm>
-
- <note>
- <para>If any variables were specified to <command>make
- buildworld</command>, specify the same variables to
- <command>make installworld</command>. However,
- <option>-j</option> must <emphasis>never</emphasis> be used
- with <buildtarget>installworld</buildtarget>.</para>
-
- <para>For example, if this command was used:</para>
-
- <screen>&prompt.root; <userinput>make -DNO_PROFILE buildworld</userinput></screen>
-
- <para>Install the results with:</para>
-
- <screen>&prompt.root; <userinput>make -DNO_PROFILE installworld</userinput></screen>
-
- <para>Otherwise, the second command will try to install
- profiled libraries that were not built during the
- <command>make buildworld</command> phase.</para>
- </note>
+ <screen>&prompt.root; <userinput>cd /usr/src</userinput>
+&prompt.root; <userinput>make installkernel installworld KERNCONF=STORAGESERVER</userinput></screen>
</sect2>
- <sect2 xml:id="mergemaster">
- <info>
- <title>Merging Configuration Files</title>
-
- <authorgroup>
- <author>
- <personname>
- <firstname>Tom</firstname>
- <surname>Rhodes</surname>
- </personname>
- <contrib>Contributed by </contrib>
- </author>
- </authorgroup>
- </info>
-
- <indexterm>
- <primary>
- <command>mergemaster</command>
- </primary>
- </indexterm>
-
- <para>&os; provides the &man.mergemaster.8; Bourne script to aid
- in determining the differences between the configuration files
- in <filename>/etc</filename>, and the configuration files in
- <filename>/usr/src/etc</filename>. This is the recommended
- solution for keeping the system configuration files up to date
- with those located in the source tree.</para>
-
- <para>Before using <command>mergemaster</command>, it is
- recommended to first copy the existing
- <filename>/etc</filename> somewhere safe. Include
- <option>-R</option> which does a recursive copy and
- <option>-p</option> which preserves times and the ownerships
- on files:</para>
-
- <screen>&prompt.root; <userinput>cp -Rp /etc /etc.old</userinput></screen>
-
- <para>When run, <command>mergemaster</command> builds a
- temporary root environment, from <filename>/</filename> down,
- and populates it with various system configuration files.
- Those files are then compared to the ones currently installed
- in the system. Files that differ will be shown in
- &man.diff.1; format, with the <option>+</option> sign
- representing added or modified lines, and <option>-</option>
- representing lines that will be either removed completely or
- replaced with a new file. Refer to &man.diff.1; for more
- information about how file differences are shown.</para>
-
- <para>Next, <command>mergemaster</command> will display each
- file that differs, and present options to: delete the new
- file, referred to as the temporary file, install the temporary
- file in its unmodified state, merge the temporary file with
- the currently installed file, or view the results
- again.</para>
-
- <para>Choosing to delete the temporary file will tell
- <command>mergemaster</command> to keep the current file
- unchanged and to delete the new version. This option is not
- recommended. To get help at any time, type
- <keycap>?</keycap> at the <command>mergemaster</command>
- prompt. If the user chooses to skip a file, it will be
- presented again after all other files have been dealt
- with.</para>
-
- <para>Choosing to install the unmodified temporary file will
- replace the current file with the new one. For most
- unmodified files, this is the best option.</para>
-
- <para>Choosing to merge the file will present a text editor with
- the contents of both files open. The files can be merged by
- reviewing both files side by side on the screen and choosing
- parts from both to create a finished product. When the files
- are compared side by side, <keycap>l</keycap> selects the left
- contents and <keycap>r</keycap> selects contents from the
- right. The final output will be a file consisting of both
- parts, which can then be installed. This option is
- customarily used for files where settings have been modified
- by the user.</para>
-
- <para>Choosing to view the results again will redisplay the file
- differences.</para>
-
- <para>After <command>mergemaster</command> is done with the
- system files, it will prompt for other options. It may prompt
- to rebuild the password file and will finish up with an option
*** DIFF OUTPUT TRUNCATED AT 1000 LINES ***
More information about the svn-doc-all
mailing list