The documentation that describes how Python and pip interact with the OS
when installing packages used to be under a common section, and was
moved to the west bootstrap one later on. Since this information is
required early on (for example on Linux when installing CMake via pip3),
move the info to its own section and link to it from others.
Signed-off-by: Carles Cufi <carles.cufi@nordicsemi.no>
Remove the version numbers from the distribution listings, since those
get outdated quickly and on top of that they are causing confusion due
to those being now too old to contain recent versions of CMake and DTC.
Signed-off-by: Carles Cufi <carles.cufi@nordicsemi.no>
Clear Linux exports to all users a list of "aggressive" compiler and
linker flags. Zephyr's CMake build system will either warn or fail
because of these. Add one magic command that solves the issue.
More background information at https://superuser.com/a/1452523/111302
Signed-off-by: Marc Herbert <marc.herbert@intel.com>
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>
Updates based on discussion and changes in supported features.
- Make the guide shorter by removing content that's not relevant to
most users who are truly just getting started, such as information
about pre-LTS versions that did not support west, and by being more
concise in some places.
- Decrease the number of colored boxes. At the latest TSC F2F, the
"note / warning / note / tip" contents were identified as a
readability problem.
- Add additional information based on new west features, like "west
boards".
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>
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>
In 0d811b9aee the gcc-mulitlib package
was removed from the Ubuntu list of packages to install.
Seems this may be creating some confusion for some developers (see
comments in #10243)
Let's add it back.
Signed-off-by: Alberto Escolar Piedras <alpi@oticon.com>
The getting started documentation has become a bit of a mess over
time:
- The reader needs to jump forward and backward in the documents
depending on what their system already has installed (e.g. "start by
cloning Zephyr, oh wait, see below if you don't have Git yet" etc.).
- The operating system setup guides, toolchain setup instructions, and
application build and run information have each become their own
balkanized fiefdom, with duplicated, confusing and sometimes
inconsistent results.
- Linux documentation for all distributions is incomplete in some
places (the Arch documentation in particular is vestigial)
and wrong in others (platforms like Ubuntu still nominally require
tools, like autoconf, that haven't been necessary since we stopped
using the C Kconfig tools)
- The dependencies needed to build the documentation have
gotten *huge* since the LaTeX additions and massively overstate the
footprint of Zephyr's real dependencies. This is particularly a
problem on Linux, where those dependencies were not clearly
separated from those needed to build Zephyr.
- The toolchain setup documentation is confusing and scattered across
the main file and the platform-specific files. There are various
bits of incomplete and/or incorrect information. For example, the
docs imply that you can use the Zephyr SDK on non-Linux hosts, which
isn't true. As another example, some toolchains, such as GNU Arm
Embedded, are documented several times. As a final example, some
toolchains, such as Intel's ISSM, are squirrelled away in the
Windows document when there are Linux builds available.
Overhaul the pages to fix these issues and otherwise clean up the
language. One significant side-effect is that all the
toolchain-related information is rooted in a single toctree. Another
is that it should now be possible to follow the instructions, in
order, on any supported platform.
Signed-off-by: Marti Bolivar <marti@foundries.io>
Fixes the indentation for some code blocks and notes
through the "getting started" instructions.
The main effect is that an ordered list
is no longer broken by a note block.
Signed-off-by: Iván Sánchez Ortega <ivan@sanchezortega.es>
Some distros set the environment variable CFLAGS, this will
accidentally affect Zephyr builds.
To fix this we clear the environment variable from within the Zephyr
build system for the duration of the CMake execution.
Until now we have been instructing the user to clear it, but it is
easier for the user if we clear it for him.
The same applies to CXXFLAGS.
Signed-off-by: Sebastian Bøe <sebastian.boe@nordicsemi.no>
This adds new targets to generate build documentation through
LaTEX to PDF.
There are a few notes:
1. pdflatex complains about the tex file generated by doxygen
so it needs to be fixed with a Python script before feeding
in through pdflatex.
2. SVG files are not recognized by pdflatex so they are converted
to known good format on the fly, only for producing PDF. This
uses the libRSVG's rsvg-convert tool.
Relates to #6782.
Signed-off-by: Daniel Leung <daniel.leung@intel.com>
Modified the web page to make it direct and easier to understand.
Major changes being the selection of the directory in the Zephyr SDK
Installation and a Note added for the '.zephyrrc' to include the SDK
installation location if not default.
Minor changes involving the elimination of repeated use of same sentence
with different Host OS and indentation correction in the Fedora section
since it showed up in 'white text' rather than code block.
SDK's '.zephyrrc' documentation needed to have the default location and
the user defined location
Signed-off-by: Arjun Warty <arjun.warty@nxp.com>
The SDK has been packaged for Arch Linux and can be found
in Arch User Repository. Update the docs to make this known.
The package is useful because by installing it the user
gets all dependencies automatically installed.
Signed-off-by: Alexei Colin <ac@alexeicolin.com>
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>
This expands the Development Environment Setup on Linux guide to
include instructions for Clear Linux.
Tested on Clear Linux build 23610.
Signed-off-by: Daniel Leung <daniel.leung@intel.com>
The 'getting started' documentation is stating that one should set
some environment variables, but this is not necessary because the user
has already been instructed to set the variables in the
platform-specific guides.
The duplicated documentation should be removed because it is inferiour
to the original documentation. E.g. this documentation does not
describe how to permanently set environment variables. Also, it is
confusingly demonstrating how to use the SDK on Windows, but this is
not supported.
I believe that the purpose of the section is to verify that the user
has not misconfigured or misinstalled the toolchain, but this
responsibility is handled better by CMake itself.
Signed-off-by: Sebastian Bøe <sebastian.boe@nordicsemi.no>
Adding missing dependency to the "getting started" documentations.
Without the python3-wheel package, running "pip3 -r requirements.txt"
on a Debian system will fail.
Signed-off-by: Iván Sánchez Ortega <ivan@sanchezortega.es>
We want to support other toolchain not based on GCC, so the variable is
confusing, use ZEPHYR_TOOLCHAIN_VARIANT instead.
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
This package is not needed for building on fedora and currently causes
dependency issue with the fedora package manager, so remove it.
Fixes#6013
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
In order to be able to document the build on Windows and UNIX
systems, slight variations are required on the app commands
that are used throughout the documentation system.
This includes getting rid of the prompt symbol and providing commands
for both UNIX and Windows operating systems.
Signed-off-by: Carles Cufi <carles.cufi@nordicsemi.no>
There are files in the cloned copy of the Zephyr tree needed to setup
the development environment, so there's a bit of chicken and egg
problem.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
We no longer want to pin users to 3.8.2. Instead we tolerate the warning
and therefore ask users to get the latest CMake package from their
distro.
Signed-off-by: Carles Cufi <carles.cufi@nordicsemi.no>
The sanity test script needs to have ccache installed on the Ubuntu
and Fedora developement environments.
Signed-off-by: David Leach <david.leach@nxp.com>
This introduces an schema-based YAML validation process when loading
any YAML file, before doing any operations on them. An exception will
be raised at SanityConfigParser() if the file fails to verify with the
given schema.
Schemas are defined for the platform files in board///*.yaml and for
the (sample|testcase).yaml files. The verification is done using the
pykwalify python library. If not installed, a warning is printed and
the verification schema is skipped. At some point, we might want to
force it being installed.
The verification library is made a separate module (scl.py) so it can
be easily imported by others.
Signed-off-by: Inaky Perez-Gonzalez <inaky.perez-gonzalez@intel.com>
ReST defines interpreted text roles where text enclosed by single quotes
can be "intrepreted", for example :ref:`some name` becomes a link to
a label anywhere in the doc set named "some name", :c:func:`funcname()`
becomes a link to the API documentation for "funcname", and
:option:`CONFIG_NAME` becomes a link to, in our case, the documentation
for the generated Kconfig option.
This patch fixes uses of `some name` (without a role) by either adding
an explicit role, or changing to ``some name``, which indicates inline
code block formatting (most likely what was intended).
This is a precursor to changing the default behavior of interpreted
text to treat `some name` as :any:`some name` (as configured in
doc/conf.py), which would attempt to create a link to any available
definition of "some name".
We may not change this default role behavior, but it becomes an option
after the fixes in this patch. In any case, this patch fixes incorrect
uses of single-quoted text (possibly introduced because GitHub's
markdown language uses single-quoted text for inline code formatting).
Jira: ZEP-2414
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
