ch10.xml

<chapter id="LKN-build-command-line">

<title>
Kernel build command line reference
</title>

<para>
As discussed in <xref linkend="LKN-chapter-building" />, the tool that
ties together kernel builds is the <command>make</command> program, to
which you pass a target that specifies what you want to build.  <xref
linkend="LKN-chapter-building" /> went over the basic targets needed
to build the kernel properly, but the kernel build system also has a
wide range of other targets.  This chapter details these targets, and
what they can be used for.
</para>

<para>
All of these targets are passed to the <command>make</command> program on
the command line, and a number of them can be grouped together if
desired. For example:
<screen>
$ <userinput>make mrproper xconfig</userinput>
</screen>

The targets are broken down into different types in the following
sections.
</para>

<para>
You can get a summary of most of these targets by running, within the build directory:
<screen>
$ <userinput>make help</userinput>
</screen>
This target prints out a lot of the common <command>make</command>
targets that are described in the rest of this chapter.
</para>

<sect1>
<title>Informational Targets</title>
<para>
These targets print the kernel version, based on a number of different
options.  They are commonly used by scripts to determine the
version of the kernel being built.
</para>

<table id="lkn-ch12-table-informational">
  <title>Informational targets</title>
  <tgroup cols="2">
    <thead>
      <row>
	<entry><para>Target</para></entry>
	<entry><para>Description</para></entry>
      </row>
    </thead>
    <tbody>
      <row>
	<entry><para><literal>kernelrelease</literal></para></entry>
	<entry><para>Displays the current kernel version, as determined by the build
	system.</para></entry>
      </row>
      <row>
	<entry><para><literal>kernelversion</literal></para></entry>
	<entry><para>Displays the current kernel version, as told by the main Makefile.  This differs from the
	<literal>kernelrelease</literal> target in that it doesn't use
	any additional version
	information based on configuration options or localversion files.</para></entry>
      </row>
    </tbody>
  </tgroup>
</table>
</sect1>

<sect1>
<title>Cleaning Targets</title>

<para>
These targets simply remove files from previous builds. Their use is
highly recommended to make sure you don't contaminate new builds with
files left over that may have been built with different options. They
differ in how much they remove; sometimes you want to keep around
files you've changed.
</para>

<table id="lkn-ch12-table-cleaning">
  <title>Cleaning targets</title>
  <tgroup cols="2">
    <thead>
      <row>
	<entry><para>Target</para></entry>
	<entry><para>Description</para></entry>
      </row>
    </thead>
    <tbody>
      <row>
	<entry><para><literal>clean</literal></para></entry>
	<entry><para>Removes most of the files generated by the kernel build
	system, but keep the kernel configuration.</para></entry>
      </row>
      <row>
	<entry><para><literal>mrproper</literal></para></entry>
	<entry><para>Removes all of the generated files by the kernel build
	system, including the configuration and some
	various backup files.</para></entry>
      </row>
      <row>
	<entry><para><literal>distclean</literal></para></entry>
	<entry><para>Does everything <literal>mrproper</literal> does and removes some
	editor backup and patch leftover files.</para></entry>
      </row>
    </tbody>
  </tgroup>
</table>
</sect1>

<sect1>
<title>Configuration Targets</title>

<para>
These targets allow the kernel to be configured in a wide range of different ways.
</para>

