michaelh/zephyr
1
0
Fork 0
Code Releases Activity

doc: Use west everywhere to build and flash

Browse source 
Instead of having a mix of west and CMake/ninja instructions for
building and flashing, document it using only west. This will help
clarify that west is the default build tool in Zephyr and should also
reduce confusion over what tool to use.
Note that the biggest change is changing the default in
doc/extensions/zephyr/application.py for :tool:, from all to west.

Signed-off-by: Carles Cufi <carles.cufi@nordicsemi.no>
This commit is contained in:
Carles Cufi 2019-08-25 19:06:22 +02:00 • committed by Carles Cufí
commit afcbc9992c
18 changed files with 55 additions and 95 deletions
Download patch file Download diff file Expand all files Collapse all files

5
boards/arm/frdm_k64f/doc/index.rst
View file

@ -237,12 +237,11 @@ the `OpenSDA J-Link Generic Firmware for V3.2 Bootloader`_. Note that Segger
does provide an OpenSDA J-Link Board-Specific Firmware for this board, however
it is not compatible with the DAPLink bootloader.
Add the argument ``-DOPENSDA_FW=jlink`` when you invoke ``west build`` or
``cmake`` to override the default runner from pyOCD to J-Link:
Add the argument ``-DOPENSDA_FW=jlink`` when you invoke ``west build`` to
override the default runner from pyOCD to J-Link:
.. zephyr-app-commands::
:zephyr-app: samples/hello_world
:tool: all
:board: frdm_k64f
:gen-args: -DOPENSDA_FW=jlink
:goals: build

5
boards/arm/frdm_kl25z/doc/index.rst
View file

@ -149,12 +149,11 @@ path.
Follow the instructions in :ref:`opensda-jlink-onboard-debug-probe` to program
the `OpenSDA J-Link FRDM-KL25Z Firmware`_.
Add the argument ``-DOPENSDA_FW=jlink`` when you invoke ``west build`` or
``cmake`` to override the default runner from pyOCD to J-Link:
Add the argument ``-DOPENSDA_FW=jlink`` when you invoke ``west build`` to
override the default runner from pyOCD to J-Link:
.. zephyr-app-commands::
:zephyr-app: samples/hello_world
:tool: all
:board: frdm_kl25z
:gen-args: -DOPENSDA_FW=jlink
:goals: build

5
boards/arm/frdm_kw41z/doc/index.rst
View file

@ -168,12 +168,11 @@ path.
Follow the instructions in :ref:`opensda-jlink-onboard-debug-probe` to program
the `OpenSDA J-Link FRDM-KW41Z Firmware`_.
Add the argument ``-DOPENSDA_FW=jlink`` when you invoke ``west build`` or
``cmake`` to override the default runner from pyOCD to J-Link:
Add the argument ``-DOPENSDA_FW=jlink`` when you invoke ``west build`` to
override the default runner from pyOCD to J-Link:
.. zephyr-app-commands::
:zephyr-app: samples/hello_world
:tool: all
:board: frdm_kw41z
:gen-args: -DOPENSDA_FW=jlink
:goals: build

5
boards/arm/hexiwear_k64/doc/index.rst
View file

@ -189,12 +189,11 @@ program the `OpenSDA DAPLink Hexiwear Firmware`_. Check that switches SW1 and
SW2 are **on**, and SW3 and SW4 are **off** to ensure K64F SWD signals are
connected to the OpenSDA microcontroller.
Add the argument ``-DOPENSDA_FW=daplink`` when you invoke ``west build`` or
``cmake`` to override the default runner from J-Link to pyOCD:
Add the argument ``-DOPENSDA_FW=daplink`` when you invoke ``west build`` to
override the default runner from J-Link to pyOCD:
.. zephyr-app-commands::
:zephyr-app: samples/hello_world
:tool: all
:board: hexiwear_k64
:gen-args: -DOPENSDA_FW=daplink
:goals: build

4
boards/arm/nrf52840_pca10059/doc/index.rst
View file

