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>
Document that the boilerplate code included in all applications must
now also include
cmake_minimum_required(VERSION 3.8.2)
Signed-off-by: Sebastian Bøe <sebastian.boe@nordicsemi.no>
Update the documentation to say that earlier defaults are preferred,
while explaining Kconfig.defconfig files.
Keep the section that covered the Zephyr prefer-later-defaults patch as
documentation for the behavior having changed. It will be linked in a
warning later.
Also add documentation explaining how to configure choices, including
using multiple definition locations to change a choice 'default'.
Document that 'range's can be added/overriden as well. This works
reliably now.
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
pyocd recently added support for python 3 so we can now remove the
python 2 package requirements. It also merged Zephyr thread awareness
upstream, so we can remove the reference to my pyocd pull request.
Tested debugging and flashing on Linux and Windows.
Signed-off-by: Maureen Helm <maureen.helm@nxp.com>
Try to clarify the scope of Device Tree vs Kconfig in order to allow
Zephyr users to identify where a particular configuration option when
developing an application, board support or SoC support.
Fixes#7230
Signed-off-by: Carles Cufi <carles.cufi@nordicsemi.no>
This resolves#5723 by adding support for assigning to Kconfig options
from the CMake CLI.
CMake CLI Kconfig options can be specified like so:
'cmake -DCONFIG_ASSERT=y'
The lifetime of such an option is the same as the lifetime of a CMake
cache variable, and in principle any method of populating the
CMakeCache could be used, such as cmake-gui.
This has been implemented by scanning the CMakeCache variables before
Kconfig is executed and writing any that are prefixed with 'CONFIG_'
to a new Kconfig fragment in the build directory that is merged in
with a high precedence.
Signed-off-by: Sebastian Bøe <sebastian.boe@nordicsemi.no>
Update the application documentation to discuss the new ability to
use semicolons as separators when there are multiple files. Enabling
semicolon separators also enables CMake lists to manipulate CONF_FILE
from the application side.
Signed-off-by: Michael R Rosen <michael.r.rosen@intel.com>
This covers its design and scope, and provides usage and some
implementation documentation on the existing flashing and debugging
commands.
Signed-off-by: Marti Bolivar <marti@opensourcefoundries.com>
This commit gets rid of the 'option env="ENV_VAR"' bounce symbols.
"$FOO" now expands directly to the value of the environment variable
FOO, instead of to the value of the Kconfig symbol FOO.
This change is likely to soon appear in the C tools as well. Those
'option env' symbols always seemed kinda pointless, and have broken
dependency handling due to forcing symbol evaluation during parsing,
before all the symbols have even been seen.
Compatibility with the C tools could be retained by naming all
'option env' symbols the same as the environment variable they
reference.
This commit also updated the Zephyr documentation to explain the new
behavior. It's relevant for $ZEPHYR_BASE and out-of-tree Kconfig
extensions.
Commit message from Kconfiglib (cbf32e29a130d)
==============================================
Make "$FOO" directly reference the environment variable $FOO in e.g.
'source' statements, instead of the symbol FOO. Use os.path.expandvars()
to expand strings (which preserves "$FOO" as-is if no environment
variable FOO exists).
This gets rid of the 'option env' "bounce" symbols, which are mostly
just spam and are buggy in the C tools (dependencies aren't always
respected, due to parsing and evaluation getting mixed up). The same
change will probably appear soon in the C tools as well.
Keep accepting 'option env' to preserve some backwards compatibility,
but ignore it when expanding strings. For compatibility with the C
tools, bounce symbols will need to be named the same as the environment
variables they reference (which is the case for the Linux kernel).
This is a compatibility break, so the major version will be bumped to 6
at the next release.
The main motivation for adding this now is to allow recording properties
on each MenuNode in a clean way. 'option env' symbols interact badly
with delayed dependency propagation.
Side note: I have a feeling that recording environment variable values
might be redundant to trigger rebuilds if sync_deps() is run at each
compile. It should detect all changes to symbol values due to
environment variables changing value.
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
This is handier in some ways compared to the symbol reference pages. The
search feature is more flexible, and you get to see which dependencies
are currently unsatisfied.
Signed-off-by: Ulf Magnusson <ulfalizer@gmail.com>
Update the Application Development Primer to describe the new menuconfig
configuration interface:
- Update the section explaining how the configuration is navigated,
changed, and saved
- Add a section explaining how to jump directly to a symbol in the
configuration interface
- Replace mconf screenshots with menuconfig.py screenshots. Remove some
screenshots that are no longer used.
- Remove the section explaining how to load arbitrary .config files
from within the configuration interface. That feature hasn't been
implemented yet in menuconfig.py.
- Do various minor language cleanup
Signed-off-by: Ulf Magnusson <ulfalizer@gmail.com>
In particular, try to demystify Kconfig.defconfig files, and provide
guidelines on whether configuration settings should go in
BOARD_defconfig or Kconfig.defconfig.
The board porting section seems to be the most relevant one here, so put
the documentation there, with some "see also" links from elsewhere.
Things could be reorganized later if needed.
Give a general overview of visible and invisible Kconfig symbols as
well, as that ties in with the configuration scheme.
This is reverse-engineering on my part. The configuration scheme doesn't
seem to be documented anywhere prior.
Fixes: #7159
Signed-off-by: Ulf Magnusson <ulfalizer@gmail.com>
The documentation doesn't give the format for listing multiple files in
CONF_FILE (space-separated list).
Signed-off-by: Ulf Magnusson <ulfalizer@gmail.com>
The current application configuration documentation makes it a bit
unclear that configuration files are merged. Rewrite the documentation
to explicitly talk about merging, which I think is less confusing.
Remove the following section from the introduction as well, as I think
it might make people wonder how they can have an existing kernel
configuration when they haven't created one. The updated configuration
section (which the introduction now has a forward reference to)
clarifies the zephyr/.config bit anyway.
If omitted, the application's existing kernel configuration option
values are used; if no existing values are provided, the kernel's
default configuration values are used.
Signed-off-by: Ulf Magnusson <ulfalizer@gmail.com>
Pressing Y/N to configure boolean configuration symbols probably won't
be supported in the upcoming Python menuconfig implementation, and Space
is much smoother anyway. '?' is smoother than tabbing to '< Help >' too.
Also remove this part, which I couldn't make sense of:
When a non-default entry is selected for options that are
non-numerical, an asterisk :kbd:`*` appears between the square
brackets in the display. There is nothing added added the display
when you select the option's default.
[*] just means the current symbol value is 'y'.
Signed-off-by: Ulf Magnusson <ulfalizer@gmail.com>
Add a sample that demonstrates a custom board definition. This proves
that BOARD_ROOT works and can be a useful reference when creating a
custom board definition.
Instead of spending time making up a board, the nrf52840_pca10056
board has been copied as-is. And the hello world sample has been used
as the basis for the application.
Signed-off-by: Sebastian Bøe <sebastian.boe@nordicsemi.no>
Single backslashes outside of a code-block are treated as escape
characters, so need to double up to get a single backslash rendered in
the generated HTML.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Edits and additions for clarity and correctness, based on the current
contents of the file (dts.cmake) which controls the DTS build.
Signed-off-by: Marti Bolivar <marti@opensourcefoundries.com>
This is one way we can support out of tree board definitions. Basically
all this needs is a board definition in the application source directory
that follows the same structure we have in the main Zephyr tree (also
allowing multiple custom boards). An application tree would look like
this for example:
boards/
CMakeLists.txt
prj.conf
README.rst
src/
with boards following the same structure as in Zephyr:
.
├── boards
│ └── x86
│ └── arduino_101
│ ├── doc
│ │ └── img
│ └── support
└── src
To use this, you need to specify the BOARD_ROOT variable on the command
line when building:
cmake -DBOARD=<board name> -DBOARD_ROOT=<path to boards> ..
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
When the Kconfig BOOTLOADER_MCUBOOT is selected, an overlay to place the
image at the slot0 location is required. In order to avoid having to do
this manually for all samples when targetting MCUboot, include the logic
inside the dts.cmake script to prepend a new common.dts file that then
conditionally includes mcuboot.overlay.
Signed-off-by: Carles Cufi <carles.cufi@nordicsemi.no>
This patch changes the manner in which we collect DTS overlay files so
that they comply with the same approach taken for configuration fragment
files (.conf).
Additionally it also documents the usage of those files in the
Application Developer Guide.
Signed-off-by: Carles Cufi <carles.cufi@nordicsemi.no>
Rework the Application Development Primer so that it describes the
differences between UNIX and Windows builds and uses Ninja by default,
in order to be compatible with all of them.
Signed-off-by: Carles Cufi <carles.cufi@nordicsemi.no>
The APPLICATION_BASE variable in the example Kconfig file was copied
in from an (out of tree) application which relied on it during the
Kbuild days, but it's actually not needed by the CMake build system
and should be removed.
Signed-off-by: Marti Bolivar <marti@opensourcefoundries.com>
installed GDB on host might not be compatible with the binary generated
by Zephyr. Mention that we need to use the gdb that corrosponds to the
toolchain being used.
Fixes#4312
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
The line between Zephyr versus application is blurry since they share
a configuration, but try to disambiguate.
Signed-off-by: Marti Bolivar <marti@opensourcefoundries.com>
The documentation regarding application-specific Kconfig options is
unclear. Fix that.
Reported-by: David Kinder <david.b.kinder@intel.com>
Signed-off-by: Marti Bolivar <marti@opensourcefoundries.com>
Himanshu Jha