doc: update with CMake instructions
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
This commit is contained in:
Anas Nashif
Anas Nashif
parent
4c2d26098e
commit
602a14365d
8 changed files with 221 additions and 325 deletions
|
|
@ -144,7 +144,7 @@ and how to set up your development environment as introduced in the Zephyr
|
|||
https://www.zephyrproject.org/doc/getting_started/getting_started.html
|
||||
|
||||
The examples below use a Linux host environment for Zephyr development.
|
||||
You should be familiar with common developer tools such as Git and Make, and
|
||||
You should be familiar with common developer tools such as Git and CMake, and
|
||||
platforms such as GitHub.
|
||||
|
||||
If you haven't already done so, you'll need to create a (free) GitHub account
|
||||
|
|
@ -233,18 +233,15 @@ run the same tests the CI system runs, follow these steps from within your
|
|||
local Zephyr source working directory::
|
||||
|
||||
$ source zephyr-env.sh
|
||||
$ make host-tools
|
||||
$ export PREBUILT_HOST_TOOLS=${ZEPHYR_BASE}/bin
|
||||
$ export USE_CCACHE=1
|
||||
$ ./scripts/sanitycheck
|
||||
$ ./scripts/sanitycheck --ccache
|
||||
|
||||
The above will execute the basic sanitycheck script, which will run various
|
||||
kernel tests using the QEMU emulator. It will also do some build tests on
|
||||
various samples with advanced features that can't run in QEMU.
|
||||
|
||||
We highly recommend you run these tests locally to avoid any CI failures.
|
||||
Using CCACHE and pre-built host tools is optional, however it speeds up the
|
||||
execution time considerably.
|
||||
We highly recommend you run these tests locally to avoid any CI
|
||||
failures. Enabling ccache with --ccache is optional, but it will speed
|
||||
up the execution time considerably.
|
||||
|
||||
|
||||
Coding Style
|
||||
|
|
|
|||
|
|
@ -100,6 +100,7 @@ commands to generate the html content locally:
|
|||
|
||||
$ cd ~/zephyr
|
||||
$ source zephyr-env.sh
|
||||
$ cd doc
|
||||
$ make htmldocs
|
||||
|
||||
Depending on your development system, it will take about 15 minutes to
|
||||
|
|
|
|||
|
|
@ -32,14 +32,24 @@ An application in the simplest form has the following structure:
|
|||
configuration option values are used; if no existing values are provided,
|
||||
the kernel's default configuration values are used.
|
||||
|
||||
* **Makefile**: This file tells the build system where to find the files
|
||||
* **CMakeLists.txt**: This file tells the build system where to find the files
|
||||
mentioned above, as well as the desired target board configuration.
|
||||
|
||||
Once the application has been defined, it can be built with a single ``make``
|
||||
call.
|
||||
The results of the build process are located in a sub-directory called
|
||||
:file:`outdir/BOARD`. This directory contains the files generated by the build
|
||||
process, the most notable of which are listed below.
|
||||
Once the application has been defined, project files for building it
|
||||
can be generated by calling cmake. The project files will be written
|
||||
to the directory where cmake was called, this directory is known as
|
||||
the build directory.
|
||||
|
||||
The most notable files in the build directory are listed below.
|
||||
|
||||
* The :file:`Makefile` (or :file:`build.ninja`) project file that can
|
||||
be invoked to build the application.
|
||||
|
||||
* The :file:`zephyr` directory is the working directory of the
|
||||
generated build system and where most generated files are located.
|
||||
|
||||
After the underlying build tool has been invoked the build output will
|
||||
be written to the :file:`zephyr` directory.
|
||||
|
||||
* The :file:`.config` file that contains the configuration settings
|
||||
used to build the application.
|
||||
|
|
@ -51,14 +61,13 @@ process, the most notable of which are listed below.
|
|||
kernel binary.
|
||||
|
||||
|
||||
|
||||
Application Structure
|
||||
*********************
|
||||
|
||||
|
||||
Create one directory for your application and a sub-directory for the
|
||||
application's source code; this makes it easier to organize directories and
|
||||
files in the structure that the kernel expects.
|
||||
application's source code; this makes it easier to distinguish between
|
||||
project files and source code.
|
||||
|
||||
#. Create an application directory structure outside of the kernel's
|
||||
installation directory tree. Often this is your workspace directory.
|
||||
|
|
@ -95,28 +104,22 @@ files in the structure that the kernel expects.
|
|||
Application Definition
|
||||
**********************
|
||||
|
||||
An application is integrated into the build system by including the Makefile.inc
|
||||
file provided.
|
||||
An application is integrated into the build system with two lines of
|
||||
boilerplate code in it's :file:`CMakeLists.txt` file and by having the
|
||||
environment variable :makevar:`ZEPHYR_BASE` set.
|
||||
|
||||
.. code-block:: make
|
||||
.. code-block:: cmake
|
||||
|
||||
include $(ZEPHYR_BASE)/Makefile.inc
|
||||
include($ENV{ZEPHYR_BASE}/cmake/app/boilerplate.cmake NO_POLICY_SCOPE)
|
||||
project(NONE)
|
||||
|
||||
The following predefined variables configure the development project:
|
||||
|
||||
* :makevar:`ZEPHYR_BASE`: Sets the path to the kernel's base directory.
|
||||
This variable is usually set by the :file:`zephyr_env.sh` script.
|
||||
It can be used to get the kernel's base directory, as used in the
|
||||
Makefile.inc inclusion above, or it can be overridden to select an
|
||||
specific instance of the kernel.
|
||||
|
||||
* :makevar:`PROJECT_BASE`: Provides the developer's application project
|
||||
directory path. It is set by the :file:`Makefile.inc` file.
|
||||
|
||||
* :makevar:`SOURCE_DIR`: Overrides the default value for the application's
|
||||
source code directory. The developer source code directory is set to
|
||||
:file:`$(PROJECT_BASE)/src/` by default. This directory name should end
|
||||
with slash **'/'**.
|
||||
* :makevar:`ZEPHYR_BASE`: Sets the path to the kernel's base
|
||||
directory. This variable is usually set by the
|
||||
:file:`zephyr_env.sh` script. It can be used to get the kernel's
|
||||
base directory, as used in the boilerplate above, or it can be
|
||||
overridden to select an specific instance of the kernel.
|
||||
|
||||
* :makevar:`BOARD`: Selects the board that the application's
|
||||
build will use for the default configuration.
|
||||
|
|
@ -125,155 +128,96 @@ The following predefined variables configure the development project:
|
|||
This file includes the kconfig configuration values that override the
|
||||
default configuration values.
|
||||
|
||||
* :makevar:`O`: Optional. Indicates the output directory that Kconfig uses.
|
||||
The output directory stores all the files generated during the build
|
||||
process. The default output directory is the :file:`$(PROJECT_BASE)/outdir`
|
||||
directory.
|
||||
|
||||
|
||||
Makefiles
|
||||
CMake
|
||||
*********
|
||||
|
||||
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.
|
||||
CMake is used to build Zephyr. A CMake build is done in two
|
||||
stages. The first stage is called Configuration, during Configuration
|
||||
the CMakeLists.txt build scripts are executed. At the end of
|
||||
Configuration, CMake will have an internal model of the Zephyr build
|
||||
and can generate build scripts that are native to the host platform.
|
||||
|
||||
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.
|
||||
CMake supports generating several build systems, but only Ninja and
|
||||
Make are tested and supported by Zephyr. After Configuration and
|
||||
Generation the user can begin the Build stage by executing the
|
||||
generated build system. The build system will for most code changes be
|
||||
able to re-build the application without involving CMake. But for
|
||||
certain configuration changes the Configuration step will need to be
|
||||
executed again, either automatically by the build system, or even
|
||||
manually in some cases.
|
||||
|
||||
.. _makefile_conventions:
|
||||
Zephyr uses CMake's concept of a 'target' to organize the build. A
|
||||
target can be an executable, a library, or a generated file. For
|
||||
application developers, the library target is the most important to
|
||||
understand. All source code that goes into a Zephyr build does so by
|
||||
being included in a library target, even application code.
|
||||
|
||||
Makefile Conventions
|
||||
====================
|
||||
Library targets have source code, that is added through CMakeLists.txt
|
||||
build scripts like this:
|
||||
|
||||
The following conventions restrict how to add modules and Makefiles to the
|
||||
build system. These conventions ensure the correct implementation of the
|
||||
recursive model.
|
||||
.. code-block:: cmake
|
||||
|
||||
* Each source code directory must contain a single Makefile. Directories
|
||||
without a Makefile are not considered source code directories.
|
||||
target_sources(app PRIVATE src/main.c)
|
||||
|
||||
* The scope of every Makefile is restricted to the contents of that directory.
|
||||
A Makefile can only make a direct reference to files and subdirectories on the
|
||||
same level or below.
|
||||
In the above code an existing library target named 'app' is being
|
||||
configured to have the source file src/main.c. The PRIVATE keyword
|
||||
indicates that we are modifying the internals of how the library is
|
||||
being built. Whereas using the keyword 'PUBLIC' would modify how other
|
||||
libraries that link with app are built. In this case, using PUBLIC
|
||||
here would cause libraries that link with app to also include the
|
||||
source file src/main.c, behaviour that we surely do not want. The
|
||||
'PUBLIC' keyword could however be useful when modifying the include
|
||||
paths of a target library.
|
||||
|
||||
* 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 object file name to the source file.
|
||||
Application CMakeLists.txt
|
||||
**************************
|
||||
|
||||
* Parent directories add their child directories into the recursion model.
|
||||
Every application must have a CMakeLists.txt file. The application
|
||||
CMakeLists.txt file is the entry point, or toplevel of the build
|
||||
system that builds the :file:`zephyr.elf` image. :file:`zephyr.elf`
|
||||
contains both the application and the kernel libraries.
|
||||
|
||||
* The root Makefile adds the directories in the kernel base directory into the
|
||||
recursion model.
|
||||
#. Open the :file:`CMakeLists.txt` and add the following mandatory
|
||||
entries using any text editor.
|
||||
|
||||
Adding Source Files
|
||||
===================
|
||||
|
||||
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
|
||||
|
||||
obj-y += <file>.o
|
||||
|
||||
.. note::
|
||||
|
||||
The same method applies for assembly files with the .S extension.
|
||||
|
||||
Source files can be added conditionally using configuration options. For
|
||||
example, if the 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:: none
|
||||
|
||||
obj-$(CONFIG_VAR) += <file>.o
|
||||
|
||||
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 build queue 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 build queue.
|
||||
|
||||
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:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
obj-$(CONFIG_VAR) += <directory_name>/
|
||||
|
||||
The subdirectory must contain its own Makefile following the rules described in
|
||||
:ref:`makefile_conventions`.
|
||||
|
||||
|
||||
Application Makefile
|
||||
********************
|
||||
|
||||
Create an application Makefile to define basic information, such as the board
|
||||
configuration used by the application. The build system uses the Makefile to
|
||||
build a :file:`zephyr.elf` image that contains both the application and the
|
||||
kernel libraries.
|
||||
|
||||
#. Open the :file:`Makefile` and add the following mandatory
|
||||
entries using any standard text editor.
|
||||
|
||||
.. note::
|
||||
|
||||
Ensure that there is a space before and after each ``=``.
|
||||
|
||||
#. Add the name of the default board configuration for your application on a
|
||||
#. Add the name of the board configuration for your application on a
|
||||
new line:
|
||||
|
||||
.. code-block:: make
|
||||
.. code-block:: cmake
|
||||
|
||||
BOARD = board_configuration_name
|
||||
set(BOARD qemu_x86)
|
||||
|
||||
The supported boards can be found in :ref:`boards`.
|
||||
|
||||
#. Add the name of the default kernel configuration file for your
|
||||
application on a new line:
|
||||
#. Include the mandatory boilerplate that integrates the application
|
||||
with the Zephyr build system on a new line:
|
||||
|
||||
.. code-block:: make
|
||||
.. code-block:: cmake
|
||||
|
||||
CONF_FILE ?= kernel_configuration_name
|
||||
include($ENV{ZEPHYR_BASE}/cmake/app/boilerplate.cmake NO_POLICY_SCOPE)
|
||||
project(NONE)
|
||||
|
||||
#. Include the mandatory :file:`Makefile` on a new line:
|
||||
#. Add any application source files to the 'app' target library:
|
||||
|
||||
.. code-block:: make
|
||||
.. code-block:: cmake
|
||||
|
||||
include ${ZEPHYR_BASE}/Makefile.inc
|
||||
target_sources(app PRIVATE src/main.c)
|
||||
|
||||
#. Save and close the :file:`Makefile`.
|
||||
#. Save and close the :file:`CMakeLists.txt`.
|
||||
|
||||
Below is an example CMakeList.txt:
|
||||
|
||||
Below is an example Makefile:
|
||||
.. code-block:: cmake
|
||||
|
||||
.. code-block:: make
|
||||
set(BOARD qemu_x86)
|
||||
|
||||
BOARD = qemu_x86
|
||||
CONF_FILE = prj.conf
|
||||
include($ENV{ZEPHYR_BASE}/cmake/app/boilerplate.cmake NO_POLICY_SCOPE)
|
||||
project(NONE)
|
||||
|
||||
include ${ZEPHYR_BASE}/Makefile.inc
|
||||
target_sources(app PRIVATE src/main.c)
|
||||
|
||||
.. _application_configuration:
|
||||
|
||||
|
|
@ -289,10 +233,10 @@ The available sources are (in order):
|
|||
|
||||
#. The application's current configuration. (i.e. The :file:`.config` file.)
|
||||
|
||||
#. The application's default configuration. (i.e. The :file:`.conf` file.)
|
||||
#. The application's default configuration. (Specified by ``CONF_FILE``, i.e. :file:`prj.conf`.)
|
||||
|
||||
#. The board configuration used by the application.
|
||||
(i.e. The board's :file:`.defconfig` file.)
|
||||
(i.e. The board's :file:`_defconfig` file.)
|
||||
|
||||
#. The kernel's default configuration.
|
||||
(i.e. One of the kernel's :file:`Kconfig` files.)
|
||||
|
|
@ -322,8 +266,10 @@ in :file:`$ZEPHYR_BASE/boards/ARCHITECTURE/BOARD/BOARD_defconfig`.
|
|||
|
||||
$ vim prj.conf
|
||||
|
||||
The default name is :file:`prj.conf`. The filename must match the
|
||||
``CONF_FILE`` entry in the application :file:`Makefile`.
|
||||
The application's default configuration is specified by
|
||||
``CONF_FILE``, ``CONF_FILE`` defaults to :file:`prj.conf` unless
|
||||
configured otherwise in the application :file:`CMakeLists.txt`
|
||||
file.
|
||||
|
||||
#. Edit the file and add the appropriate configuration entries.
|
||||
|
||||
|
|
@ -363,7 +309,7 @@ Configure the kernel options using a menu-driven interface. While you can add
|
|||
entries manually, using the configuration menu is a preferred method.
|
||||
|
||||
|
||||
#. Run the :command:`make menuconfig` rule to launch the menu-driven interface.
|
||||
#. After generating project files run :command:`ninja menuconfig` to launch the menu-driven interface.
|
||||
|
||||
a) In a terminal session, navigate to the application directory
|
||||
(:file:`~/app`).
|
||||
|
|
@ -372,7 +318,8 @@ entries manually, using the configuration menu is a preferred method.
|
|||
|
||||
.. code-block:: bash
|
||||
|
||||
$ make [BOARD=<type>] menuconfig
|
||||
$ cmake -Bbuild -H. -GNinja
|
||||
$ ninja -C build menuconfig
|
||||
|
||||
A question-based menu opens that allows you to set individual configuration
|
||||
options.
|
||||
|
|
@ -427,9 +374,8 @@ entries manually, using the configuration menu is a preferred method.
|
|||
Typically, you will save to the default file name unless you are
|
||||
experimenting with various configuration scenarios.
|
||||
|
||||
An :file:`outdir` directory is created in the application directory. The
|
||||
outdir directory contains symbolic links to files under
|
||||
:file:`\$ZEPHYR_BASE`.
|
||||
A :file:`zephyr` directory will have been created in the build
|
||||
directory.
|
||||
|
||||
.. note::
|
||||
|
||||
|
|
@ -439,7 +385,7 @@ entries manually, using the configuration menu is a preferred method.
|
|||
:file:`.config`, rename it to something other than :file:`.config`.
|
||||
|
||||
Kernel configuration files, such as the :file:`.config` file, are saved
|
||||
as hidden files in :file:`outdir`. To list all your kernel configuration
|
||||
as hidden files in :file:`zephyr`. To list all your kernel configuration
|
||||
files, enter :command:`ls -a` at the terminal prompt.
|
||||
|
||||
The following dialog opens, displaying the file name the configuration
|
||||
|
|
@ -488,16 +434,10 @@ entries manually, using the configuration menu is a preferred method.
|
|||
Application-Specific Code
|
||||
*************************
|
||||
|
||||
Application-specific source code files are normally added to the application's
|
||||
:file:`src` directory. If the application adds a large number of files the
|
||||
developer can group them into sub-directories under :file:`src`, to whatever
|
||||
depth is needed. The developer must supply a :file:`Makefile` for the
|
||||
:file:`src` directory, as well as for each sub-directory under :file:`src`.
|
||||
|
||||
.. note::
|
||||
|
||||
These Makefiles are distinct from the top-level application Makefile
|
||||
that appears in :file:`~/app`.
|
||||
Application-specific source code files are normally added to the
|
||||
application's :file:`src` directory. If the application adds a large
|
||||
number of files the developer can group them into sub-directories
|
||||
under :file:`src`, to whatever depth is needed.
|
||||
|
||||
Application-specific source code should not use symbol name prefixes that have
|
||||
been reserved by the kernel for its own use. For more information, see
|
||||
|
|
@ -505,58 +445,6 @@ been reserved by the kernel for its own use. For more information, see
|
|||
`Naming Conventions
|
||||
<https://github.com/zephyrproject-rtos/zephyr/wiki/Naming-Conventions>`_.
|
||||
|
||||
|
||||
The following requirements apply to all Makefiles in the :file:`src`
|
||||
directory, including any sub-directories it may have.
|
||||
|
||||
* During the build process, Kbuild identifies the source files to compile
|
||||
into object files by matching the file names identified in
|
||||
the application's Makefile(s).
|
||||
|
||||
.. important::
|
||||
|
||||
A source file that is not referenced by any Makefile is not included
|
||||
when the application is built.
|
||||
|
||||
* A Makefile cannot directly reference source code. It can only
|
||||
reference object files (:file:`.o` files) produced from source code files.
|
||||
|
||||
* A Makefile can only reference files in its own directory or in the
|
||||
sub-directories of that directory.
|
||||
|
||||
* A Makefile may reference multiple files from a single-line entry.
|
||||
However, a separate line must be used to reference each directory.
|
||||
|
||||
|
||||
|
||||
#. Create a directory structure for your source code in :file:`src`
|
||||
and add your source code files to it.
|
||||
|
||||
#. Create a :file:`Makefile` in the :file:`src` directory. Then create
|
||||
an additional :file:`Makefile` in each of the sub-directories under
|
||||
the :file:`src` directory, if any.
|
||||
|
||||
a) Use the following syntax to add file references:
|
||||
|
||||
.. code-block:: make
|
||||
|
||||
obj-y += file1.o file2.o
|
||||
|
||||
b) Use the following syntax to add directory references:
|
||||
|
||||
.. code-block:: make
|
||||
|
||||
obj-y += directory_name/**
|
||||
|
||||
|
||||
This example is taken from the :ref:`dining-philosophers-sample`. To examine this file in
|
||||
context, navigate to: :file:`$ZEPHYR_BASE/samples/philosophers/src`.
|
||||
|
||||
.. code-block:: make
|
||||
|
||||
obj-y = main.o
|
||||
|
||||
|
||||
Support for building third-party library code
|
||||
=============================================
|
||||
|
||||
|
|
@ -567,31 +455,22 @@ compiler flags that control the ABI targeted, making it important that both
|
|||
libraries and applications have certain compiler flags in common. It may also
|
||||
be useful for glue code to have access to Zephyr kernel header files.
|
||||
|
||||
To make it easier to integrate third-party components, the Zephyr build system
|
||||
includes a special build target, ``outputexports``, that takes a number of
|
||||
critical variables from the Zephyr build system and copies them into
|
||||
:file:`Makefile.export`. This allows the critical variables to be included by
|
||||
wrapper code for use in a third-party build system.
|
||||
To make it easier to integrate third-party components, the Zephyr
|
||||
build system has defined CMake functions that give application build
|
||||
scripts access to the zephyr compiler options. The functions are
|
||||
documented and defined in :file:`$ZEPHYR_BASE/cmake/extensions.cmake`
|
||||
and follow the naming convention ``zephyr_get_<type>_<format>``.
|
||||
|
||||
The following variables are recommended for use within the third-party build
|
||||
(see :file:`Makefile.export` for the complete list of exported variables):
|
||||
The following variables will often need to be exported to the
|
||||
third-party build system.
|
||||
|
||||
* ``CROSS_COMPILE``, together with related convenience variables to call the
|
||||
cross-tools directly (including ``AR``, ``AS``, ``CC``, ``CXX``, ``CPP``
|
||||
and ``LD``).
|
||||
* ``CMAKE_C_COMPILER``, ``CMAKE_AR``.
|
||||
|
||||
* ``ARCH`` and ``BOARD``, together with several variables that identify the
|
||||
Zephyr kernel version.
|
||||
|
||||
* ``KBUILD_CFLAGS``, ``NOSTDINC_FLAGS`` and ``ZEPHYRINCLUDE`` all of which
|
||||
should normally be added, in that order, to ``CFLAGS`` (or
|
||||
``CXXFLAGS``).
|
||||
|
||||
* All kconfig variables, allowing features of the library code to be
|
||||
enabled/disabled automatically based on the Zephyr kernel configuration.
|
||||
|
||||
:file:`samples/application_development/static_lib` is a sample project that demonstrates
|
||||
some of these features.
|
||||
:file:`samples/application_development/external_lib` is a sample
|
||||
project that demonstrates some of these features.
|
||||
|
||||
.. _build_an_application:
|
||||
|
||||
|
|
@ -605,13 +484,16 @@ hardware.
|
|||
|
||||
#. Navigate to the application directory :file:`~/app`.
|
||||
|
||||
#. Enter the following command to build the application's :file:`zephyr.elf`
|
||||
image using the configuration settings for the board type specified
|
||||
in the application's :file:`Makefile`.
|
||||
#. Enter the following commands to build the application's
|
||||
:file:`zephyr.elf` image using the configuration settings for the
|
||||
board type specified in the application's :file:`CMakeLists.txt`.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ make
|
||||
$ mkdir build
|
||||
$ cd build
|
||||
$ cmake -GNinja ..
|
||||
$ ninja
|
||||
|
||||
If desired, you can build the application using the configuration settings
|
||||
specified in an alternate :file:`.conf` file using the :code:`CONF_FILE`
|
||||
|
|
@ -620,15 +502,14 @@ hardware.
|
|||
|
||||
.. code-block:: console
|
||||
|
||||
$ make CONF_FILE=prj.alternate.conf
|
||||
|
||||
If desired, you can build the application for a different board type than the
|
||||
one specified in the application's :file:`Makefile` using the :code:`BOARD`
|
||||
parameter. For example:
|
||||
$ export CONF_FILE=prj.alternate.conf
|
||||
$ cmake -GNinja ..
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ make BOARD=arduino_101
|
||||
If desired, you can generate project files for a different board
|
||||
type than the one specified in the application's
|
||||
:file:`CMakeLists.txt` by defining the environment variable
|
||||
:code:`BOARD`.
|
||||
|
||||
Both the :code:`CONF_FILE` and :code:`BOARD` parameters can be specified
|
||||
when building the application.
|
||||
|
|
@ -640,7 +521,7 @@ Application development is usually fastest when changes are continually tested.
|
|||
Frequently rebuilding your application makes debugging less painful
|
||||
as the application becomes more complex. It's usually a good idea to
|
||||
rebuild and test after any major changes to the application's source files,
|
||||
Makefiles, or configuration settings.
|
||||
CMakeLists.txt files, or configuration settings.
|
||||
|
||||
.. important::
|
||||
|
||||
|
|
@ -654,23 +535,24 @@ the build system to rebuild the entire application from scratch with the
|
|||
following procedure:
|
||||
|
||||
|
||||
#. Navigate to the application directory :file:`~/app`.
|
||||
#. Navigate to the build directory :file:`~/app/build`.
|
||||
|
||||
#. Enter the following command to delete the application's generated files
|
||||
for the specified board type, except for the :file:`.config` file that
|
||||
contains the application's current configuration information.
|
||||
#. Enter the following command to delete the application's generated
|
||||
files, except for the :file:`.config` file that contains the
|
||||
application's current configuration information.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ make [BOARD=<type>] clean
|
||||
$ ninja clean
|
||||
|
||||
Alternatively, enter the following command to delete *all* generated files
|
||||
for *all* board types, including the :file:`.config` files that contain
|
||||
the application's current configuration information for those board types.
|
||||
Alternatively, enter the following command to delete *all*
|
||||
generated files, including the :file:`.config` files that contain
|
||||
the application's current configuration information for those board
|
||||
types.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ make pristine
|
||||
$ ninja pristine
|
||||
|
||||
#. Rebuild the application normally following the steps specified
|
||||
in `Build an Application`_ above.
|
||||
|
|
@ -721,13 +603,13 @@ run an application via QEMU:
|
|||
#. Open a terminal console on your host computer, and navigate to the
|
||||
application directory :file:`~/app`.
|
||||
|
||||
#. Enter the following command to build and run the application
|
||||
using a QEMU-supported board configuration, such as qemu_cortex_m3 or
|
||||
qemu_x86.
|
||||
#. After generating project files for a QEMU-supported board
|
||||
configuration, such as qemu_cortex_m3 or qemu_x86, enter the
|
||||
following command to build and run the application.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ make [BOARD=<type> ...] run
|
||||
$ ninja run
|
||||
|
||||
The Zephyr build system generates a :file:`zephyr.elf` image file
|
||||
and then begins running it in the terminal console.
|
||||
|
|
@ -758,7 +640,7 @@ The simplest way to debug an application running in QEMU is using the GNU
|
|||
Debugger and setting a local GDB server in your development system through QEMU.
|
||||
|
||||
You will need an ELF binary image for debugging purposes. The build system
|
||||
generates the image in the output directory. By default, the kernel binary name
|
||||
generates the image in the build directory. By default, the kernel binary name
|
||||
is :file:`zephyr.elf`. The name can be changed using a Kconfig option.
|
||||
|
||||
We will use the standard 1234 TCP port to open a :abbr:`GDB (GNU Debugger)`
|
||||
|
|
@ -782,11 +664,11 @@ The options used above have the following meaning:
|
|||
TCP port 1234.
|
||||
|
||||
To debug with QEMU and to start a GDB server and wait for a remote connect, run
|
||||
the following inside an application:
|
||||
the following inside the build directory of an application:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
make BOARD=qemu_x86 debugserver
|
||||
ninja debugserver
|
||||
|
||||
The build system will start a QEMU instance with the CPU halted at startup
|
||||
and with a GDB server instance listening at the TCP port 1234.
|
||||
|
|
|
|||
|
|
@ -70,7 +70,7 @@ To build an example application follow these steps:
|
|||
|
||||
.. code-block:: console
|
||||
|
||||
$ cd zephyr-project
|
||||
$ cd zephyr
|
||||
|
||||
#. Source the project environment file to set the project environment
|
||||
variables:
|
||||
|
|
@ -79,21 +79,36 @@ To build an example application follow these steps:
|
|||
|
||||
$ source zephyr-env.sh
|
||||
|
||||
#. Build the :ref:`hello_world` example project, enter:
|
||||
#. Generate project files for the :ref:`hello_world` example, enter:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ cd $ZEPHYR_BASE/samples/hello_world
|
||||
$ make
|
||||
$ mkdir build
|
||||
$ cd build
|
||||
$ cmake -GNinja ..
|
||||
|
||||
The above invocation of make will build the :ref:`hello_world` sample application
|
||||
using the default settings defined in the application's Makefile. You can
|
||||
build for a different board by defining the variable BOARD with one of the
|
||||
supported boards, for example:
|
||||
The above will generate project files that can build the
|
||||
:ref:`hello_world` sample application using the default settings
|
||||
defined in the application's CMakeLists.txt. To build the application,
|
||||
enter:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ make BOARD=arduino_101
|
||||
$ cd $ZEPHYR_BASE/samples/hello_world/build
|
||||
$ ninja
|
||||
|
||||
You can build for a different board by defining the variable BOARD
|
||||
with one of the supported boards, for example:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ cd $ZEPHYR_BASE/samples/hello_world
|
||||
$ export BOARD=arduino_101
|
||||
$ mkdir build_101
|
||||
$ cd build_101
|
||||
$ cmake -GNinja ..
|
||||
$ ninja
|
||||
|
||||
For further information on the supported boards go see
|
||||
:ref:`here <boards>`. Alternatively, run the following command to obtain a list
|
||||
|
|
@ -101,13 +116,12 @@ of the supported boards:
|
|||
|
||||
.. code-block:: console
|
||||
|
||||
$ make help
|
||||
$ ninja usage
|
||||
|
||||
Sample projects for different features of the project are available at
|
||||
at :file:`$ZEPHYR_BASE/samples`.
|
||||
After building an application successfully, the results can be found in the
|
||||
:file:`outdir` sub-directory under the application root directory, in a
|
||||
subdirectory that matches the BOARD string.
|
||||
directory where cmake was invoked.
|
||||
|
||||
The ELF binaries generated by the build system are named by default
|
||||
:file:`zephyr.elf`. This value can be overridden in the application
|
||||
|
|
@ -133,12 +147,23 @@ follow the steps below to build with any custom or 3rd party cross-compilers:
|
|||
$ unset ZEPHYR_GCC_VARIANT
|
||||
$ unset ZEPHYR_SDK_INSTALL_DIR
|
||||
|
||||
#. Build Kconfig and add it to path
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ mkdir ~/kconfig_build_dir && cd ~/kconfig_build_dir
|
||||
$ cmake -GNinja $ZEPHYR_BASE/scripts
|
||||
$ ninja
|
||||
$ echo "export PATH=$PWD/kconfig:\$PATH" >> $HOME/.bashrc
|
||||
$ bash
|
||||
$ which conf
|
||||
|
||||
#. We will use the `GCC ARM Embedded`_ compiler for this example, download the
|
||||
package suitable for your operating system from the `GCC ARM Embedded`_ website
|
||||
and extract it on your file system. This example assumes the compiler was
|
||||
extracted to: :file:`~/gcc-arm-none-eabi-5_3-2016q1/`.
|
||||
|
||||
#. Navigate to the main project directory:
|
||||
#. Navigate to the main project directory (where you cloned the Zephyr source from GitHub):
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
|
|
@ -151,29 +176,13 @@ follow the steps below to build with any custom or 3rd party cross-compilers:
|
|||
|
||||
$ source zephyr-env.sh
|
||||
|
||||
#. Build the example :ref:`hello_world` project and make sure you supply the
|
||||
CROSS_COMPILE on the command line, enter:
|
||||
#. Build the example :ref:`hello_world` project, enter:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ export GCCARMEMB_TOOLCHAIN_PATH="~/gcc-arm-none-eabi-5_3-2016q1/"
|
||||
$ export ZEPHYR_GCC_VARIANT=gccarmemb
|
||||
$ cd $ZEPHYR_BASE/samples/hello_world
|
||||
$ make CROSS_COMPILE=~/gcc-arm-none-eabi-5_3-2016q1/bin/arm-none-eabi- BOARD=arduino_due
|
||||
|
||||
The above will build the sample using the toolchain downloaded from
|
||||
`GCC ARM Embedded`_.
|
||||
|
||||
Alternatively, you can use the existing support for GCC ARM Embedded:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ export GCCARMEMB_TOOLCHAIN_PATH="~/gcc-arm-none-eabi-5_3-2016q1/"
|
||||
$ export ZEPHYR_GCC_VARIANT=gccarmemb
|
||||
$ cd zephyr-project
|
||||
$ source zephyr-env.sh
|
||||
$ cd $ZEPHYR_BASE/samples/hello_world
|
||||
$ make BOARD=arduino_due
|
||||
$ cmake -DBOARD=arduino_due -H$ZEPHYR_BASE/samples/hello_world -Bbld -GNinja && cmake --build bld
|
||||
|
||||
Running a Sample Application in QEMU
|
||||
====================================
|
||||
|
|
@ -189,13 +198,15 @@ type:
|
|||
|
||||
.. code-block:: console
|
||||
|
||||
$ make BOARD=qemu_x86 run
|
||||
$ cd $ZEPHYR_BASE/samples/hello_world
|
||||
$ export BOARD=qemu_x86
|
||||
$ mkdir qemu_build
|
||||
$ cd qemu_build
|
||||
$ cmake -GNinja ..
|
||||
$ ninja run
|
||||
|
||||
To run an application using the ARM qemu_cortex_m3 board configuration, type:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ make BOARD=qemu_cortex_m3 run
|
||||
To run an application using the ARM qemu_cortex_m3 board configuration
|
||||
specify the qemu_cortex_m3 board instead.
|
||||
|
||||
QEMU is not supported on all boards and SoCs. When developing for a specific
|
||||
hardware target you should always test on the actual hardware and should not
|
||||
|
|
|
|||
|
|
@ -52,16 +52,16 @@ Install the required packages in a Ubuntu host system with:
|
|||
|
||||
.. code-block:: console
|
||||
|
||||
$ sudo apt-get install git make gcc g++ ncurses-dev gperf ccache\
|
||||
doxygen dfu-util device-tree-compiler python3-ply python3-pip
|
||||
$ sudo apt-get install --no-install-recommends git ninja-build gperf \
|
||||
ccache doxygen dfu-util device-tree-compiler \
|
||||
python3-ply python3-pip python3-setuptools xz-utils file
|
||||
|
||||
Install the required packages in a Fedora host system with:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ sudo dnf group install "Development Tools"
|
||||
$ sudo dnf install git make gcc glibc-static gperf ccache\
|
||||
libstdc++-static ncurses-devel \
|
||||
$ sudo dnf install git ninja-build gperf ccache\
|
||||
doxygen dfu-util dtc python3-pip \
|
||||
python3-ply python3-yaml dfu-util dtc python3-pykwalify
|
||||
|
||||
|
|
@ -69,6 +69,15 @@ Install additional packages required for development with Zephyr::
|
|||
|
||||
$ pip3 install --user -r scripts/requirements.txt
|
||||
|
||||
Install exactly version 3.8.2 of CMake::
|
||||
|
||||
$ mkdir $HOME/work_dir && cd $HOME/work_dir
|
||||
$ wget https://cmake.org/files/v3.8/cmake-3.8.2-Linux-x86_64.sh
|
||||
$ yes | sh cmake-3.8.2-Linux-x86_64.sh | cat
|
||||
$ echo "export PATH=$PWD/cmake-3.8.2-Linux-x86_64/bin:\$PATH" >> $HOME/.bashrc
|
||||
$ bash
|
||||
$ cmake --version
|
||||
|
||||
.. _zephyr_sdk:
|
||||
|
||||
Installing the Zephyr Software Development Kit
|
||||
|
|
@ -118,8 +127,7 @@ Follow these steps to install the SDK on your Linux host system.
|
|||
|
||||
.. code-block:: console
|
||||
|
||||
$ chmod +x zephyr-sdk-<version>-setup.run
|
||||
$ ./zephyr-sdk-<version>-setup.run
|
||||
$ sh zephyr-sdk-<version>-setup.run
|
||||
|
||||
There is no need to use ``sudo`` if the SDK is installed in the current
|
||||
user's home directory.
|
||||
|
|
|
|||
|
|
@ -8,7 +8,7 @@ resource-constrained systems: from simple embedded environmental sensors and LED
|
|||
wearables to sophisticated smart watches and IoT wireless gateways.
|
||||
|
||||
The Zephyr kernel supports multiple architectures, including ARM Cortex-M, Intel
|
||||
x86, ARC, NIOS II, Tensilica Xtensa and RISC V. The full list of supported
|
||||
x86, ARC, NIOS II, Tensilica Xtensa, and RISC-V. The full list of supported
|
||||
boards can be found :ref:`here <boards>`.
|
||||
|
||||
Licensing
|
||||
|
|
|
|||
|
|
@ -60,6 +60,9 @@ which are not described here.
|
|||
Various programs and other files used to build and test Zephyr
|
||||
applications.
|
||||
|
||||
:file:`cmake`
|
||||
Additional build scripts needed to build Zephyr.
|
||||
|
||||
:file:`subsys`
|
||||
Subsystems of Zephyr, including:
|
||||
|
||||
|
|
|
|||
|
|
@ -23,10 +23,10 @@ the **bar** component of **foo**, you should copy the sample folder to
|
|||
|
||||
The sample contains the following files:
|
||||
|
||||
Makefile
|
||||
CMakeLists.txt
|
||||
|
||||
.. literalinclude:: ../../../samples/testing/integration/Makefile
|
||||
:language: Make
|
||||
.. literalinclude:: ../../../samples/testing/integration/CMakeLists.txt
|
||||
:language: CMake
|
||||
:linenos:
|
||||
|
||||
sample.yaml
|
||||
|
|
@ -41,12 +41,6 @@ prj.conf
|
|||
:language: text
|
||||
:linenos:
|
||||
|
||||
src/Makefile
|
||||
|
||||
.. literalinclude:: ../../../samples/testing/integration/src/Makefile
|
||||
:language: Make
|
||||
:linenos:
|
||||
|
||||
src/main.c
|
||||
|
||||
.. literalinclude:: ../../../samples/testing/integration/src/main.c
|
||||
|
|
@ -79,10 +73,10 @@ that interaction.
|
|||
The :file:`samples/testing/unit` folder contains an example for testing
|
||||
the net-buf api of Zephyr.
|
||||
|
||||
Makefile
|
||||
CMakeLists.txt
|
||||
|
||||
.. literalinclude:: ../../../samples/testing/unit/Makefile
|
||||
:language: Make
|
||||
.. literalinclude:: ../../../samples/testing/unit/CMakeLists.txt
|
||||
:language: CMake
|
||||
:linenos:
|
||||
|
||||
sample.yaml
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue