michaelh/zephyr
1
0
Fork 0
Code Releases Activity

doc: update with CMake instructions

Browse source 
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
This commit is contained in:
Anas Nashif 2017-10-31 08:35:24 -04:00 • committed by Anas Nashif
commit 602a14365d
8 changed files with 221 additions and 325 deletions
Download patch file Download diff file Expand all files Collapse all files

13
CONTRIBUTING.rst
View file

@ -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 https://www.zephyrproject.org/doc/getting_started/getting_started.html
The examples below use a Linux host environment for Zephyr development. 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. platforms such as GitHub.
If you haven't already done so, you'll need to create a (free) GitHub account 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:: local Zephyr source working directory::
$ source zephyr-env.sh $ source zephyr-env.sh
$ make host-tools $ ./scripts/sanitycheck --ccache
$ export PREBUILT_HOST_TOOLS=${ZEPHYR_BASE}/bin
$ export USE_CCACHE=1
$ ./scripts/sanitycheck
The above will execute the basic sanitycheck script, which will run various 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 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. various samples with advanced features that can't run in QEMU.
We highly recommend you run these tests locally to avoid any CI failures. We highly recommend you run these tests locally to avoid any CI
Using CCACHE and pre-built host tools is optional, however it speeds up the failures. Enabling ccache with --ccache is optional, but it will speed
execution time considerably. up the execution time considerably.
Coding Style Coding Style

1
doc/README.rst
View file

@ -100,6 +100,7 @@ commands to generate the html content locally:
$ cd ~/zephyr $ cd ~/zephyr
$ source zephyr-env.sh $ source zephyr-env.sh
$ cd doc
$ make htmldocs $ make htmldocs
Depending on your development system, it will take about 15 minutes to Depending on your development system, it will take about 15 minutes to

406
doc/application/application.rst
View file