<table id="lkn-ch12-table-configuring">
  <title> Configuration targets</title>
  <tgroup cols="2">
    <thead>
      <row>
	<entry><para>Target</para></entry>
	<entry><para>Description</para></entry>
      </row>
    </thead>
    <tbody>
      <row>
	<entry><para><literal>config</literal></para></entry>
	<entry><para>Updates the current kernel configuration by using a
	line-oriented program.</para></entry>
      </row>
      <row>
	<entry><para><literal>menuconfig</literal></para></entry>
	<entry><para>Updates the current kernel configuration by using a text
	based menu program.</para></entry>
      </row>
      <row>
	<entry><para><literal>xconfig</literal></para></entry>
	<entry><para>Updates the current kernel configuration by using a QT-based graphical program.</para></entry>
      </row>
      <row>
	<entry><para><literal>gconfig</literal></para></entry>
	<entry><para>Updates the current kernel configuration by using a GTK+-based graphical program.</para></entry>
      </row>
      <row>
	<entry><para><literal>oldconfig</literal></para></entry>
	<entry><para>Updates the current kernel configuration by using the
	current <filename>.config</filename> file and prompting for any new options that have been
	added to the kernel.</para></entry>
      </row>
      <row>
	<entry><para><literal>silentoldconfig</literal></para></entry>
	<entry><para>Just like <literal>oldconfig</literal>, but prints nothing to the screen except when a question needs to be
	answered.</para></entry>
      </row>
      <row>
	<entry><para><literal>randconfig</literal></para></entry>
	<entry><para>Generates a new kernel configuration with random answers
	to all of the different options.</para></entry>
      </row>
      <row>
	<entry><para><literal>defconfig</literal></para></entry>
	<entry><para>Generates a new kernel configuration with the default
	answer being used for all options.  The default
	values are taken from a file located in the
	<filename>arch/$ARCH/defconfig</filename> file, where
	<literal>$ARCH</literal> refers to the specific architecture
	for which
	the kernel is being built.</para></entry>
      </row>
      <row>
	<entry><para><literal>allmodconfig</literal></para></entry>
	<entry><para>Generates a new kernel configuration in which modules
	are enabled whenever possible.</para></entry>
      </row>
      <row>
	<entry><para><literal>allyesconfig</literal></para></entry>
	<entry><para>Generates a new kernel configuration with all options
	set to <literal>yes</literal>.</para></entry>
      </row>
      <row>
	<entry><para><literal>allnoconfig</literal></para></entry>
	<entry><para>Generates a new kernel configuration with all options
	set to <literal>no</literal>.</para></entry>
      </row>
    </tbody>
  </tgroup>
</table>

<para>
Note that the <literal>allyesconfig</literal>,
<literal>allmodconfig</literal>,
<literal>allnoconfig</literal>, and
<literal>randconfig</literal> targets also take advantage of the
environment variable <literal>KCONFIG_ALLCONFIG</literal>.  If that
variable points to a file, that file will be used as a list of
configuration values that you require to be set to a specific
value. In other words, the file overrides the normal behavior of the
<command>make</command> targets.
</para>

<para>
For example, if the file <filename>~/linux/must_be_set</filename> contains
the following variables:
<screen>
$ <userinput>cat ~/linux/must_be_set</userinput>
CONFIG_SWAP=y
CONFIG_DEBUG_FS=y
</screen>
and you enter <command>make allnoconfig</command> with the proper
<literal>KCONFIG_ALLCONFIG</literal> environment variable in effect:
<screen>
$ <userinput>KCONFIG_ALLCONFIG=../must_be_set make allnoconfig</userinput>
$ <userinput>grep CONFIG_SWAP .config</userinput>
CONFIG_SWAP=y
</screen>
then the results include:
<screen>
$ <userinput>grep CONFIG_DEBUG_FS .config</userinput>
CONFIG_DEBUG_FS=y
</screen>
This variable would not have normally been set to <literal>y</literal>
otherwise.
</para>

<para>
If the <literal>KCONFIG_ALLCONFIG</literal> variable is not set, the build
system checks for files in the top-level build directory named:

<itemizedlist>

<listitem>
<para>
<filename>allmod.config</filename>
</para>
</listitem>

<listitem>
<para>
<filename>allno.config</filename>
</para>
</listitem>

<listitem>
<para>
<filename>allrandom.config</filename>
</para>
</listitem>

<listitem>
<para>
<filename>allyes.config</filename>
</para>
</listitem>

</itemizedlist>

If any of those files are present, the build uses them as lists of configuration values that must be
forced to the specified values.  If none of those files are found, the build
system finally looks for a file called <filename>all.config</filename> for a
list of forced configuration values.
</para>