@ -146,7 +146,6 @@ device. Make sure ``nrfutil`` is installed before proceeding.
:app: zephyr/samples/basic/blinky
:board: nrf52840_pca10059
:goals: build
:tool: west
#. Package the application for the bootloader using ``nrfutil``:
@ -193,7 +192,6 @@ to the zephyr repository on your computer.
:app: mcuboot/boot/zephyr
:board: nrf52840_pca10059
:build-dir: mcuboot
:tool: west
:goals: build
#. Package the application for the bootloader using ``nrfutil``:
@ -236,7 +234,6 @@ over Bluetooth).
:app: zephyr/samples/subsys/mgmt/mcumgr/smp_svr
:board: nrf52840_pca10059
:build-dir: smp_svr
:tool: west
:goals: build
#. Sign ``smp_svr`` for chain-loading by MCUboot.
@ -275,7 +272,6 @@ name.
:board: nrf52840_pca10059
:build-dir: blinky
:goals: build
:tool: west
:gen-args: -DCONFIG_BOOTLOADER_MCUBOOT=y
You can then sign and flash it using the steps above.

1
boards/arm/stm32mp157c_dk2/doc/stm32mp157_dk2.rst
View file

@ -270,7 +270,6 @@ install `stm32mp1 developer package`_.
.. zephyr-app-commands::
:zephyr-app: samples/hello_world
:tool: all
:board: stm32mp157_dk2
:goals: debug

5
boards/arm/twr_ke18f/doc/index.rst
View file

@ -161,12 +161,11 @@ path.
Follow the instructions in :ref:`opensda-jlink-onboard-debug-probe` to program
the `OpenSDA J-Link Firmware for TWR-KE18F`_.
Add the argument ``-DOPENSDA_FW=jlink`` when you invoke ``west build`` or
``cmake`` to override the default runner from pyOCD to J-Link:
Add the argument ``-DOPENSDA_FW=jlink`` when you invoke ``west build`` to
override the default runner from pyOCD to J-Link:
.. zephyr-app-commands::
:zephyr-app: samples/hello_world
:tool: all
:board: twr_ke18f
:gen-args: -DOPENSDA_FW=jlink
:goals: build

4
boards/shields/frdm_cr20a/doc/index.rst
View file

@ -53,12 +53,10 @@ For more information about the MCR20A SoC and FRDM-CR20A board:
Programming
***********
Set ``-DSHIELD=frdm_cr20a`` when you invoke ``west build`` or ``cmake`` in your
Zephyr application. For example:
Set ``-DSHIELD=frdm_cr20a`` when you invoke ``west build``. For example:
.. zephyr-app-commands::
:zephyr-app: samples/net/wpanusb
:tool: all
:board: frdm_k64f
:shield: frdm_cr20a
:goals: build

3
boards/shields/frdm_kw41z/doc/index.rst
View file

@ -53,12 +53,11 @@ host controller interface (HCI):
#. Attach the FRDM-KW41Z to the Arduino header on your selected main board,
such as :ref:`mimxrt1050_evk` or :ref:`frdm_k64f`.
#. Set ``-DSHIELD=frdm_kw41z`` when you invoke ``west build`` or ``cmake`` in
#. Set ``-DSHIELD=frdm_kw41z`` when you invoke ``west build`` in
your Zephyr bluetooth application. For example,
.. zephyr-app-commands::
:zephyr-app: samples/bluetooth/peripheral_hr
:tool: all
:board: frdm_k64f
:shield: frdm_kw41z
:goals: build

1
boards/x86/acrn/doc/index.rst
View file

@ -58,7 +58,6 @@ On the Zephyr Build System
:zephyr-app: samples/hello_world
:board: acrn
:goals: build
:tool: all
This will build the application ELF binary in
``samples/hello_world/build/zephyr/zephyr.elf``.

1
boards/x86/gpmrb/doc/index.rst
View file

@ -36,7 +36,6 @@ application for the GP MRB:
.. zephyr-app-commands::
:zephyr-app: samples/hello_world
:tool: all
:board: gpmrb
:goals: build

1
boards/x86/up_squared/doc/index.rst
View file

@ -243,7 +243,6 @@ Build Zephyr application
.. zephyr-app-commands::
:zephyr-app: samples/hello_world
:tool: all
:board: up_squared
:goals: build

42
doc/application/index.rst
View file