@ -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, configuration option values are used; if no existing values are provided,
the kernel's default configuration values are used. 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. mentioned above, as well as the desired target board configuration.
Once the application has been defined, it can be built with a single ``make`` Once the application has been defined, project files for building it
call. can be generated by calling cmake. The project files will be written
The results of the build process are located in a sub-directory called to the directory where cmake was called, this directory is known as
:file:`outdir/BOARD`. This directory contains the files generated by the build the build directory.
process, the most notable of which are listed below.
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 * The :file:`.config` file that contains the configuration settings
used to build the application. used to build the application.
@ -51,14 +61,13 @@ process, the most notable of which are listed below.
kernel binary. kernel binary.
Application Structure Application Structure
********************* *********************
Create one directory for your application and a sub-directory for the Create one directory for your application and a sub-directory for the
application's source code; this makes it easier to organize directories and application's source code; this makes it easier to distinguish between
files in the structure that the kernel expects. project files and source code.
#. Create an application directory structure outside of the kernel's #. Create an application directory structure outside of the kernel's
installation directory tree. Often this is your workspace directory. installation directory tree. Often this is your workspace directory.
@ -95,28 +104,22 @@ files in the structure that the kernel expects.
Application Definition Application Definition
********************** **********************
An application is integrated into the build system by including the Makefile.inc An application is integrated into the build system with two lines of
file provided. 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: The following predefined variables configure the development project:
* :makevar:`ZEPHYR_BASE`: Sets the path to the kernel's base directory. * :makevar:`ZEPHYR_BASE`: Sets the path to the kernel's base
This variable is usually set by the :file:`zephyr_env.sh` script. directory. This variable is usually set by the
It can be used to get the kernel's base directory, as used in the :file:`zephyr_env.sh` script. It can be used to get the kernel's
Makefile.inc inclusion above, or it can be overridden to select an base directory, as used in the boilerplate above, or it can be
specific instance of the kernel. 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:`BOARD`: Selects the board that the application's * :makevar:`BOARD`: Selects the board that the application's
build will use for the default configuration. 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 This file includes the kconfig configuration values that override the
default configuration values. default configuration values.
* :makevar:`O`: Optional. Indicates the output directory that Kconfig uses. CMake
The output directory stores all the files generated during the build
process. The default output directory is the :file:`$(PROJECT_BASE)/outdir`
directory.
Makefiles
********* *********
Overview Overview
======== ========
The build system defines a set of conventions for the correct use of Makefiles CMake is used to build Zephyr. A CMake build is done in two
in the kernel source directories. The correct use of Makefiles is driven by the stages. The first stage is called Configuration, during Configuration
concept of recursion. 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 CMake supports generating several build systems, but only Ninja and
code and any subdirectories to the build process. Each subdirectory follows Make are tested and supported by Zephyr. After Configuration and
the same principle. Developers can focus exclusively in their own work. They Generation the user can begin the Build stage by executing the
integrate their module with the build system by adding a very simple Makefile generated build system. The build system will for most code changes be
following the recursive model. 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 .. code-block:: cmake
build system. These conventions ensure the correct implementation of the
recursive model.
* Each source code directory must contain a single Makefile. Directories target_sources(app PRIVATE src/main.c)
without a Makefile are not considered source code directories.
* The scope of every Makefile is restricted to the contents of that directory. In the above code an existing library target named 'app' is being
A Makefile can only make a direct reference to files and subdirectories on the configured to have the source file src/main.c. The PRIVATE keyword
same level or below. 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 Application CMakeLists.txt
build system finds the source file that generates the object file by matching **************************
the object file name to the source file.
* 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 #. Open the :file:`CMakeLists.txt` and add the following mandatory
recursion model. entries using any text editor.
Adding Source Files #. Add the name of the board configuration for your application on a
===================
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
new line: 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`. The supported boards can be found in :ref:`boards`.
#. Add the name of the default kernel configuration file for your #. Include the mandatory boilerplate that integrates the application
application on a new line: 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 include($ENV{ZEPHYR_BASE}/cmake/app/boilerplate.cmake NO_POLICY_SCOPE)
CONF_FILE = prj.conf project(NONE)
include ${ZEPHYR_BASE}/Makefile.inc target_sources(app PRIVATE src/main.c)
.. _application_configuration: .. _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 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. #. 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. #. The kernel's default configuration.
(i.e. One of the kernel's :file:`Kconfig` files.) (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 $ vim prj.conf
The default name is :file:`prj.conf`. The filename must match the The application's default configuration is specified by
``CONF_FILE`` entry in the application :file:`Makefile`. ``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. #. 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. 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 a) In a terminal session, navigate to the application directory
(:file:`~/app`). (:file:`~/app`).
@ -372,7 +318,8 @@ entries manually, using the configuration menu is a preferred method.
.. code-block:: bash .. 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 A question-based menu opens that allows you to set individual configuration
options. 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 Typically, you will save to the default file name unless you are
experimenting with various configuration scenarios. experimenting with various configuration scenarios.
An :file:`outdir` directory is created in the application directory. The A :file:`zephyr` directory will have been created in the build
outdir directory contains symbolic links to files under directory.
:file:`\$ZEPHYR_BASE`.
.. note:: .. 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`. :file:`.config`, rename it to something other than :file:`.config`.
Kernel configuration files, such as the :file:`.config` file, are saved 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. files, enter :command:`ls -a` at the terminal prompt.
The following dialog opens, displaying the file name the configuration 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 Code
************************* *************************
Application-specific source code files are normally added to the application's Application-specific source code files are normally added to the
:file:`src` directory. If the application adds a large number of files the application's :file:`src` directory. If the application adds a large
developer can group them into sub-directories under :file:`src`, to whatever number of files the developer can group them into sub-directories
depth is needed. The developer must supply a :file:`Makefile` for the under :file:`src`, to whatever depth is needed.
: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 should not use symbol name prefixes that have 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 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 `Naming Conventions
<https://github.com/zephyrproject-rtos/zephyr/wiki/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 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 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. 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 To make it easier to integrate third-party components, the Zephyr
includes a special build target, ``outputexports``, that takes a number of build system has defined CMake functions that give application build
critical variables from the Zephyr build system and copies them into scripts access to the zephyr compiler options. The functions are
:file:`Makefile.export`. This allows the critical variables to be included by documented and defined in :file:`$ZEPHYR_BASE/cmake/extensions.cmake`
wrapper code for use in a third-party build system. and follow the naming convention ``zephyr_get_<type>_<format>``.
The following variables are recommended for use within the third-party build The following variables will often need to be exported to the
(see :file:`Makefile.export` for the complete list of exported variables): third-party build system.
* ``CROSS_COMPILE``, together with related convenience variables to call the * ``CMAKE_C_COMPILER``, ``CMAKE_AR``.
cross-tools directly (including ``AR``, ``AS``, ``CC``, ``CXX``, ``CPP``
and ``LD``).
* ``ARCH`` and ``BOARD``, together with several variables that identify the * ``ARCH`` and ``BOARD``, together with several variables that identify the
Zephyr kernel version. Zephyr kernel version.
* ``KBUILD_CFLAGS``, ``NOSTDINC_FLAGS`` and ``ZEPHYRINCLUDE`` all of which :file:`samples/application_development/external_lib` is a sample
should normally be added, in that order, to ``CFLAGS`` (or project that demonstrates some of these features.
``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.
.. _build_an_application: .. _build_an_application:
@ -605,13 +484,16 @@ hardware.
#. Navigate to the application directory :file:`~/app`. #. Navigate to the application directory :file:`~/app`.
#. Enter the following command to build the application's :file:`zephyr.elf` #. Enter the following commands to build the application's
image using the configuration settings for the board type specified :file:`zephyr.elf` image using the configuration settings for the
in the application's :file:`Makefile`. board type specified in the application's :file:`CMakeLists.txt`.
.. code-block:: console .. code-block:: console
$ make $ mkdir build
$ cd build
$ cmake -GNinja ..
$ ninja
If desired, you can build the application using the configuration settings If desired, you can build the application using the configuration settings
specified in an alternate :file:`.conf` file using the :code:`CONF_FILE` specified in an alternate :file:`.conf` file using the :code:`CONF_FILE`
@ -620,15 +502,14 @@ hardware.
.. code-block:: console .. code-block:: console
$ make CONF_FILE=prj.alternate.conf
If desired, you can build the application for a different board type than the $ export CONF_FILE=prj.alternate.conf
one specified in the application's :file:`Makefile` using the :code:`BOARD` $ cmake -GNinja ..
parameter. For example:
.. code-block:: console If desired, you can generate project files for a different board
type than the one specified in the application's
$ make BOARD=arduino_101 :file:`CMakeLists.txt` by defining the environment variable
:code:`BOARD`.
Both the :code:`CONF_FILE` and :code:`BOARD` parameters can be specified Both the :code:`CONF_FILE` and :code:`BOARD` parameters can be specified
when building the application. 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 Frequently rebuilding your application makes debugging less painful
as the application becomes more complex. It's usually a good idea to 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, rebuild and test after any major changes to the application's source files,
Makefiles, or configuration settings. CMakeLists.txt files, or configuration settings.
.. important:: .. important::
@ -654,23 +535,24 @@ the build system to rebuild the entire application from scratch with the
following procedure: 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 #. Enter the following command to delete the application's generated
for the specified board type, except for the :file:`.config` file that files, except for the :file:`.config` file that contains the
contains the application's current configuration information. application's current configuration information.
.. code-block:: console .. code-block:: console
$ make [BOARD=<type>] clean $ ninja clean
Alternatively, enter the following command to delete *all* generated files Alternatively, enter the following command to delete *all*
for *all* board types, including the :file:`.config` files that contain generated files, including the :file:`.config` files that contain
the application's current configuration information for those board types. the application's current configuration information for those board
types.
.. code-block:: console .. code-block:: console
$ make pristine $ ninja pristine
#. Rebuild the application normally following the steps specified #. Rebuild the application normally following the steps specified
in `Build an Application`_ above. 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 #. Open a terminal console on your host computer, and navigate to the
application directory :file:`~/app`. application directory :file:`~/app`.
#. Enter the following command to build and run the application #. After generating project files for a QEMU-supported board
using a QEMU-supported board configuration, such as qemu_cortex_m3 or configuration, such as qemu_cortex_m3 or qemu_x86, enter the
qemu_x86. following command to build and run the application.
.. code-block:: console .. code-block:: console
$ make [BOARD=<type> ...] run $ ninja run
The Zephyr build system generates a :file:`zephyr.elf` image file The Zephyr build system generates a :file:`zephyr.elf` image file
and then begins running it in the terminal console. 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. 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 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. 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)` 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. TCP port 1234.
To debug with QEMU and to start a GDB server and wait for a remote connect, run 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 .. code-block:: bash
make BOARD=qemu_x86 debugserver ninja debugserver
The build system will start a QEMU instance with the CPU halted at startup 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. and with a GDB server instance listening at the TCP port 1234.

