doc: build system documentation cleanup
Change-Id: I8a55b103f4143770c74434c376c4d1770a0374e3 Signed-off-by: Anas Nashif <anas.nashif@intel.com>
This commit is contained in:
Anas Nashif
parent
68f6032006
commit
df64bba4d7
5 changed files with 55 additions and 196 deletions
|
|
@ -1,25 +1,16 @@
|
|||
.. _kbuild:
|
||||
|
||||
The Build System User Guide
|
||||
###########################
|
||||
Build System User Guide
|
||||
#######################
|
||||
|
||||
The |codename|'s build system is based on the Kbuild system used in the
|
||||
Linux kernel, version 3.19-rc7. This way the kernel embraces
|
||||
the recursive model proposed by Linux and the configuration model
|
||||
proposed by Kconfig.
|
||||
Linux kernel. This way the kernel embraces the recursive model used in Linux
|
||||
and the configuration model implemented using Kconfig.
|
||||
|
||||
The |codename|'s build system is application centered, unlike the Linux Kbuild system. Therefore,
|
||||
the build system requires an application to build the kernel's image. For that reason, the build
|
||||
structure follows the Kbuild architecture, yet requires an application directory. The
|
||||
application's directory contains the application's definition and code files. The build system
|
||||
compiles the kernel and the application into a single image.
|
||||
|
||||
Scope
|
||||
*****
|
||||
|
||||
The following sections provide details about the build system implementation. The information is
|
||||
intended for application developers wanting to use the kernel as a development platform and for
|
||||
kernel developers looking to modify or expand the kernel's functionality.
|
||||
The |codename|'s build process is driven by applications, unlike the Linux Kbuild
|
||||
system. Therefore, the build system requires an application to initiate building
|
||||
the kernel source code. The build system compiles the kernel and the application
|
||||
into a single image.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
|
@ -27,5 +18,3 @@ kernel developers looking to modify or expand the kernel's functionality.
|
|||
kbuild_kconfig
|
||||
kbuild_makefiles
|
||||
kbuild_project
|
||||
kbuild_targets
|
||||
kbuild_toolchains
|
||||
|
|
|
|||
|
|
@ -20,11 +20,9 @@ they add to the configuration menus. For example:
|
|||
defined for and apply to the entire build system.
|
||||
|
||||
* The Kconfig file at the :file:`kernel` directory contains the general
|
||||
configuration related to the micro- and the nanokernel. Some configuration
|
||||
options contained here are: :option:`Kernel Type`
|
||||
and :option:`Enhanced Security`.
|
||||
configuration related to the micro- and the nanokernel.
|
||||
|
||||
* The Kconfig file at the :file:`driver` directory organizes the inclusion of
|
||||
* The Kconfig file at the :file:`drivers` directory organizes the inclusion of
|
||||
the various Kconfig files needed for each supported driver in the system.
|
||||
|
||||
* The Kconfig file at the :file:`misc` directory contains the configuration
|
||||
|
|
@ -73,7 +71,7 @@ kernel on a specific platform. For example:
|
|||
* :file:`arch/x86/configs` and
|
||||
* :file:`arch/arc/configs`.
|
||||
|
||||
All the defconfig files must end with the suffix defconfig. For
|
||||
All the default configuration files must end with the suffix _defconfig. For
|
||||
example, the :file:`galileo_defconfig` file contains the configuration
|
||||
information for the galileo platform.
|
||||
|
||||
|
|
@ -84,7 +82,7 @@ target's defconfig. The build system takes the specified defconfig file and
|
|||
sets it as the current :file:`.config` file for the current project. For
|
||||
example:
|
||||
|
||||
.. code-block:: bash
|
||||
.. code-block:: console
|
||||
|
||||
$ make galileo_defconfig
|
||||
|
||||
|
|
@ -104,8 +102,8 @@ configuration options. The subset must contain the specific configuration
|
|||
options that differ from the default configuration.
|
||||
|
||||
The **initconfig** target pulls the default configuration file and merges it
|
||||
with the configuration snippet. For example, the sample application **hello
|
||||
world** overrides the base configuration with the configuration snippet
|
||||
with the local configuration fragments. For example, the sample application **hello
|
||||
world** overrides the base configuration with the configuration fragment in
|
||||
:file:`prj.conf`.
|
||||
|
||||
.. caution::
|
||||
|
|
|
|||
|
|
@ -6,43 +6,49 @@ The Makefiles
|
|||
Overview
|
||||
========
|
||||
|
||||
The build system defines a set of conventions for the correct use of Makefiles in the kernel source
|
||||
directories. The correct use of Makefiles is driven by the concept of recursion.
|
||||
The build system defines a set of conventions for the correct use of Makefiles
|
||||
in the kernel source directories. The correct use of Makefiles is driven by the
|
||||
concept of recursion.
|
||||
|
||||
In the recursion model, each Makefile within a directory includes the source code and any
|
||||
sub-directories to the build process. Each sub-directory follows the same principle. Developers can
|
||||
focus exclusively in their own work. They integrate their module with the build system by adding a
|
||||
very simple Makefile following the recursive model.
|
||||
In the recursion model, each Makefile within a directory includes the source
|
||||
code and any subdirectories to the build process. Each subdirectory follows
|
||||
the same principle. Developers can focus exclusively in their own work. They
|
||||
integrate their module with the build system by adding a very simple Makefile
|
||||
following the recursive model.
|
||||
|
||||
.. _makefile_conventions:
|
||||
|
||||
Makefile Conventions
|
||||
====================
|
||||
|
||||
The following conventions restrict how to add modules and Makefiles to the build system. These
|
||||
conventions guard the correct implementation of the recursive model.
|
||||
The following conventions restrict how to add modules and Makefiles to the
|
||||
build system. These conventions guard the correct implementation of the
|
||||
recursive model.
|
||||
|
||||
* Each source code directory must contain a single Makefile. Directories without a Makefile are not
|
||||
considered source code directories.
|
||||
* Each source code directory must contain a single Makefile. Directories
|
||||
without a Makefile are not considered source code directories.
|
||||
|
||||
* The scope of every Makefile is restricted to the contents of that directory. A Makefile can only
|
||||
make a direct reference to its own files and sub-directories. Any file outside the directory has
|
||||
to be referenced in its home directory Makefile.
|
||||
* The scope of every Makefile is restricted to the contents of that directory.
|
||||
A Makefile can only make a direct reference to its own files and subdirectories.
|
||||
Any file outside the directory has to be referenced in its home directory Makefile.
|
||||
|
||||
* Makefiles list the object files that are included in the link process. The build system finds the
|
||||
source file that generates the object file by matching the file name.
|
||||
* Makefiles list the object files that are included in the link process. The
|
||||
build system finds the source file that generates the object file by matching
|
||||
the file name.
|
||||
|
||||
* Parent directories add their child directories into the recursion model.
|
||||
|
||||
* The root Makefile adds the directories in the kernel base directory into the recursion model.
|
||||
* The root Makefile adds the directories in the kernel base directory into the
|
||||
recursion model.
|
||||
|
||||
|
||||
Adding Source Files
|
||||
===================
|
||||
A source file is added to the build system through its home directory Makefile. The Makefile must
|
||||
refer the source build indirectly, specifying the object file that results from the source file
|
||||
using the :literal:`obj-y` variable. For example, if the file that we want to add is a C file named
|
||||
:file:`<file>.c` the following line should be added in the Makefile:
|
||||
A source file is added to the build system through its home directory Makefile.
|
||||
The Makefile must refer the source build indirectly, specifying the object file
|
||||
that results from the source file using the :literal:`obj-y` variable. For
|
||||
example, if the file that we want to add is a C file named :file:`<file>.c` the
|
||||
following line should be added in the Makefile:
|
||||
|
||||
.. code-block:: make
|
||||
|
||||
|
|
@ -52,10 +58,10 @@ using the :literal:`obj-y` variable. For example, if the file that we want to ad
|
|||
|
||||
The same method applies for assembly files with .s extension.
|
||||
|
||||
Source files can be added conditionally using configuration options.
|
||||
For example, if the option :option:`CONFIG_VAR` is set and it implies that
|
||||
a source file must be added in the compilation process, then the
|
||||
following line adds the source code conditionally:
|
||||
Source files can be added conditionally using configuration options. For
|
||||
example, if the option :option:`CONFIG_VAR` is set and it implies that a source
|
||||
file must be added in the compilation process, then the following line adds the
|
||||
source code conditionally:
|
||||
|
||||
.. code-block:: make
|
||||
|
||||
|
|
@ -64,20 +70,21 @@ following line adds the source code conditionally:
|
|||
Adding Directories
|
||||
==================
|
||||
|
||||
Add a subdirectory to the build system by editing the Makefile in its directory.
|
||||
The subdirectory is added using the :literal:`obj-y` variable. The correct syntax to add a
|
||||
subdirectory into the recursion is:
|
||||
Add a subdirectory to the build system by editing the Makefile in its
|
||||
directory. The subdirectory is added using the :literal:`obj-y` variable. The
|
||||
correct syntax to add a subdirectory into the recursion is:
|
||||
|
||||
.. code-block:: make
|
||||
|
||||
obj-y += <directory_name>/
|
||||
|
||||
The backslash at the end of the directory name signals the build system that a directory, and not a
|
||||
file, is being added to the recursion.
|
||||
The backslash at the end of the directory name signals the build system that a
|
||||
directory, and not a file, is being added to the recursion.
|
||||
|
||||
The conventions require us to add only one directory per line and never to mix source code with
|
||||
directory recursion in a single :literal:`obj-y` line. This helps keep the readability of the
|
||||
Makefile by making it clear when an item adds an additional lever of recursion.
|
||||
The conventions require us to add only one directory per line and never to mix
|
||||
source code with directory recursion in a single :literal:`obj-y` line. This
|
||||
helps keep the readability of the Makefile by making it clear when an item adds
|
||||
an additional lever of recursion.
|
||||
|
||||
Directories can also be conditionally added:
|
||||
|
||||
|
|
@ -85,29 +92,5 @@ Directories can also be conditionally added:
|
|||
|
||||
oby-$(CONFIG_VAR) += <directory_name>/
|
||||
|
||||
The subdirectory must contain its own Makefile following the rules
|
||||
described in :ref:`makefile_conventions`.
|
||||
|
||||
Adding Root Directories
|
||||
=======================
|
||||
|
||||
Root directories are the directories inside the kernel's base directory. Examples include:
|
||||
the :file:`arch/`, :file:`kernel/` and :file:`driver/` directories.
|
||||
|
||||
The parent directory for this directories is the root directory and it contains the
|
||||
root Makefile. The root Makefile defines the variable :literal:`core-y` used to list all
|
||||
directories at the root of recursion.
|
||||
|
||||
To add a new root directory, include the directory name in the list. For example:
|
||||
|
||||
.. code-block:: make
|
||||
|
||||
core-y += <directory_name/>
|
||||
|
||||
A new root directory might require a specific variable instead of :literal:`core-y`. Consult with
|
||||
the code's maintainer before performing a change of this sort.
|
||||
|
||||
.. caution::
|
||||
|
||||
Adding or changing root directories can potentially compromise the integrity and organization of
|
||||
the project.
|
||||
The subdirectory must contain its own Makefile following the rules described in
|
||||
:ref:`makefile_conventions`.
|
||||
|
|
|
|||
|
|
@ -1,110 +0,0 @@
|
|||
.. _kbuild_targets:
|
||||
|
||||
Supported Targets
|
||||
*****************
|
||||
|
||||
The build system supports the following targets:
|
||||
|
||||
Clean targets
|
||||
=============
|
||||
|
||||
**clean**: Removes most generated files keeping the configuration information.
|
||||
|
||||
**distclean**: Removes editor backup and patch files.
|
||||
|
||||
**pristine**: Alias name for distclean.
|
||||
|
||||
**mrproper**: Removes all generated files, various backup files, and host tools files.
|
||||
|
||||
Configuration targets
|
||||
=====================
|
||||
|
||||
**config**: Updates the current configuration using a line-oriented program.
|
||||
|
||||
**nconfig**: Updates the current configuration using a ncurses menu based program.
|
||||
|
||||
**menuconfig**: Updates the current configuration using a menu based program.
|
||||
|
||||
**xconfig**: Updates the current configuration using a QT based front-end.
|
||||
|
||||
**gconfig**: Updates the current configuration using a GTK based front-end.
|
||||
|
||||
**oldconfig**: Updates the current configuration using a provided :file:`.config` as base.
|
||||
|
||||
**silentoldconfig**: Works as oldconfig but quietly. Additionally, it updates the dependencies.
|
||||
|
||||
**defconfig**: Creates a new configuration with the default defconfig supplied by ARCH.
|
||||
|
||||
**savedefconfig**: Saves the current configuration as the minimal configuration under
|
||||
:file:`./defconfig`.
|
||||
|
||||
**allnoconfig**: Creates a configuration file where all options are answered with no.
|
||||
|
||||
**allyesconfig**: Creates a configuration file where all options are accepted with yes.
|
||||
|
||||
**alldefconfig**: Creates a configuration file with all symbols set to default.
|
||||
|
||||
**randconfig**: Creates a configuration file with random answer to all options.
|
||||
|
||||
**listnewconfig**: Lists new options.
|
||||
|
||||
**olddefconfig**: Works as silentoldconfig while setting new symbols to their default value.
|
||||
|
||||
**tinyconfig**: Configures the smallest possible kernel.
|
||||
|
||||
Generic Targets
|
||||
=====================
|
||||
|
||||
**all**: Builds zephyr target.
|
||||
|
||||
**zephyr**: Builds the bare kernel.
|
||||
|
||||
**qemu**: Builds the bare kernel and runs the emulation with Qemu.
|
||||
|
||||
x86 Supported Default Configuration Files
|
||||
=========================================
|
||||
|
||||
**micro_galileo_defconfig**: Builds a microkernel for Galileo.
|
||||
|
||||
**micro_basic_atom_defconfig**: Builds a microkernel for an Atom processor on Qemu.
|
||||
|
||||
**micro_basic_minuteia_defconfig**: Builds a microkernel for minute IA processor on Qemu.
|
||||
|
||||
**nano_galileo_defconfig**: Builds a nanokernel for Galileo.
|
||||
|
||||
**nano_basic_atom_defconfig**: Builds a nanokernel for an Atom processor on Qemu.
|
||||
|
||||
**nano_basic_minuteia_defconfig**: Builds a nanokernel for minute IA processor on Qemu.
|
||||
|
||||
arm Supported Default Configuration Files
|
||||
=========================================
|
||||
|
||||
**micro_fsl_frdm_k64f_defconfig**: Builds a microkernel for FSL FRDM K64F.
|
||||
|
||||
**micro_basic_cortex_m3_defconfig**: Builds a microkernel for Cortex-M3 processor on Qemu.
|
||||
|
||||
**nano_fsl_frdm_k64f_defconfig**: Builds a nanokenrel FSL FRDM K64F.
|
||||
|
||||
**nano_basic_cortex_m3_defconfig**: Builds a nanokernel for Cortex-M3 processor on Qemu.
|
||||
|
||||
Make Modifiers
|
||||
==============
|
||||
|
||||
**make V=0|1 [targets]**: Modifies verbosity of the project.
|
||||
|
||||
**0**: Quiet build, default.
|
||||
|
||||
**1**: Verbose build.
|
||||
|
||||
**2**: Gives the reason for rebuilding the target.
|
||||
|
||||
**make O=dir [targets]** Places all output files in :file:`dir`, including :file:`.config.`.
|
||||
|
||||
Other Environment Variables
|
||||
===========================
|
||||
|
||||
* :envvar:`USE_CCACHE` If set to 1, the build system uses the :program:`ccache` utility to speed
|
||||
up builds. :program:`ccache` must be installed on your development system. See the
|
||||
`CCACHE documentation`_.
|
||||
|
||||
.. _CCACHE documentation: https://ccache.samba.org/
|
||||
|
|
@ -10,4 +10,3 @@ The following reference guides might be needed during development.
|
|||
|
||||
api.rst
|
||||
kconfig/index.rst
|
||||
kbuild/kbuild.rst
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue