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>
The Particle mesh feather boards provide device-tree overlays that
allow individual applications to select the SPI peripheral to be
used for the pins associated with a specific labelled SPI device.
This is necessary because different peripheral instances have slightly
different properties.
Add BOARD_DIR to DTS_ROOTS so these shared files can be located when
included from application-specific overlays.
Signed-off-by: Peter A. Bigot <pab@pabigot.com>
Clean up some stray references to cmake in doc, boards and
samples that don't make explicit use of the zephyr app extension,
as well as other minor doc fixes.
Signed-off-by: Carles Cufi <carles.cufi@nordicsemi.no>
Make it clearer that the note about setting QEMU_BIN_PATH only applies
if you've got the Zephyr SDK installed.
Signed-off-by: Marti Bolivar <marti.bolivar@nordicsemi.no>
There are a few different places where alternatives for setting
environment variables are described. None of them is 100% complete, so
the results are likely to be confusing.
Make a single page on setting environment variables, how the zephyrrc
files work, how the zephyr-env scripts work, and some of the important
environment variables, with appropriate references elsewhere. (This is
inspired by the Arch wiki's excellent page on installing programs.)
Link to it from the getting started and application development pages
instead of repeating the information. This has the benefit of
shortening the getting started guide a bit more.
Add some concrete advice on checking the toolchain environment
variables in particular. This is a stumbling block for beginners.
Signed-off-by: Marti Bolivar <marti.bolivar@nordicsemi.no>
Add documentation for the new GUI configuration interface in the
Application Development guide.
Also update all the images, touch up the language a bit, and tweak some
minor stuff:
- Say *.conf instead of .conf to make it clearer that .conf isn't the
literal name
- Add a missing -D<board> argument when running cmake
- Use figure:: instead of image::. Comes out left-aligned and with
space between the images, which looks nicer.
- Explain what '- -' and '-*-' means in the terminal menuconfig.
tkinter isn't included by default in many Python installations, despite
being part of the Python standard library, so also add the required
packages to the Development Environment Setup section of the manual. Add
a note to the Application Development section as well, to help
debugging.
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
The directory tree description was missing a code-block shorthand so the
following lines weren't formatted correctly.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Move to a new guide which will expand on how to submit modules and how
to maintain them.
Also move topology documentation to repository management section where
it fits better.
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
Just like board's can be placed in out-of-tree BOARD_ROOT's, we now
support DeviceTree sources and bindings being placed in out-of-tree
DTS_ROOT's.
This required for out-of-tree drivers that use DeviceTree.
To implement this we get rid of various user-settable CMake variables
like DTS_APP_BINDINGS, DTS_APP_INCLUDE, and instead have ZEPHYR_BASE,
APPLICATION_SOURCE_DIR and out-of-tree directories conform to using
the same DTS_ROOT concept and directory structure.
Signed-off-by: Sebastian Bøe <sebastian.boe@nordicsemi.no>
Update the files which contain no license information with the
'Apache-2.0' SPDX license identifier. Many source files in the tree are
missing licensing information, which makes it harder for compliance
tools to determine the correct license.
By default all files without license information are under the default
license of Zephyr, which is Apache version 2.
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
Add a missing reference to how west is used to set ZEPHYR_MODULES in
without-west.rst, augmenting the application development guide a bit
to include this in the list of important variables, cleaning that up a
bit while we are here and adding some more west details.
Add a big fat warning in the getting started guide that using Zephyr
without west is not for the faint of heart.
Signed-off-by: Marti Bolivar <marti.bolivar@nordicsemi.no>
A note in the Modules (External projects) section indicated
that in the future it would be possible to do something that
can be already done.
So, let's clarify the note with how it can be done.
Signed-off-by: Alberto Escolar Piedras <alpi@oticon.com>
Linking to API material requires knowing the pecularities of how
doxygen, sphinx, and breathe work. In an attempt to hide some of this
we're preparing the current docs to allow use of configuration defaults
that will let us more simply use a default role that will hunt for a
reference target in the various domains that are available by using a
default "role" of "all". This will let us use the simple notation
`functionname` or `typename` without fully specifying the reference as
:c:func:`functionname`.
This patch cleans up exising docs that were (incorrectly) using single
backtics where double backtics should have been used, and also found
some typos (such as a space between the role name and the reference,
such as :file: `filename`, and a missing colon such as
c:func:`functionname`)
This is a start to address issue #14313
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Overhaul the Bluetooth documentation to split it into manageable units
and include additional information, such as architecture and tooling.
Signed-off-by: Carles Cufi <carles.cufi@nordicsemi.no>
A new role :zephyr_file: is available that renders to a link to the file
or folder in GitHub. Find appropriate references using :file: and
convert to :zephyr_file: to take advantage of its linking capability.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
In-tree, all usage of 'set_conf_file' is implementing the same
pattern (with some inconsequential differences).
To reduce copy-paste and get closer to dropping support for
'set_conf_file', we include this pattern into the built-in set of
patterns.
'set_conf_file' is causing issues for future extensions,
e.g. multi-image support, and is also the source of a lot of
duplicated code.
Note support for 'set_conf_file' is not dropped, it is only marked as
deprecated.
Signed-off-by: Sebastian Bøe <sebastian.boe@nordicsemi.no>
Remove most unnecessary instances of `export` and `cmake` use that can
instead be replaced with `zephyr-app-commands` or similar. This is to
avoid documentation using different mechanisms to describe the same
actions and in preparation for documenting `west build` everywhere.
Signed-off-by: Carles Cufi <carles.cufi@nordicsemi.no>
Document the build system integration with west and any projects managed
by it.
Signed-off-by: Carles Cufi <carles.cufi@nordicsemi.no>
Signed-off-by: Torsten Rasmussen <torsten.rasmussen@nordicsemi.no>
Overhaul the west documentation so that it matches the model that is
currently implemented in the west repository.
This model is no longer subject to change in the short or mid term,
since it has been selected as the only viable one for multi-repo
management using west.
Signed-off-by: Carles Cufi <carles.cufi@nordicsemi.no>
With the new theme we are able to have more section in the top level.
Move things around and expose the most important sections in the top
table of content.
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
Move to latest cmake version with many bug fixes and enhancements.
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
Signed-off-by: Carles Cufi <carles.cufi@nordicsemi.no>
Update Kconfiglib (and menuconfig, just to sync) to upstream revision
094f4a9622046, to add the commit below.
Save existing configuration to .<filename>.old in write_config()
Add a default-True 'save_old' flag to write_config(). If 'save_old' is
True and an existing configuration file is being overwritten, a copy
of the old configuration file is saved to .<filename>.old (e.g.
.config.old) in the same directory.
Errors are ignored, as the old configuration would usually just be a
nice-to-have, and not essential.
The same functionality could be added for minimal configuration files
and headers, but it's probably most useful for configuration files.
Other changes:
- Parsing performance is improved a bit
- scripts/kconfig/kconfig.py now prints the path to the merged
configuration in zephyr/.config, to make it a bit easier to
discover.
Fixes: #2907
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
Added basic working details of code/data/bss relocation feature,
how to use with examples & code sample details
Signed-off-by: Varun Sharma <varun.sharma@intel.com>
In order to clarify their use, add a brief description of the Device
Tree `aliases` and `chosen` nodes and their use in Zephyr.
Signed-off-by: Carles Cufi <carles.cufi@nordicsemi.no>
The newly proposed script must have report mode implemented
in them since they are less verbose warnings and helpful
in automated CI when throwing warnings to users.
Also, fixup mailing list links to follow .rst rules for
documentation using bullets while rectifying unwanted bold text.
Signed-off-by: Himanshu Jha <himanshujha199640@gmail.com>
Allow user to add externally built hex files to the cmake property
HEX_FILES_TO_MERGE. The hex files in this list will be merged
with the hex file generated when building the zephyr application.
This allows users to leverage the application configuration
available in Kconfig and CMake to help decide what hex file
should be merged with the zephyr application.
Signed-off-by: Håkon Øye Amundsen <haakon.amundsen@nordicsemi.no>
Add a new 'Kconfig tips and best practices' page that covers some
Kconfig best practices, tips, and arcana, like the following:
- What should be turned into a Kconfig symbol?
- Best practices and pitfalls for 'select'
- Factoring out common dependencies
- Kconfig shorthands
- Redundant defaults
- Explanations of various more obscure Kconfig features, like 'imply',
optional prompts, optional choices, and 'visible if'
Link the new page in the sidebar (under Developer Guides), the
application development primer, and the architecture and board porting
guides.
Perhaps other, more Zephyr-specific information could be added later on
as well, but this is a good start.
Include some other Kconfig-related documentation improvements as well:
- In the application development primer, give 'CONFIG_FOO=n' as the way
to set a bool symbol to 'n', instead of '# CONFIG_FOO is not set'.
That seems to be what people usually do in practice in Zephyr.
Explain why '# CONFIG_FOO is not set' works as well. There's a
technical reason for it, related to Make.
- Mention that the recommended syntax for referencing environment
variables is now $(FOO) (which uses the Kconfig preprocessor)
- Mention that the kconfiglib.py docstring has more in-depth
information about how symbol values are calculated.
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
When using an IDE (e.g. Eclipse, Qt Creator), the project name gets
displayed. This greatly simplifies the navigation between projects when
having many of them open at the same time. Naming every project "NONE"
defeats this functionality.
This patch tries to use sensible project names while not duplicating
too much of what is already represented in the path. This is done by
using the name of the directory the relevant CMakeLists.txt file is
stored in. To ensure unique project names in the samples (and again, in
the tests folder) folder, small manual adjustments have been done.
Signed-off-by: Reto Schneider <code@reto-schneider.ch>
- Fix a few errors and bits of stale information in "Creating an
Application", also adding additional cross-references.
- Consolidate some of the steps to help users create CMakeLists.txt
correctly by unambiguously putting target_sources() after the
boilerplate include.
- Split the description of the important build system variables into
its own section and add more context for what they do.
- Add whitespace warning
Signed-off-by: Marti Bolivar <marti@foundries.io>
Put the Developer Guides after the Getting Started guide, and make
sure the Application Development Primer is the first item in the
Developer Guides. Make some other ordering adjustments as well.
These changes collectively make for a more logical order for linearly
reading through the Zephyr documentation for the average user.
"Average user" here is defined as a person who wants to:
1. learn what Zephyr is and its distinguishing features
2. install a Zephyr development environment, building/running hello
world
3. learn the basics of how Zephyr applications are structured
4. start diving deeper
This privileges "users" over "developers", i.e. it pushes sections
related to Zephyr's internals and how to edit them down lower in the
order.
Signed-off-by: Marti Bolivar <marti@foundries.io>
The $srctree environment variable gives the path relative to which
'(o)source' statements work (the current directory is used if $srctree
is unset). It is set to $ZEPHYR_BASE in cmake/kconfig.cmake, so there's
no need to qualify the source of Kconfig.zephyr in sample Kconfig files
(or in external projects).
All 'source's in Zephyr assume that the Zephyr root directory is used as
the srctree as well, and would break otherwise.
Remove the $(ZEPHYR_BASE)s to make it clearer that all 'source'
statements work relative to the Zephyr root. There was some user
confusion on IRC.
Also explain how things work in the documentation.
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
The Zephyr configuration system uses many different files in many
different formats. It makes it a lot easier for users to understand
what these files do if when we use the correct file extensions.
To this end we rename the dts.fixup files to the correct file
extension '.h'.
This is a breaking change for out-of-tree fixup files. Such files will
be detected and given an appropriate error message.
Signed-off-by: Sebastian Bøe <sebastian.boe@nordicsemi.no>
Automatically detect the Kconfig file in it's conventional placement
${APPLICATION_SOURCE_DIR}/Kconfig and set KCONFIG_ROOT accordingly.
'Convention over configuration' is an imporant principle for
minimizing metadata and keeping things consistent. We use this
principle for instance with the file prj.conf.
This commit applies this principle to also re-direrct KCONFIG_ROOT.
Signed-off-by: Sebastian Bøe <sebastian.boe@nordicsemi.no>
Example of st_stm32 soc tree structure was instantiating
'stm32l0' dir as subdir of 'common' which is not the case.
Signed-off-by: Erwan Gouriou <erwan.gouriou@linaro.org>
With the new Kconfig preprocessor (described in
https://github.com/torvalds/linux/blob/master/Documentation/kbuild/
kconfig-macro-language.txt), the syntax for expanding environment
variables is $(FOO) rather than $FOO.
$(FOO) is a general preprocessor variable expansion, which falls back to
environment variables if the variable isn't set (like in Make). It can
also be used in prompts, 'comment's, etc.
The old syntax will probably be supported forever in Kconfiglib for
backwards compatibility, but might as well make it consistent now that
people might start using the preprocessor more.
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
Support using an alternate QEMU path for when we want to use a qemu
version not available in the SDK.
To use the alternate qemu version, export QEMU_BIN_PATH and point it
to the bin directory which contains the qemu executables.
For example:
export QEMU_BIN_PATH=/usr/local/bin
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