83
doc/getting_started/getting_started.rst
View file

@ -70,7 +70,7 @@ To build an example application follow these steps:
.. code-block:: console .. code-block:: console
$ cd zephyr-project $ cd zephyr
#. Source the project environment file to set the project environment #. Source the project environment file to set the project environment
variables: variables:
@ -79,21 +79,36 @@ To build an example application follow these steps:
$ source zephyr-env.sh $ 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 .. code-block:: console
$ cd $ZEPHYR_BASE/samples/hello_world $ 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 The above will generate project files that can build the
using the default settings defined in the application's Makefile. You can :ref:`hello_world` sample application using the default settings
build for a different board by defining the variable BOARD with one of the defined in the application's CMakeLists.txt. To build the application,
supported boards, for example: enter:
.. code-block:: console .. 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 For further information on the supported boards go see
:ref:`here <boards>`. Alternatively, run the following command to obtain a list :ref:`here <boards>`. Alternatively, run the following command to obtain a list
@ -101,13 +116,12 @@ of the supported boards:
.. code-block:: console .. code-block:: console
$ make help $ ninja usage
Sample projects for different features of the project are available at Sample projects for different features of the project are available at
at :file:`$ZEPHYR_BASE/samples`. at :file:`$ZEPHYR_BASE/samples`.
After building an application successfully, the results can be found in the After building an application successfully, the results can be found in the
:file:`outdir` sub-directory under the application root directory, in a directory where cmake was invoked.
subdirectory that matches the BOARD string.
The ELF binaries generated by the build system are named by default The ELF binaries generated by the build system are named by default
:file:`zephyr.elf`. This value can be overridden in the application :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_GCC_VARIANT
$ unset ZEPHYR_SDK_INSTALL_DIR $ 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 #. 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 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 and extract it on your file system. This example assumes the compiler was
extracted to: :file:`~/gcc-arm-none-eabi-5_3-2016q1/`. 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 .. 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 $ source zephyr-env.sh
#. Build the example :ref:`hello_world` project and make sure you supply the #. Build the example :ref:`hello_world` project, enter:
CROSS_COMPILE on the command line, enter:
.. code-block:: console .. code-block:: console
$ export GCCARMEMB_TOOLCHAIN_PATH="~/gcc-arm-none-eabi-5_3-2016q1/" $ export GCCARMEMB_TOOLCHAIN_PATH="~/gcc-arm-none-eabi-5_3-2016q1/"
$ export ZEPHYR_GCC_VARIANT=gccarmemb $ export ZEPHYR_GCC_VARIANT=gccarmemb
$ cd $ZEPHYR_BASE/samples/hello_world $ cmake -DBOARD=arduino_due -H$ZEPHYR_BASE/samples/hello_world -Bbld -GNinja && cmake --build bld
$ 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
Running a Sample Application in QEMU Running a Sample Application in QEMU
==================================== ====================================
@ -189,13 +198,15 @@ type:
.. code-block:: console .. 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: To run an application using the ARM qemu_cortex_m3 board configuration
specify the qemu_cortex_m3 board instead.
.. code-block:: console
$ make BOARD=qemu_cortex_m3 run
QEMU is not supported on all boards and SoCs. When developing for a specific 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 hardware target you should always test on the actual hardware and should not

