As presented to the TSC, Zephyr's out-of-box experience for new
developers is, well, complicated. A number of suggestions were
presented including simplifying the getting started material to present
a straight-forward path through the setup and installation steps through
to getting a sample application built, flashed, and running.
This PR is a work-in-progress towards addressing this OOB experience
with a minimal-distractions version of the GSG. Alternatives, warnings,
and material that could lead the developer astray were moved to
alternative/advanced instruction documents (based on the previous
separate Linux/macOS/Windows setup guides) and a new "Beyond the GSG"
document.
We do take advantage of a sphinx-tabs extension for synchronized tabs to
present OS-specific instructions: clicking on one tab will display all
same-named tabs throughout the doc.
We hope (and will continue evaluating) that this new GSG gets developers
set up quickly and then we can send them along to other documents to
continue learning about Zephyr and trying other sample apps.
Thanks for all your previous feedback that I've worked
into this new version.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Add comment for the setup failure.
The solution can be infered from ARMmbed/cmsis-pack-manager#97
Fixes#18269.
Signed-off-by: Chen Guokai <1415430544@qq.com>
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>
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>
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>
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>
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>
Remove the C Kconfig tools and various scripts associated with them.
scripts/kconfig/diffconfig is popular, so keep it.
I don't know whether anyone is using scripts/kconfig/config. Remove it
and see if anyone screams.
scripts/kconfig/streamline_config.pl deals with modules ('m' values) and
can safely be removed. Zephyr's Kconfig files do not use modules.
Signed-off-by: Ulf Magnusson <ulfalizer@gmail.com>
Modernize macOS instructions to fit the latest packages offered by
Homebrew and macOS High Sierra.
Signed-off-by: Carles Cufi <carles.cufi@nordicsemi.no>
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>
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>
Since QEMU currently requires Linux or macOS to run, use "unix" as a
host OS for those documenting the build with it.
Signed-off-by: Carles Cufi <carles.cufi@nordicsemi.no>
Since we're switching to ninja as a default generator for CMake, require
the ninja package as part of the requirements on macOS.
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>
Unify the format and mechanisms used in the different Getting Started
guides so that they are consistent in:
- The way Kconfig is built
- Avoiding using -B and -H CMake options
- -DBOARD instead of export
Signed-off-by: Carles Cufi <carles.cufi@nordicsemi.no>
fixed error introduced in application.rst (v1.8) along with a general
spelling check pass including consistent spelling of "runtime" and
hyphenated words with "pre-"
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
When installing packages with PIP, recommend --user so that it is
installed in the user's directory vs system wide, potentially
overriding system-wide files that are under package manager control
and introducing possible security issues.
Signed-off-by: Inaky Perez-Gonzalez <inaky.perez-gonzalez@intel.com>
List all required modules in one file and just call pip with this
file to install all needed modules instead of listing them
individually.
Added gitlint and pyocd and other required packages to the list.
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
Fixed documentation and updated config files for xtools to be used with
the latest version of crosstool-ng (1.23)
Jira: ZEP-616, ZEP-2146
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
Also recommend dfu-util on Mac OS, as it's the recommended flashing
method for Arduino 101 and 96Boards Carbon.
Change-Id: I91d5a8323330ee31cc2165336e4a0a7fdd23dbcf
Signed-off-by: Ricardo Salveti <ricardo.salveti@linaro.org>
Add documentation for OS X users that want to compile
using an available 3rd-party cross compiler and also
complete the section to describe the existing support
for the GCC ARM Embedded toolchain.
Change-Id: I97d27d46c0048a49029dbe4d66fe141755c226e9
Signed-off-by: Carles Cufi <carles.cufi@nordicsemi.no>
Mac OS X guide had an unneeded transient variable.
JIRA: ZEP-616
Change-Id: I1a7cea35830bb786b67aee235337f89c62a4b69f
Signed-off-by: Genaro Saucedo Tejada <genaro.saucedo.tejada@intel.com>
Mac OS X set up instructions were missing some important details that
prevent a new user to set up Zephyr development environment on a not
yet configured system.
JIRA: ZEP-616
Change-Id: I0890ec5364a0ce21e38ba4101d285fc8e46a6bd8
Signed-off-by: Genaro Saucedo Tejada <genaro.saucedo.tejada@intel.com>
- Put everything in one page and simplify workflow.
- Fix indent and layout
Change-Id: Ifd9d11531c9b906324cf87cf401cbce416cc01a4
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
The file can be used to define variables used by the SDK to avoid
having to define them everytime a session is started.
The old file names ~/zephyr-env_install.bash will still work but
it will warn about the file being renamed. We do not want to break
users who have ~/zephyr-env_install.bash in their home and depend on
it.
Change-Id: I04fcaa76854bda3dcfc1cabe75e00e95c511b10d
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
Restructured the guide to follow a basic three step process: Set up, develop,
build. All information that is independent of the OS selection was taken out of
of the OS related documents and placed in the general set up sections.
A new section, Developing Zephyr Applications, was added with links to all the
development relevant section of the documentation.
The content in local_development.rst was split between the setting_up.rst,
installation_linux.rst and installation_mac.rst files as appropriate.
This new structure provides a much better flow for developers beginning their
Zephyr develpment.
Applied all of Inaky's suggestions in the refactored content.
Minor markup fixes and language edits were also perfomed during the refactoring.
Fixed a cross-reference that was broken during the refactor.
Applied all the feedback from the first trial run.
Applied the feedback provided by David Kinder from TCS.
Change-Id: I3368a3a41ec9ad02cc4e7b37fe71c65abd8a7df9
Signed-off-by: Rodrigo Caballero <rodrigo.caballero.abraham@intel.com>
David B. Kinder