1.. _beyond-gsg:
2
3Beyond the Getting Started Guide
4################################
5
6The :ref:`getting_started` gives a straight-forward path to set up
7your Linux, macOS, or Windows environment for Zephyr development. In
8this document, we delve deeper into Zephyr development setup
9issues and alternatives.
10
11.. _python-pip:
12
13Python and pip
14**************
15
16Python 3 and its package manager, pip\ [#pip]_, are used extensively by Zephyr
17to install and run scripts required to compile and run Zephyr
18applications, set up and maintain the Zephyr development environment,
19and build project documentation.
20
21Depending on your operating system, you may need to provide the
22``--user`` flag to the ``pip3`` command when installing new packages. This is
23documented throughout the instructions.
24See `Installing Packages`_ in the Python Packaging User Guide for more
25information about pip\ [#pip]_, including `information on -\\-user`_.
26
27- On Linux, make sure ``~/.local/bin`` is at the front of your :envvar:`PATH`
28  :ref:`environment variable <env_vars>`, or programs installed with ``--user``
29  won't be found. Installing with ``--user`` avoids conflicts between pip
30  and the system package manager, and is the default on Debian-based
31  distributions.
32
33- On macOS, `Homebrew disables -\\-user`_.
34
35- On Windows, see the `Installing Packages`_ information on ``--user`` if you
36  require using this option.
37
38On all operating systems, pip's ``-U`` flag installs or updates the package if the
39package is already installed locally but a more recent version is available. It
40is good practice to use this flag if the latest version of a package is
41required.  (Check the :zephyr_file:`scripts/requirements.txt` file to
42see if a specific Python package version is expected.)
43
44Advanced Platform Setup
45***********************
46
47Here are some alternative instructions for more advanced platform setup
48configurations for supported development platforms:
49
50.. toctree::
51   :maxdepth: 1
52
53   Linux setup alternatives <getting_started/installation_linux.rst>
54   macOS setup alternatives <getting_started/installation_mac.rst>
55   Windows setup alternatives <getting_started/installation_win.rst>
56
57.. _gs_toolchain:
58
59Install a Toolchain
60*******************
61
62Zephyr binaries are compiled and linked by a *toolchain* comprised of
63a cross-compiler and related tools which are different from the compiler
64and tools used for developing software that runs natively on your host
65operating system.
66
67You can install the :ref:`Zephyr SDK <toolchain_zephyr_sdk>` to get toolchains for all
68supported architectures, or install an :ref:`alternate toolchain <toolchains>`
69recommended by the SoC vendor or a specific board (check your specific
70:ref:`board-level documentation <boards>`).
71
72You can configure the Zephyr build system to use a specific toolchain by
73setting :ref:`environment variables <env_vars>` such as
74:envvar:`ZEPHYR_TOOLCHAIN_VARIANT <{TOOLCHAIN}_TOOLCHAIN_PATH>` to a supported
75value, along with additional variable(s) specific to the toolchain variant.
76
77.. _gs_toolchain_update:
78
79Updating the Zephyr SDK toolchain
80*********************************
81
82When updating Zephyr SDK, check whether the :envvar:`ZEPHYR_TOOLCHAIN_VARIANT`
83or :envvar:`ZEPHYR_SDK_INSTALL_DIR` environment variables are already set.
84
85* If the variables are not set, the latest compatible version of Zephyr SDK will be selected
86  by default. Proceed to next step without making any changes.
87
88* If :envvar:`ZEPHYR_TOOLCHAIN_VARIANT` is set, the corresponding toolchain will be selected
89  at build time. Zephyr SDK is identified by the value ``zephyr``.
90  If the :envvar:`ZEPHYR_TOOLCHAIN_VARIANT` environment variable is not ``zephyr``, then either
91  unset it or change its value to ``zephyr`` to make sure Zephyr SDK is selected.
92
93* If the :envvar:`ZEPHYR_SDK_INSTALL_DIR` environment variable is set, it will override
94  the default lookup location for Zephyr SDK. If you install Zephyr SDK to one
95  of the :ref:`recommended locations <toolchain_zephyr_sdk_bundle_variables>`,
96  you can unset this variable. Otherwise, set it to your chosen install location.
97
98For more information about these environment variables in Zephyr, see :ref:`env_vars_important`.
99
100Cloning the Zephyr Repositories
101*******************************
102
103The Zephyr project source is maintained in the `GitHub zephyr repo
104<https://github.com/zephyrproject-rtos/zephyr>`_. External modules used
105by Zephyr are found in the parent `GitHub Zephyr project
106<https://github.com/zephyrproject-rtos/>`_.  Because of these
107dependencies, it's convenient to use the Zephyr-created :ref:`west
108<west>` tool to fetch and manage the Zephyr and external module source
109code.  See :ref:`west-basics` for more details.
110
111Once your development tools are installed, use :ref:`west` to create,
112initialize, and download sources from the zephyr and external module
113repos.  We'll use the name ``zephyrproject``, but you can choose any
114name that does not contain a space anywhere in the path.
115
116.. code-block:: console
117
118   west init zephyrproject
119   cd zephyrproject
120   west update
121
122The ``west update`` command fetches and keeps :ref:`modules` in the
123:file:`zephyrproject` folder in sync with the code in the local zephyr
124repo.
125
126.. warning::
127
128   You must run ``west update`` any time the :file:`zephyr/west.yml`
129   changes, caused, for example, when you pull the :file:`zephyr`
130   repository, switch branches in it, or perform a ``git bisect`` inside of
131   it.
132
133Keeping Zephyr updated
134======================
135
136To update the Zephyr project source code, you need to get the latest
137changes via ``git``. Afterwards, run ``west update`` as mentioned in
138the previous paragraph.
139
140.. code-block:: console
141
142   # replace zephyrproject with the path you gave west init
143   cd zephyrproject/zephyr
144   git pull
145   west update
146
147Export Zephyr CMake package
148***************************
149
150The :ref:`cmake_pkg` can be exported to CMake's user package registry if it has
151not already been done as part of :ref:`getting_started`.
152
153.. _gs-board-aliases:
154
155Board Aliases
156*************
157
158Developers who work with multiple boards may find explicit board names
159cumbersome and want to use aliases for common targets.  This is
160supported by a CMake file with content like this:
161
162.. code-block:: cmake
163
164   # Variable foo_BOARD_ALIAS=bar replaces BOARD=foo with BOARD=bar and
165   # sets BOARD_ALIAS=foo in the CMake cache.
166   set(pca10028_BOARD_ALIAS nrf51dk/nrf51822)
167   set(pca10056_BOARD_ALIAS nrf52840dk/nrf52840)
168   set(k64f_BOARD_ALIAS frdm_k64f)
169   set(sltb004a_BOARD_ALIAS efr32mg_sltb004a)
170
171and specifying its location in :envvar:`ZEPHYR_BOARD_ALIASES`.  This
172enables use of aliases ``pca10028`` in contexts like
173``cmake -DBOARD=pca10028`` and ``west -b pca10028``.
174
175Build and Run an Application
176****************************
177
178You can build, flash, and run Zephyr applications on real
179hardware using a supported host system. Depending on your operating system,
180you can also run it in emulation with QEMU, or as a native application with
181:ref:`native_sim <native_sim>`.
182Additional information about building applications can be found in the
183:ref:`build_an_application` section.
184
185Build Blinky
186============
187
188Let's build the :zephyr:code-sample:`blinky` sample application.
189
190Zephyr applications are built to run on specific hardware, called a
191"board"\ [#board_misnomer]_. We'll use the Phytec :ref:`reel_board
192<reel_board>` here, but you can change the ``reel_board`` build target
193to another value if you have a different board. See :ref:`boards` or run
194``west boards`` from anywhere inside the ``zephyrproject`` directory for
195a list of supported boards.
196
197#. Go to the zephyr repository:
198
199   .. code-block:: console
200
201      cd zephyrproject/zephyr
202
203#. Build the blinky sample for the ``reel_board``:
204
205   .. zephyr-app-commands::
206      :zephyr-app: samples/basic/blinky
207      :board: reel_board
208      :goals: build
209
210The main build products will be in :file:`build/zephyr`;
211:file:`build/zephyr/zephyr.elf` is the blinky application binary in ELF
212format. Other binary formats, disassembly, and map files may be present
213depending on your board.
214
215The other sample applications in the :zephyr_file:`samples` folder are
216documented in :zephyr:code-sample-category:`samples`.
217
218.. note:: If you want to reuse an
219   existing build directory for another board or application, you need to
220   add the parameter ``-p=auto`` to ``west build`` to clean out settings
221   and artifacts from the previous build.
222
223Run the Application by Flashing to a Board
224==========================================
225
226Most hardware boards supported by Zephyr can be flashed by running
227``west flash``. This may require board-specific tool installation and
228configuration to work properly.
229
230See :ref:`application_run` and your specific board's documentation in
231:ref:`boards` for additional details.
232
233.. _setting-udev-rules:
234
235Setting udev rules
236===================
237
238Flashing a board requires permission to directly access the board
239hardware, usually managed by installation of the flashing tools.  On
240Linux systems, if the ``west flash`` command fails, you likely need to
241define udev rules to grant the needed access permission.
242
243Udev is a device manager for the Linux kernel and the udev daemon
244handles all user space events raised when a hardware device is added (or
245removed) from the system.  We can add a rules file to grant access
246permission by non-root users to certain USB-connected devices.
247
248The OpenOCD (On-Chip Debugger) project conveniently provides a rules
249file that defined board-specific rules for most Zephyr-supported
250arm-based boards, so we recommend installing this rules
251file by downloading it from their sourceforge repo, or if you've
252installed the Zephyr SDK there is a copy of this rules file in the SDK
253folder:
254
255* Either download the OpenOCD rules file and copy it to the right
256  location::
257
258     wget -O 60-openocd.rules https://sf.net/p/openocd/code/ci/master/tree/contrib/60-openocd.rules?format=raw
259     sudo cp 60-openocd.rules /etc/udev/rules.d
260
261* or copy the rules file from the Zephyr SDK folder::
262
263     sudo cp ${ZEPHYR_SDK_INSTALL_DIR}/sysroots/x86_64-pokysdk-linux/usr/share/openocd/contrib/60-openocd.rules /etc/udev/rules.d
264
265Then, in either case, ask the udev daemon to reload these rules::
266
267   sudo udevadm control --reload
268
269Unplug and plug in the USB connection to your board, and you should have
270permission to access the board hardware for flashing. Check your
271board-specific documentation (:ref:`boards`) for further information if
272needed.
273
274Run the Application in QEMU
275===========================
276
277On Linux and macOS, you can run Zephyr applications via emulation on your host
278system using `QEMU <https://www.qemu.org/>`_ when targeting either
279the x86 or ARM Cortex-M3 architectures. (QEMU is included with the Zephyr
280SDK installation.)
281
282On Windows, you need to install QEMU manually from
283`Download QEMU <https://www.qemu.org/download/#windows>`_. After installation,
284add path to QEMU installation folder to PATH environment variable.
285To enable QEMU in Test Runner (Twister) on Windows,
286:ref:`set the environment variable <env_vars>`
287``QEMU_BIN_PATH`` to the path of QEMU installation folder.
288
289For example, you can build and run the :zephyr:code-sample:`hello_world` sample using
290the x86 emulation board configuration (``qemu_x86``), with:
291
292.. zephyr-app-commands::
293   :zephyr-app: samples/hello_world
294   :host-os: unix
295   :board: qemu_x86
296   :goals: build run
297
298To exit QEMU, type :kbd:`Ctrl-a`, then :kbd:`x`.
299
300Use ``qemu_cortex_m3`` to target an emulated Arm Cortex-M3 sample.
301
302.. _gs_native:
303
304Run a Sample Application natively (Linux)
305=========================================
306
307You can compile some samples to run as host programs
308on Linux. See :ref:`native_sim` for more information. On 64-bit host operating systems, you
309need to install a 32-bit C library, or build targeting :ref:`native_sim/native/64<native_sim32_64>`.
310
311First, build Hello World for ``native_sim``.
312
313.. zephyr-app-commands::
314   :zephyr-app: samples/hello_world
315   :host-os: unix
316   :board: native_sim
317   :goals: build
318
319Next, run the application.
320
321.. code-block:: console
322
323   west build -t run
324   # or just run zephyr.exe directly:
325   ./build/zephyr/zephyr.exe
326
327Press :kbd:`Ctrl-C` to exit.
328
329You can run ``./build/zephyr/zephyr.exe --help`` to get a list of available
330options.
331
332This executable can be instrumented using standard tools, such as gdb or
333valgrind.
334
335.. rubric:: Footnotes
336
337.. [#pip]
338
339   pip is Python's package installer. Its ``install`` command first tries to
340   reuse packages and package dependencies already installed on your computer.
341   If that is not possible, ``pip install`` downloads them from the Python
342   Package Index (PyPI) on the Internet.
343
344   The package versions requested by Zephyr's :file:`requirements.txt` may
345   conflict with other requirements on your system, in which case you may
346   want to set up a virtualenv for Zephyr development.
347
348.. [#board_misnomer]
349
350   This has become something of a misnomer over time. While the target can be,
351   and often is, a microprocessor running on its own dedicated hardware
352   board, Zephyr also supports using QEMU to run targets built for other
353   architectures in emulation, targets which produce native host system
354   binaries that implement Zephyr's driver interfaces with POSIX APIs, and even
355   running different Zephyr-based binaries on CPU cores of differing
356   architectures on the same physical chip. Each of these hardware
357   configurations is called a "board," even though that doesn't always make
358   perfect sense in context.
359
360.. _information on -\\-user:
361 https://packaging.python.org/tutorials/installing-packages/#installing-to-the-user-site
362.. _Homebrew disables -\\-user:
363 https://docs.brew.sh/Homebrew-and-Python#note-on-pip-install---user
364.. _Installing Packages:
365 https://packaging.python.org/tutorials/installing-packages/
366