20
doc/getting_started/installation_linux.rst
View file

@ -52,16 +52,16 @@ Install the required packages in a Ubuntu host system with:
.. code-block:: console .. code-block:: console
$ sudo apt-get install git make gcc g++ ncurses-dev gperf ccache\ $ sudo apt-get install --no-install-recommends git ninja-build gperf \
doxygen dfu-util device-tree-compiler python3-ply python3-pip 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: Install the required packages in a Fedora host system with:
.. code-block:: console .. code-block:: console
$ sudo dnf group install "Development Tools" $ sudo dnf group install "Development Tools"
$ sudo dnf install git make gcc glibc-static gperf ccache\ $ sudo dnf install git ninja-build gperf ccache\
libstdc++-static ncurses-devel \
doxygen dfu-util dtc python3-pip \ doxygen dfu-util dtc python3-pip \
python3-ply python3-yaml dfu-util dtc python3-pykwalify 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 $ 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: .. _zephyr_sdk:
Installing the Zephyr Software Development Kit 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 .. code-block:: console
$ chmod +x zephyr-sdk-<version>-setup.run $ sh zephyr-sdk-<version>-setup.run
$ ./zephyr-sdk-<version>-setup.run
There is no need to use ``sudo`` if the SDK is installed in the current There is no need to use ``sudo`` if the SDK is installed in the current
user's home directory. user's home directory.

