Date: Fri, 12 May 2017 17:30:55 +0000 (UTC) From: Warren Block <wblock@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r50251 - head/en_US.ISO8859-1/books/handbook/cutting-edge Message-ID: <201705121730.v4CHUtcS042717@repo.freebsd.org>
next in thread | raw e-mail | index | archive | help
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 ***
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201705121730.v4CHUtcS042717>