@ -287,8 +287,8 @@ should know about.
.. _build_an_application:
Build an Application
********************
Building an Application
***********************
The Zephyr build system compiles and links all components of an application
into a single application image that can be run on simulated hardware or real
@ -303,16 +303,46 @@ The second stage runs the native build tool to actually build the
source files and generate an image. To learn more about these concepts refer to
the `CMake introduction`_ in the official CMake documentation.
As described in :ref:`getting_started_cmake`, you can choose to invoke ``cmake``
directly or to use :ref:`west <west>`, Zephyr's meta-tool, which itself invokes
``cmake`` and the build tool behind the scenes.
On Linux and macOS you can choose between the ``make`` and ``ninja``
Although the default build tool in Zephyr is :std:ref:`west <west>`, Zephyr's
meta-tool, which invokes ``cmake`` and the underlying build tool (``ninja`` or
``make``) behind the scenes, you can also choose to invoke ``cmake`` directly if
you prefer. On Linux and macOS you can choose between the ``make`` and
``ninja``
generators (i.e. build tools), whereas on Windows you need to use ``ninja``,
since ``make`` is not supported on this platform.
For simplicity we will use ``ninja`` throughout this guide, and if you
choose to use ``west build`` to build your application know that it will
default to ``ninja`` under the hood.
As an example, let's build the Hello World sample for the ``reel_board``:
.. zephyr-app-commands::
:tool: all
:app: samples/hello_world
:board: reel_board
:goals: build
On Linux and macOS, you can also build with ``make`` instead of ``ninja``:
Using west:
- to use ``make`` just once, add ``-- -G"Unix Makefiles"`` to the west build
command line; see the :ref:`west build <west-building-generator>`
documentation for an example.
- to use ``make`` by default from now on, run ``west config build.generator
"Unix Makefiles"``.
Using CMake directly:
.. zephyr-app-commands::
:tool: cmake
:app: samples/hello_world
:generator: make
:host-os: unix
:board: reel_board
:goals: build
Basics
======

4
doc/extensions/zephyr/application.py
View file

@ -30,7 +30,7 @@ class ZephyrAppCommandsDirective(Directive):
\:tool:
which tool to use. Valid options are currently 'cmake', 'west' and 'all'.
The default is 'all'.
The default is 'west'.
\:app:
path to the application to build.
@ -123,7 +123,7 @@ class ZephyrAppCommandsDirective(Directive):
# Parse directive options. Don't use os.path.sep or os.path.join here!
# That would break if building the docs on Windows.
tool = self.options.get('tool', 'all').lower()
tool = self.options.get('tool', 'west').lower()
app = self.options.get('app', None)
zephyr_app = self.options.get('zephyr-app', None)
cd_into = 'cd-into' in self.options

55
doc/getting_started/index.rst
View file

