Page MenuHomeFreeBSD
Files F144619777

D7665.1775818355.diff
No OneTemporary
Actions

Size
58 KB
Referenced Files
None
Subscribers
None

D7665.1775818355.diff
View Options

Index: head/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml
===================================================================
--- head/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml
+++ head/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml
@@ -1067,1044 +1067,445 @@
</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>
-
- <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>
+ <sect1 xml:id="updating-src">
+ <title>Updating &os; from Source</title>
- <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>etcupdate extract</userinput></screen>
- <screen>&prompt.root; <userinput>chflags -R noschg /usr/obj/*</userinput>
-&prompt.root; <userinput>rm -rf /usr/obj</userinput></screen>
- </step>
+ <para>This creates a checkpoint for later comparison and
+ merging of system settings.</para>
- <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>kbdmap</userinput></screen>
- </step>
-
- <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>
+ <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>
- <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>
+ <title>Update and Build</title>
- <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>
-
- <step>
- <para>Update any remaining configuration files.</para>
-
- <screen>&prompt.root; <userinput>mergemaster -iF</userinput></screen>
- </step>
-
- <step>
- <para>Delete any obsolete files. This is important as they
- may cause problems if left on the disk.</para>
-
- <screen>&prompt.root; <userinput>make delete-old</userinput></screen>
- </step>
-
- <step>
- <para>A full reboot is now needed to load the new kernel and
- new world with the new configuration files.</para>
-
- <screen>&prompt.root; <userinput>reboot</userinput></screen>
- </step>
-
- <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>
-
- <screen>&prompt.root; <userinput>make delete-old-libs</userinput></screen>
+ <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>
- <indexterm><primary>single-user mode</primary></indexterm>
+ <sect2 xml:id="updating-src-preparing">
+ <title>Preparing for a Source Update</title>
- <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>
+ <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>
- <sect2 xml:id="src-updating">
- <title>Configuration Files</title>
+ <sect2 xml:id="updating-src-obtaining-src">
+ <title>Updating the Source</title>
- <indexterm>
- <primary><filename>make.conf</filename></primary>
- </indexterm>
+ <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>
- <para>This build world process uses several configuration
- files.</para>
+ <sect2 xml:id="updating-src-building">
+ <title>Building from Source</title>
- <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>
+ <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>
- <indexterm>
- <primary><filename>src.conf</filename></primary>
- </indexterm>
+ <screen>&prompt.root; <userinput>cd /usr/src</userinput>
+&prompt.root; <userinput>make buildworld</userinput>
+&prompt.root; <userinput>make buildkernel</userinput></screen>
- <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>
+ <para>The compiled code is written to
+ <filename>/usr/obj</filename>.</para>
- <sect2 xml:id="make-buildworld">
- <title>Variables and Targets</title>
+ <para>These are the basic steps. Additional options to control
+ the build are described below.</para>
- <para>The general format for using <command>make</command> is as
- follows:</para>
+ <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>make -<replaceable>x</replaceable> -D<replaceable>VARIABLE</replaceable> <replaceable>target</replaceable></userinput></screen>
+ <screen>&prompt.root; <userinput>rm -rf /usr/obj/*</userinput></screen>
+ </sect3>
- <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>
+ <sect3 xml:id="updating-src-building-jobs">
+ <title>Setting the Number of Jobs</title>
- <indexterm>
- <primary>rebuilding <quote>world</quote></primary>
- <secondary>timings</secondary>
- </indexterm>
+ <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>
- <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>
+ <example xml:id="updating-src-building-jobs-example">
+ <title>Increasing the Number of Build Jobs</title>
- <para>For example, if this command was used:</para>
+ <para>Building the world and kernel with four jobs:</para>
- <screen>&prompt.root; <userinput>make -DNO_PROFILE buildworld</userinput></screen>
+ <screen>&prompt.root; <userinput>make -j4 buildworld buildkernel</userinput></screen>
+ </example>
+ </sect3>
- <para>Install the results with:</para>
+ <sect3 xml:id="updating-src-building-go-fast">
+ <title>go-fast</title>
- <screen>&prompt.root; <userinput>make -DNO_PROFILE installworld</userinput></screen>
+ <para>Go-fast: Describe other go-fast options like NO_CLEAN
+ here. Preferably avoid having different sections for
+ different versions of &os;.</para>
+ </sect3>
- <para>Otherwise, the second command will try to install
- profiled libraries that were not built during the
- <command>make buildworld</command> phase.</para>
- </note>
- </sect2>
+ <sect3 xml:id="updating-src-building-only-kernel">
+ <title>Building Only the Kernel</title>
- <sect2 xml:id="mergemaster">
- <info>
- <title>Merging Configuration Files</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>
- <authorgroup>
- <author>
- <personname>
- <firstname>Tom</firstname>
- <surname>Rhodes</surname>
- </personname>
- <contrib>Contributed by </contrib>
- </author>
- </authorgroup>
- </info>
-
- <indexterm>
- <primary>
- <command>mergemaster</command>
- </primary>
- </indexterm>
+ <screen>&prompt.root; <userinput>cd /usr/src</userinput>
+&prompt.root; <userinput>make buildkernel</userinput></screen>
+ </sect3>
- <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
- to remove left-over temporary files.</para>
-<!--
-Probably not needed as changes should be minimal and mergemaster does
-a good job of merging.
- <tip>
- <title>Name the New Root Directory
- (<filename>/var/tmp/root</filename>)
- with a Time Stamp, so You Can Easily Compare Differences
- Between Versions</title>
-
- <para>Frequently rebuilding world entails frequently
- updating <filename>/etc</filename>
- as well, which can be a bit of a chore.</para>
-
- <para>To speed up this process, use the following
- procedure to keep a copy of the last set of changed files
- that were merged into <filename>/etc</filename>.</para>
-
- <procedure>
- <step>
- <para>Make the world as normal. When updating
- <filename>/etc</filename> and the
- other directories, give the target directory a name
- based on the current date:</para>
-
- <screen>&prompt.root; <userinput>mkdir /var/tmp/root-20130214</userinput>
-&prompt.root; <userinput>cd /usr/src/etc</userinput>
-&prompt.root; <userinput>make DESTDIR=/var/tmp/root-20130214 \
- distrib-dirs distribution</userinput></screen>
- </step>
-
- <step>
- <para>Merge in the changes from this directory as
- outlined above. <emphasis>Do not</emphasis> remove
- the <filename>/var/tmp/root-20130214</filename>
- directory when you have finished.</para>
- </step>
-
- <step>
- <para>After downloading the latest version of the
- source and remaking it, follow step 1. Create a new
- directory, which reflects the new date. This example
- uses
- <filename>/var/tmp/root-20130221</filename>.</para>
- </step>
-
- <step>
- <para>Use &man.diff.1; to see the differences that have
- been made in the intervening week by creating a
- recursive diff between the two directories:</para>
-
- <screen>&prompt.root; <userinput>cd /var/tmp</userinput>
-&prompt.root; <userinput>diff -r root-20130214 root-20130221</userinput></screen>
-
- <para>Typically, this will be a much smaller set of
- differences than those between
- <filename>/var/tmp/root-20130221/etc</filename> and
- <filename>/etc</filename>. Because the set of
- differences is smaller, it is easier to migrate those
- changes across into <filename>/etc</filename>.</para>
- </step>
-
- <step>
- <para>When finished, remove the older of the two
- <filename>/var/tmp/root-*</filename>
- directories:</para>
-
- <screen>&prompt.root; <userinput>rm -rf /var/tmp/root-20130214</userinput></screen>
- </step>
-
- <step>
- <para>Repeat this process whenever merging
- in changes to <filename>/etc</filename>.</para>
- </step>
- </procedure>
+ <sect3 xml:id="updating-src-building-custom-kernel">
+ <title>Building a Custom Kernel</title>
- <para>Use &man.date.1; to automate the generation of the
- directory names:</para>
+ <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>
- <screen>&prompt.root; <userinput>mkdir /var/tmp/root-`date "+%Y%m%d"`</userinput></screen>
- </tip>
- -->
+ <screen>&prompt.root; <userinput>make buildkernel KERNCONF=STORAGESERVER</userinput></screen>
+ </sect3>
</sect2>
- <sect2 xml:id="make-delete-old">
- <info>
- <title>Deleting Obsolete Files and Libraries</title>
+ <sect2 xml:id="updating-src-installing">
+ <title>Installing the Compiled Code</title>
- <authorgroup>
- <author>
- <personname>
- <firstname>Anton</firstname>
- <surname>Shterenlikht</surname>
- </personname>
- <contrib>Based on notes provided by </contrib>
- </author>
- </authorgroup>
- </info>
+ <para>After the <buildtarget>buildworld</buildtarget> and
+ <buildtarget>buildkernel</buildtarget> steps have been
+ completed, the new kernel and world are installed:</para>
- <indexterm>
- <primary>Deleting obsolete files and directories</primary>
- </indexterm>
+ <screen>&prompt.root; <userinput>cd /usr/src</userinput>
+&prompt.root; <userinput>make installkernel installworld</userinput></screen>
- <para>As a part of the &os; development lifecycle, files and
- their contents occasionally become obsolete. This may be
- because functionality is implemented elsewhere, the version
- number of the library has changed, or it was removed from the
- system entirely. These obsoleted files, libraries, and
- directories should be removed when updating the system.
- This ensures that the system is not cluttered with old files
- which take up unnecessary space on the storage and backup
- media. Additionally, if the old library has a security or
- stability issue, the system should be updated to the newer
- library to keep it safe and to prevent crashes caused by the
- old library. Files, directories, and libraries which are
- considered obsolete are listed in
- <filename>/usr/src/ObsoleteFiles.inc</filename>. The
- following instructions should be used to remove obsolete files
- during the system upgrade process.</para>
-
- <para>After the <command>make installworld</command> and the
- subsequent <command>mergemaster</command> have finished
- successfully, check for obsolete files and libraries:</para>
+ <para>If a custom kernel was built, <varname>KERNCONF</varname>
+ must also be set to use the new custom kernel:</para>
<screen>&prompt.root; <userinput>cd /usr/src</userinput>
-&prompt.root; <userinput>make check-old</userinput></screen>
+&prompt.root; <userinput>make installkernel installworld KERNCONF=STORAGESERVER</userinput></screen>
+ </sect2>
- <para>If any obsolete files are found, they can be deleted using
- the following command:</para>
+ <sect2 xml:id="updating-src-completing">
+ <title>Completing the Update</title>
- <screen>&prompt.root; <userinput>make delete-old</userinput></screen>
+ <para>A few final tasks complete the update. Any modified
+ configuration files are merged with the new versions, outdated
+ libraries are located and removed, then the system is
+ restarted.</para>
+
+ <sect3 xml:id="updating-src-completing-merge-etcupdate">
+ <title>Merging Configuration Files with
+ <application>etcupdate</application></title>
+
+ <para><application>etcupdate</application> provides an easy
+ way to merge changes that have been made to system
+ configuration files with new versions of those files.</para>
- <para>A prompt is displayed before deleting each obsolete file.
- To skip the prompt and let the system remove these files
- automatically, use
- <varname>BATCH_DELETE_OLD_FILES</varname>:</para>
+ <para><command>etcupdate</command></para>
+ </sect3>
- <screen>&prompt.root; <userinput>make -DBATCH_DELETE_OLD_FILES delete-old</userinput></screen>
+ <sect3 xml:id="updating-src-completing-merge-mergemaster">
+ <title xml:id="mergemaster">Merging Configuration Files with
+ <application>mergemaster</application></title>
- <para>The same goal can be achieved by piping these commands
- through <command>yes</command>:</para>
+ <para><command>mergemaster -Ui</command></para>
+ </sect3>
- <screen>&prompt.root; <userinput>yes|make delete-old</userinput></screen>
+ <sect3 xml:id="updating-src-completing-check-old">
+ <title>Checking for Outdated Files and Libraries</title>
- <warning>
- <title>Warning</title>
+ <para>Some obsolete files or directories can remain after an
+ update. These files can be located:</para>
- <para>Deleting obsolete files will break applications that
- still depend on those obsolete files. This is especially
- true for old libraries. In most cases, the programs, ports,
- or libraries that used the old library need to be recompiled
- before <command>make delete-old-libs</command> is
- executed.</para>
- </warning>
-
- <para>Utilities for checking shared library dependencies include
- <package>sysutils/libchk</package> and
- <package>sysutils/bsdadminscripts</package>.</para>
-
- <para>Obsolete shared libraries can conflict with newer
- libraries, causing messages like these:</para>
-
- <screen>/usr/bin/ld: warning: libz.so.4, needed by /usr/local/lib/libtiff.so, may conflict with libz.so.5
-/usr/bin/ld: warning: librpcsvc.so.4, needed by /usr/local/lib/libXext.so, may conflict with librpcsvc.so.5</screen>
-
- <para>To solve these problems, determine which port installed
- the library:</para>
-
- <screen>&prompt.root; <userinput>pkg which /usr/local/lib/libtiff.so</userinput>
- /usr/local/lib/libtiff.so was installed by package tiff-3.9.4
-&prompt.root; <userinput>pkg which /usr/local/lib/libXext.so</userinput>
- /usr/local/lib/libXext.so was installed by package libXext-1.1.1,1</screen>
-
- <para>Then deinstall, rebuild, and reinstall the port. To
- automate this process,
- <package>ports-mgmt/portmaster</package> can be used. After
- all ports are rebuilt and no longer use the old libraries,
- delete the old libraries using the following command:</para>
-
- <screen>&prompt.root; <userinput>make delete-old-libs</userinput></screen>
-
- <para>If something goes wrong, it is easy to rebuild a
- particular piece of the system. For example, if
- <filename>/etc/magic</filename> was accidentally deleted as
- part of the upgrade or merge of <filename>/etc</filename>,
- <command>file</command> will stop working. To fix this,
- run:</para>
+ <screen>&prompt.root; <userinput>make check-old</userinput></screen>
- <screen>&prompt.root; <userinput>cd /usr/src/usr.bin/file</userinput>
-&prompt.root; <userinput>make all install</userinput></screen>
- </sect2>
+ <para>and deleted:</para>
- <sect2 xml:id="updating-questions">
- <title>Common Questions</title>
+ <screen>&prompt.root; <userinput>make delete-old</userinput></screen>
- <variablelist>
- <varlistentry>
- <term>Do I need to re-make the world for every
- change?</term>
-
- <listitem>
- <para>It depends upon the nature of the change. For
- example, if <application>svn</application> only shows
- the following files as being updated:</para>
-
- <screen><filename>src/games/factor/factor.c</filename>
-<filename>src/games/fortune/fortune/fortune.c</filename>
-<filename>src/usr.sbin/bsdinstall/distextract/distextract.c</filename>
-<filename>src/usr.sbin/bsdinstall/partedit/diskeditor.c</filename>
-<filename>src/share/man/man7/intro.7</filename></screen>
-
- <para>it probably is not worth rebuilding the entire
- world. Instead, go into the appropriate sub-directories
- and run <command>make all install</command>. But if
- something major changes, such as
- <filename>src/lib/libc/stdlib</filename>, a complete rebuild of
- world is highly recommended.</para>
-
- <para>Some users rebuild world every fortnight and let
- changes accumulate over that fortnight. Others only
- re-make those things that have changed and are careful
- to spot all the dependencies. It all depends on how
- often a user wants to upgrade and whether they are
- tracking &os.stable; or &os.current;.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>What would cause a compile to fail with lots of
- signal 11<indexterm>
- <primary>signal 11</primary>
- </indexterm>
- (or other signal number) errors?</term>
-
- <listitem>
- <para>This normally indicates a hardware problem.
- Building world is an effective way to stress test
- hardware, especially memory. A sure indicator of a
- hardware issue is when <application>make</application>
- is restarted and it dies at a different point in the
- process.</para>
-
- <para>To resolve this error, swap out the components in
- the machine, starting with RAM, to determine which
- component is failing.</para>
- </listitem>
- </varlistentry>
+ <para>Some obsolete libraries can also remain. These can be
+ detected with:</para>
- <varlistentry>
- <term>Can <filename>/usr/obj</filename>
- be removed when finished?</term>
+ <screen>&prompt.root; <userinput>make check-old-libs</userinput></screen>
- <listitem>
- <para>This directory contains all the object files that
- were produced during the compilation phase. Normally,
- one of the first steps in the <command>make
- buildworld</command> process is to remove this
- directory and start afresh. Keeping
- <filename>/usr/obj</filename> around when finished makes
- little sense, and its removal frees up a approximately
- 2GB of disk space.</para>
- </listitem>
- </varlistentry>
+ <para>and deleted with</para>
- <varlistentry>
- <term>Can interrupted builds be resumed?</term>
+ <screen>&prompt.root; <userinput>make delete-old-libs</userinput></screen>
- <listitem>
- <para>This depends on how far into the process the
- problem occurs. In general, <command>make
- buildworld</command> builds new copies of essential
- tools and the system libraries. These tools and
- libraries are then installed, used to rebuild
- themselves, and are installed again. The rest of the
- system is then rebuilt with the new system
- tools.</para>
-
- <para>During the last stage, it is fairly safe to run
- these commands as they will not undo the work of the
- previous <command>make buildworld</command>:</para>
-
- <screen>&prompt.root; <userinput>cd /usr/src</userinput>
-&prompt.root; <userinput>make -DNO_CLEAN all</userinput></screen>
-
- <para>If this message appears:</para>
-
- <screen>--------------------------------------------------------------
-Building everything..
---------------------------------------------------------------</screen>
-
- <para>in the <command>make buildworld</command> output,
- it is probably fairly safe to do so.</para>
-
- <para>If that message is not displayed, it is always
- better to be safe than sorry and to restart the build
- from scratch.</para>
- </listitem>
- </varlistentry>
+ <para>Programs which were still using those old libraries will
+ stop working when the library has been deleted. These
+ programs must be rebuilt or replaced after deleting the old
+ libraries.</para>
- <varlistentry>
- <term>Is it possible to speed up making the world?</term>
+ <tip>
+ <para>When all the old files or directories are known to be
+ safe to delete, pressing <keycap>y</keycap> and
+ <keycap>Enter</keycap> to delete each file can be avoided
+ by setting <varname>BATCH_DELETE_OLD_FILES</varname> in
+ the command. For example:</para>
- <listitem>
- <para>Several actions can speed up the build world
- process. For example, the entire process can be run
- from single-user mode. However, this will prevent users
- from having access to the system until the process is
- complete.</para>
-
- <para>Careful file system design or the use of ZFS
- datasets can make a difference. Consider putting
- <filename>/usr/src</filename> and
- <filename>/usr/obj</filename> on
- separate file systems. If possible, place the file
- systems on separate disks on separate disk controllers.
- When mounting <filename
- >/usr/src</filename>, use
- <option>noatime</option> which prevents the file system
- from recording the file access time. If <filename
- >/usr/src</filename> is not on its
- own file system, consider remounting <filename
- >/usr</filename> with
- <option>noatime</option>.</para>
-
- <para>The file system holding <filename
- >/usr/obj</filename> can be mounted
- or remounted with <option>async</option> so that disk
- writes happen asynchronously. The write completes
- immediately, and the data is written to the disk a few
- seconds later. This allows writes to be clustered
- together, and can provide a dramatic performance
- boost.</para>
-
- <warning>
- <para>Keep in mind that this option makes the file
- system more fragile. With this option, there is an
- increased chance that, should power fail, the file
- system will be in an unrecoverable state when the
- machine restarts.</para>
-
- <para>If <filename>/usr/obj</filename> is the only
- directory on this file system, this is not a problem.
- If you have other, valuable data on the same file
- system, ensure that there are verified backups before
- enabling this option.</para>
- </warning>
-
- <para>Turn off profiling by setting
- <quote>NO_PROFILE=true</quote> in
- <filename>/etc/make.conf</filename>.</para>
-
- <para>Pass <option>-j<replaceable>n</replaceable></option>
- to &man.make.1; to run multiple processes in parallel.
- This usually helps on both single- and multi-processor
- machines.</para>
- </listitem>
- </varlistentry>
+ <screen>&prompt.root; <userinput>make BATCH_DELETE_OLD_FILES=yes delete-old-libs</userinput></screen>
+ </tip>
+ </sect3>
- <varlistentry>
- <term>What if something goes wrong?</term>
+ <sect3 xml:id="updating-src-completing-restart">
+ <title>Restarting After the Update</title>
- <listitem>
- <para>First, make absolutely sure that the environment has
- no extraneous cruft from earlier builds:</para>
+ <para>The last step after updating is to restart the computer
+ so all the changes take effect:</para>
- <screen>&prompt.root; <userinput>chflags -R noschg /usr/obj/usr</userinput>
-&prompt.root; <userinput>rm -rf /usr/obj/usr</userinput>
-&prompt.root; <userinput>cd /usr/src</userinput>
-&prompt.root; <userinput>make cleandir</userinput>
-&prompt.root; <userinput>make cleandir</userinput></screen>
-
- <para>Yes, <command>make cleandir</command> really should
- be run twice.</para>
-
- <para>Then, restart the whole process, starting with
- <command>make buildworld</command>.</para>
-
- <para>If problems persist, send the error and the output
- of <command>uname -a</command> to &a.questions;. Be
- prepared to answer other questions about the
- setup!</para>
- </listitem>
- </varlistentry>
- </variablelist>
+ <screen>&prompt.root; <userinput>shutdown -r now</userinput></screen>
+ </sect3>
</sect2>
</sect1>

File Metadata

Mime Type
text/plain
Expires
Fri, Apr 10, 10:52 AM (16 m, 29 s)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
28315755
Default Alt Text
D7665.1775818355.diff (58 KB)

Event Timeline