<para>
You can use these different files to set up a known good base
configuration that will always work.  Then the other configuration options
can be used to generate different testing configurations for the needed
situation.
</para>


</sect1>

<sect1>
<title>Build Targets</title>
<para>
These targets build the kernel itself in a variety of ways.
</para>

<table id="lkn-ch12-table-build">
  <title>Build targets</title>
  <tgroup cols="2">
    <thead>
      <row>
	<entry><para>Target</para></entry>
	<entry><para>Description</para></entry>
      </row>
    </thead>
    <tbody>
      <row>
	<entry><para><literal>all</literal></para></entry>
	<entry><para>Builds all of the different targets needed for
	this kernel to be able to be used.  This includes both the modules and
	the static portion of the kernel.
	</para></entry>
      </row>
      <row>
	<entry><para><literal>vmlinux</literal></para></entry>
	<entry><para>Builds just the static portion of the kernel,
	not any loadable modules.
	</para></entry>
      </row>
      <row>
	<entry><para><literal>modules</literal></para></entry>
	<entry><para>Builds all of the loadable kernel modules for
	this configuration.
	</para></entry>
      </row>
      <row>
	<entry><para><literal>modules_install</literal></para></entry>
	<entry><para>Installs all of the modules into the specified
	location.  If no location is specified with the
	<literal>INSTALL_MODULE_PATH</literal> environment variable, they are
	installed in the default root directory of the machine.
	</para></entry>
      </row>
      <row>
	<entry><para><literal>dir/</literal></para></entry>
	<entry><para>Builds all of the files in the specified
	directory and in all subdirectories below it.
	</para></entry>
      </row>
      <row>
	<entry><para><literal>dir/file.</literal>[<replaceable>o</replaceable>|<replaceable>i</replaceable>|<replaceable>s</replaceable>]</para></entry>
	<entry><para>Builds only the specified file.
	</para></entry>
      </row>
      <row>
	<entry><para><literal>dir/file.ko</literal></para></entry>
	<entry><para>Builds all of the needed files and links
	them together to form the specified module.
	</para></entry>
      </row>
      <row>
<!--

  AO: Are the two following targets identical, or are they used for
  different text editors?

  gkh: I don't really know.

-->
	<entry><para><literal>tags</literal></para></entry>
	<entry><para>Builds all of the needed tags that most common
	text editors can use while editing the source code.
	</para></entry>
      </row>
      <row>
	<entry><para><literal>TAGS</literal></para></entry>
	<entry><para>Builds all of the needed tags that most common
	text editors can use while editing the source code.
	</para></entry>
      </row>
      <row>
	<entry><para><literal>cscope</literal></para></entry>
	<entry><para>Builds a <command>cscope</command> image, useful
	in source tree searches, of the source tree for
	the architecture specified by the configuration file (not all
	of the kernel source files).
	</para></entry>
      </row>
    </tbody>
  </tgroup>
</table>

<para>
You can also pass a number of environment variables to <command>make</command>
that will change the build.  These can be specified for
almost any target.
</para>