@ -157,23 +157,8 @@ Build and Run an Application
Next, build a sample Zephyr application. You can then flash and run it on real
hardware using any supported host system. Depending on your operating system,
you can also run it in emulation with QEMU or as a native POSIX application.
You can build applications by either running ``cmake`` directly or using the
:ref:`west build <west-building>` convenience wrapper.
.. _getting_started_cmake:
A Brief Note on the Zephyr Build System
=======================================
The Zephyr build system uses `CMake`_. CMake creates build systems in different
formats, called `generators`_. Zephyr supports the following generators:
* ``Unix Makefiles``: Supported on UNIX-like platforms (Linux, macOS).
* ``Ninja``: Supported on all platforms.
You can use any supported generator when running ``cmake`` directly or using
``west build``.
Additional information about building applications can be found in the
:ref:`build_an_application` section.
Build Hello World
=================
@ -205,47 +190,24 @@ inside the ``zephyrproject`` directory for a list of supported boards.
#. Build the Hello World sample for the ``reel_board``:
.. zephyr-app-commands::
:tool: all
:app: samples/hello_world
:board: reel_board
:goals: build
On Linux and macOS, you can also build with ``make`` instead of ``ninja``.
Using west:
- to use ``make`` just once, add ``-- -G"Unix Makefiles"`` to the west build
command line; see the :ref:`west build <west-building-generator>`
documentation for an example.
- to use ``make`` by default from now on, run ``west config build.generator
"Unix Makefiles"``.
Using CMake directly:
.. zephyr-app-commands::
:tool: cmake
:app: samples/hello_world
:generator: make
:host-os: unix
:board: reel_board
:goals: build
Either way, the main build products will be in :file:`build/zephyr`;
The main build products will be in :file:`build/zephyr`;
:file:`build/zephyr/zephyr.elf` is the Hello World application binary in ELF
format. Other binary formats, disassembly, and map files may be present
depending on your board.
The other sample applications in :zephyr_file:`samples` are documented in
:ref:`samples-and-demos`. If you want to re-use an existing build directory for
another board or application, you need to run the ``pristine`` build system
target or pass ``-p=auto`` to ``west build``.
another board or application, you need to pass ``-p=auto`` to ``west build``.
Run the Application by Flashing to a Board
==========================================
Most "real hardware" boards supported by Zephyr can be flashed by running
``west flash``, or by running ``ninja flash`` from the build
directory. However, this may require board-specific tool installation and
``west flash``. However, this may require board-specific tool installation and
configuration to work properly.
See :ref:`application_run` in the Application Development Primer and your
@ -261,7 +223,6 @@ To build and run Hello World using the x86 emulation board configuration
(``qemu_x86``), type:
.. zephyr-app-commands::
:tool: all
:zephyr-app: samples/hello_world
:host-os: unix
:board: qemu_x86
@ -284,7 +245,6 @@ need to install a 32 bit C library; see :ref:`native_posix_deps` for details.
First, build Hello World for ``native_posix``.
.. zephyr-app-commands::
:tool: all
:zephyr-app: samples/hello_world
:host-os: unix
:board: native_posix
@ -294,12 +254,7 @@ Next, run the application.
.. code-block:: console
# With west:
west build -t run
# With ninja:
ninja -Cbuild run
# or just run zephyr.exe directly:
./build/zephyr/zephyr.exe

2
doc/guides/coverage.rst
View file

@ -51,7 +51,6 @@ These steps will produce an HTML coverage report for a single application.
enable the configuration manually:
.. zephyr-app-commands::
:tool: all
:board: mps2_an385
:gen-args: -DCONFIG_COVERAGE=y
:goals: build
@ -110,7 +109,6 @@ You may postprocess these with your preferred tools. For example:
.. zephyr-app-commands::
:zephyr-app: samples/hello_world
:tool: cmake
:gen-args: -DCONFIG_COVERAGE=y
:host-os: unix
:board: native_posix

5
samples/basic/minimal/README.rst
View file

@ -31,7 +31,6 @@ following combinations are suggested:
.. zephyr-app-commands::
:zephyr-app: samples/basic/minimal
:tool: west
:host-os: unix
:board: reel_board
:build-dir: reel_board/mt/
@ -45,7 +44,6 @@ following combinations are suggested:
.. zephyr-app-commands::
:zephyr-app: samples/basic/minimal
:tool: west
:host-os: unix
:board: reel_board
:build-dir: reel_board/mt-no-preempt/
@ -59,7 +57,6 @@ following combinations are suggested:
.. zephyr-app-commands::
:zephyr-app: samples/basic/minimal
:tool: west
:host-os: unix
:board: reel_board
:build-dir: reel_board/mt-no-preempt-no-timers/
@ -73,7 +70,6 @@ following combinations are suggested:
.. zephyr-app-commands::
:zephyr-app: samples/basic/minimal
:tool: west
:host-os: unix
:board: reel_board
:build-dir: reel_board/no-mt/
@ -87,7 +83,6 @@ following combinations are suggested:
.. zephyr-app-commands::
:zephyr-app: samples/basic/minimal
:tool: west
:host-os: unix
:board: reel_board
:build-dir: reel_board/no-mt-no-timers/

2
samples/boards/intel_s1000_crb/i2s/i2s_app.rst
View file

@ -86,7 +86,6 @@ Audio Playback from a Host
.. zephyr-app-commands::
:zephyr-app: samples/boards/intel_s1000_crb/i2s
:tool: all
:board:
:goals: build
:gen-args: -DAUDIO_PLAY_FROM_HOST=Y
@ -97,7 +96,6 @@ Tone Sequence Playback
.. zephyr-app-commands::
:zephyr-app: samples/boards/intel_s1000_crb/i2s
:tool: all
:board:
:goals: build
:gen-args: -DAUDIO_PLAY_FROM_HOST=N