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>
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>