2
doc/introduction/introducing_zephyr.rst
View file

@ -8,7 +8,7 @@ resource-constrained systems: from simple embedded environmental sensors and LED
wearables to sophisticated smart watches and IoT wireless gateways. wearables to sophisticated smart watches and IoT wireless gateways.
The Zephyr kernel supports multiple architectures, including ARM Cortex-M, Intel 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>`. boards can be found :ref:`here <boards>`.
Licensing Licensing

3
doc/kernel/overview/source_tree.rst
View file

@ -60,6 +60,9 @@ which are not described here.
Various programs and other files used to build and test Zephyr Various programs and other files used to build and test Zephyr
applications. applications.
:file:`cmake`
Additional build scripts needed to build Zephyr.
:file:`subsys` :file:`subsys`
Subsystems of Zephyr, including: Subsystems of Zephyr, including:

18
doc/subsystems/test/ztest.rst
View file

@ -23,10 +23,10 @@ the **bar** component of **foo**, you should copy the sample folder to
The sample contains the following files: The sample contains the following files:
Makefile CMakeLists.txt
.. literalinclude:: ../../../samples/testing/integration/Makefile .. literalinclude:: ../../../samples/testing/integration/CMakeLists.txt
:language: Make :language: CMake
:linenos: :linenos:
sample.yaml sample.yaml
@ -41,12 +41,6 @@ prj.conf
:language: text :language: text
:linenos: :linenos:
src/Makefile
.. literalinclude:: ../../../samples/testing/integration/src/Makefile
:language: Make
:linenos:
src/main.c src/main.c
.. literalinclude:: ../../../samples/testing/integration/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 :file:`samples/testing/unit` folder contains an example for testing
the net-buf api of Zephyr. the net-buf api of Zephyr.
Makefile CMakeLists.txt
.. literalinclude:: ../../../samples/testing/unit/Makefile .. literalinclude:: ../../../samples/testing/unit/CMakeLists.txt
:language: Make :language: CMake
:linenos: :linenos:
sample.yaml sample.yaml