Create a new dedicated section for west installation that details
some of the finer aspects of the process and steps involved.
Signed-off-by: Carles Cufi <carles.cufi@nordicsemi.no>
I often wish I had a short and Zephyr-specific place to point people
to when they're asking for help in ways that make it hard to help
them.
Add one.
Signed-off-by: Marti Bolivar <marti.bolivar@nordicsemi.no>
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>
- add glossary terms for important concepts we have to explain often,
like "west installation"
- add autodoc directives for pulling in west API docs
- add missing documentation for built-in features like west's
configuration, extension commands, etc.
- add missing documentation for "west sign" extension
- describe the manifest in a self-contained way rather than linking to
the relevant pykwalify schema, also adding a missing reference to
"west manifest" in the miscellaneous multi-repo commands list
- move various details regarding history and motivation to why.rst
among other changes to repo-tool.rst, leaving it closer to a "tell
me what I really need to know" style overview
- update planned features
Fixes: #14992
Signed-off-by: Marti Bolivar <marti@foundries.io>
The latest release of the Windows toolchain has a critical bug,
Windows users should install the next-to-latest release instead.
To prevent Windows users from being affected we add a note about this
in the documentation.
Bug: https://github.com/zephyrproject-rtos/zephyr/issues/12257
Signed-off-by: Sebastian Bøe <sebastian.boe@nordicsemi.no>
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>
Add a note installing programs manually on your Windows system: you may
need to update the Windows PATH so the system can file these programs.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
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>
Skipping the setup of a toolchain is especially nice for brand new users
who just want to give qemu_x86[_64] or native_posix a quick try, gives a
great first impression.
Signed-off-by: Marc Herbert <marc.herbert@intel.com>
Document building the samples with west (for now only in the Getting
Started guide).
Also switch to `reel_board` by default since `arduino_101` is no longer
well supported.
Signed-off-by: Carles Cufi <carles.cufi@nordicsemi.no>
Reference the multiple repository management section in the Getting
Started Guide, so that users have a direct link to the text describing
how multiple repositories are managed.
Signed-off-by: Carles Cufi <carles.cufi@nordicsemi.no>
Add additional details about what running `west init` and `west update`
actually does in the local filesystem.
Signed-off-by: Carles Cufi <carles.cufi@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>
Since west is no longer included in the Zephyr repository, instruct
users to install and use west in order to obtain the Zephyr source code.
Signed-off-by: Carles Cufi <carles.cufi@nordicsemi.no>
Signed-off-by: Torsten Rasmussen <torsten.rasmussen@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>
When we move DT infront of Kconfig we are going to need access to a C
toolchain before Kconfig is evaluated. This means it will not be
possible to specify the toolchain used through Kconfig.
To deal with this we ...
Drop support for specifying CROSS_COMPILE through Kconfig. Still
available is the ability to specify CROSS_COMPILE through the
environment or through a CMake variable.
Signed-off-by: Sebastian Bøe <sebastian.boe@nordicsemi.no>
MSYS support was added as a stop-gap while native windows support was
unsupported. Now that Native windows support is stable we can drop
support for MSYS.
Dropping support for MSYS fixes#11260 and allows us to spend more
resources on native windows support.
Signed-off-by: Sebastian Bøe <sebastian.boe@nordicsemi.no>
Using ``pip3 install --user`` installs Python packages in the Python
user install directory (``.local``) so we should remind folks to add
``~/.local/bin`` to their PATH.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
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>
Windows requires that there are no quotes around environment variables,
remove the ones in the documentation.
Signed-off-by: Carles Cufi <carles.cufi@nordicsemi.no>
The getting started guide says to run:
pip3 install -r --user zephyr/scripts/requirements.txt
but this is broken. It should be:
pip3 install --user -r zephyr/scripts/requirements.txt
This fixes#10817 and is a regression from:
0d811b9aee
Signed-off-by: Sebastian Bøe <sebastian.boe@nordicsemi.no>
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>
Add a new optional TOOLCHAIN_ROOT cmake and environment variable to
specify an alternative location for toolchain cmake files.
When set, Zephyr will look for a toolchain cmake file located in:
${TOOLCHAIN_ROOT}/cmake/toolchain/${ZEPHYR_TOOLCHAIN_VARIANT}.cmake
Signed-off-by: François Delawarde <fnde@oticon.com>
Add a section to optionally install the Chocolatey packages required to
build the documentation in .pdf format on Windows.
Signed-off-by: Carles Cufi <carles.cufi@nordicsemi.no>
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>
The old GCC ARM Embedded website on launchpad
(https://launchpad.net/gcc-arm-embedded) has been superseeded by the new
GNU Arm Embedded one
(https://developer.arm.com/open-source/gnu-toolchain/gnu-rm).
This also means a change of name from "GCC" to "GNU". Reflect this in
the enviroment variables so that the proper term is used henceforth.
Signed-off-by: Carles Cufi <carles.cufi@nordicsemi.no>
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>
In order to make things simpler for the user, remove the
`--user` flag when invoking pip and pip3 so that executables are placed
in the <Python>\Scripts folder, which is added to the PATH
automatically.
Additionally clarify and clean up the documentation tools section.
Signed-off-by: Carles Cufi <carles.cufi@nordicsemi.no>
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>
In order to build the documentation one needs Doxygen. Now that building
the documentation is supported on Windows, include this package.
Signed-off-by: Carles Cufi <carles.cufi@nordicsemi.no>
"Getting Started" does not clearly state how to use a custom cross
compiler. This patch adds a new section "Using Custom Cross
Compilers" to it.
To support users without SDK, we have the section "Building without
the Zephyr SDK". But the section is all about prebuilt tools in the
SDK but not build process. This patch adds two pointers "Using 3rd
Party Cross Compilers" and "Using Custom Cross Compilers" pointing to
the actual building process, and let those section describe
ZEPHYR_TOOLCHAIN_VARIANT, which is cross compilers dependent variable.
The patch also clarify what a 3rd party cross compiler is and what a
custom compiler is.
Signed-off-by: Yasushi SHOJI <y-shoji@ispace-inc.com>
The building and running section is out of date, as Windows and macOS
commands are available now.
It also has some accuracies:
- the following section describes how to build hello_world, not how to
make a new application based on it
- zephyr-env scripts do more than just set project-specific
environment variables (they modify PATH on Unix, and may run
arbitrary RC scripts on all platforms)
Fix these issues.
Signed-off-by: Marti Bolivar <marti@opensourcefoundries.com>
Commas are needed before coordinating conjunctions joining independent
clauses. Two backticks are needed for teletype fonts.
Signed-off-by: Marti Bolivar <marti@opensourcefoundries.com>
Now that the instructions work on Windows, delete a reference to
~ (the user's home on a Unix system) in the text.
Signed-off-by: Marti Bolivar <marti@opensourcefoundries.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>