<table id="lkn-ch12-table-environment">
  <title>Environment variables</title>
  <tgroup cols="3">
    <thead>
      <row>
	<entry><para>Variable</para></entry>
	<entry><para>Value</para></entry>
	<entry><para>Description</para></entry>
      </row>
    </thead>
    <tbody>
      <row>
	<entry><para><literal>V</literal></para></entry>
	<entry><para><literal>0</literal></para></entry>
	<entry><para>This tells the build system to run in a quiet manner,
	showing only the file that is currently being built, and not the entire
	command that is running in order to build that file.  This is the
	default option for the build system.
	</para></entry>
      </row>
      <row>
	<entry><para><literal>V</literal></para></entry>
	<entry><para><literal>1</literal></para></entry>
	<entry><para>This tells the build system to operate in a verbose way,
	showing the full command that is being used to generate each of the
	specific files.
	</para></entry>
      </row>
      <row>
	<entry><para><literal>O</literal></para></entry>
	<entry><para><literal>dir</literal></para></entry>
	<entry><para>This tells the build system to locate all output files in
	the <literal>dir</literal> directory, including the kernel
	configuration files.  This allows the kernel to be built from a
	read-only filesystem and have the output placed in another location.
	</para></entry>
      </row>
      <row>
	<entry><para><literal>C</literal></para></entry>
	<entry><para><literal>1</literal></para></entry>
	<entry><para>This checks all C files that are about to be built with
	the <literal>sparse</literal> tool, which detects common programming errors in the kernel
	source files.
	<command>sparse</command> can be downloaded using
	<command>git</command> from
	<systemitem role="url">git://git.kernel.org/pub/scm/devel/sparse/sparse.git</systemitem>.
	Nightly snapshots can be found at
	<systemitem role="url">http://www.codemonkey.org.uk/projects/git-snapshots/sparse/</systemitem>.
	More information on how to use <command>sparse</command> can be
	found in the <filename>Documentation/sparse.txt</filename> file in
	the kernel source tree.
	</para></entry>
      </row>
      <row>
	<entry><para><literal>C</literal></para></entry>
	<entry><para><literal>2</literal></para></entry>
	<entry><para>This forces all C files to be checked with the
	<literal>sparse</literal> tool, even if they did not need to be built.
	</para></entry>
      </row>
    </tbody>
  </tgroup>
</table>
</sect1>

<sect1>
<title>Packaging Targets</title>
<para>
These targets package up a built kernel into a stand-alone package that can be
installed on a wide range of different machines.
</para>

<table id="lkn-ch12-table-packaging">
  <title>Packaging targets</title>
  <tgroup cols="2">
    <thead>
      <row>
	<entry><para>Target</para></entry>
	<entry><para>Description</para></entry>
      </row>
    </thead>
    <tbody>
      <row>
	<entry><para><literal>rpm</literal></para></entry>
	<entry><para>Builds the kernel first and then packages
	it up as a RPM package that can be installed.
	</para></entry>
      </row>
      <row>
	<entry><para><literal>rpm-pkg</literal></para></entry>
	<entry><para>Builds a source RPM package containing the base kernel.
	</para></entry>
      </row>
      <row>
	<entry><para><literal>binrpm-pkg</literal></para></entry>
	<entry><para>Builds a RPM package that contains a compiled kernel and modules.
	</para></entry>
      </row>
      <row>
	<entry><para><literal>deb-pkg</literal></para></entry>
	<entry><para>Builds a Debian package that contains the compiled kernel and modules.
	</para></entry>
      </row>
      <row>
	<entry><para><literal>tar-pkg</literal></para></entry>
	<entry><para>Builds a tarball that contains the compiled kernel and modules.
	</para></entry>
      </row>
      <row>
	<entry><para><literal>targz-pkg</literal></para></entry>
	<entry><para>Builds a <command>gzip</command>-compressed tarball that contains the compiled kernel and modules.
	</para></entry>
      </row>
      <row>
	<entry><para><literal>tarbz2-pkg</literal></para></entry>
	<entry><para>Builds a <command>bzip2</command>-compressed tarball that contains the compiled kernel and modules.
	</para></entry>
      </row>
    </tbody>
  </tgroup>
</table>
</sect1>

<sect1>
<title>Documentation Targets</title>
<para>
These targets build the internal kernel documentation in a variety of
different formats.
</para>

<table id="lkn-ch12-table-documentation">
  <title>Documentation targets</title>
  <tgroup cols="2">
    <thead>
      <row>
	<entry><para>Target</para></entry>
	<entry><para>Description</para></entry>
      </row>
    </thead>
    <tbody>
      <row>
	<entry><para><literal>xmldocs</literal></para></entry>
	<entry><para>Builds the kernel documentation as XML DocBook files.
	</para></entry>
      </row>
      <row>
	<entry><para><literal>psdocs</literal></para></entry>
	<entry><para>Builds the kernel documentation as PostScript files.
	</para></entry>
      </row>
      <row>
	<entry><para><literal>pdfdocs</literal></para></entry>
	<entry><para>Builds the kernel documentation as PDF files.
	</para></entry>
      </row>
      <row>
	<entry><para><literal>htmldocs</literal></para></entry>
	<entry><para>Builds the kernel documentation as HTML files.
	</para></entry>
      </row>
      <row>
	<entry><para><literal>mandocs</literal></para></entry>
	<entry><para>Builds the kernel documentation as a set of man
	pages, which can then be installed with the <command>installmandocs</command> target.
	</para></entry>
      </row>
    </tbody>
  </tgroup>
</table>
</sect1>

<sect1>
<title>Architecture-Specific Targets</title>
<para>
Each kernel architecture has a set of specific targets unique to it.  The
32-bit Intel architecture has the following targets available.
</para>
<table id="lkn-ch12-table-arch">
  <title>32-bit Intel Architecture-Specific Targets</title>
  <tgroup cols="2">
    <thead>
      <row>
	<entry><para>Target</para></entry>
	<entry><para>Description</para></entry>
      </row>
    </thead>
    <tbody>
      <row>
	<entry><para><literal>bzImage</literal></para></entry>
	<entry><para>Creates a compressed kernel image and places it in
	the <filename>arch/i386/boot/bzImage</filename> file. This is the
	default target for the i386 kernel build.
	</para></entry>
      </row>
      <row>
	<entry><para><literal>install</literal></para></entry>
	<entry><para>Installs the kernel image using the distribution-specific <filename>/sbin/installkernel</filename> program.  Note that
	this does not install the kernel modules; that must be done with the
	<literal>modules_install</literal> target.
	</para></entry>
      </row>
      <row>
	<entry><para><literal>bzdisk</literal></para></entry>
	<entry><para>Creates a boot floppy image and writes it to the
	<literal>/dev/fd0</literal> device.
	</para></entry>
      </row>
      <row>
	<entry><para><literal>fdimage</literal></para></entry>
	<entry><para>Creates a boot floppy image and places it in the
	file <filename>arch/i386/boot/fdimage</filename>.  The
	<literal>mtools</literal> package must be present on your system in
	order for this to work properly.
	</para></entry>
      </row>
      <row>
	<entry><para><literal>isoimage</literal></para></entry>
	<entry><para>Creates a CD-ROM boot image and places it in the
	file <filename>arch/i396/boot/image.iso</filename>.  The
	<literal>syslinux</literal> package must be present on your system in
	order for this to work properly.
	</para></entry>
      </row>
    </tbody>
  </tgroup>
</table>
</sect1>

<sect1>
<title>Analysis Targets</title>
<para>
These targets are good for trying to find problem code in the kernel.
<!--

  AO: I edited the paragraph heavily and may have put in something wrong.

  gkh: looks good.

-->
It's a good idea to create a
stack space list when creating new code to determine that your
changes are not taking up too much kernel stack space.  The
<literal>namespacecheck</literal> target is useful for determining whether your
changes can safely add its symbols to the kernel's global namespace.
</para>

<table id="lkn-ch12-table-analyser">
  <title>Analysis targets</title>
  <tgroup cols="2">
    <thead>
      <row>
	<entry><para>Target</para></entry>
	<entry><para>Description</para></entry>
      </row>
    </thead>
    <tbody>
      <row>
	<entry><para><literal>checkstack</literal></para></entry>
	<entry><para>Generate a list of the functions that use the most of the kernel stack space.
	</para></entry>
      </row>
      <row>
	<entry><para><literal>namespacecheck</literal></para></entry>
	<entry><para>Generate a list of all of the kernel symbols and
	their namespaces. This will be a large list.
	</para></entry>
      </row>
    </tbody>
  </tgroup>
</table>
</sect1>

</chapter>

<!-- vim: set ai tw=72 : -->