bartoszek/zephyr
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

doc: gsg: simplifications and fixups

Browse Source 
Strip out text that isn't needed to try to minimize the GSG's length.
Fix up some grammar nits.

Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
This commit is contained in:
Martí Bolívar 2020-03-31 14:49:11 -07:00 committed by Carles Cufí
parent a5949e74f6
commit d5533765ff
1 changed files with 145 additions and 208 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

353
doc/getting_started/index.rst
View File

@ -3,17 +3,13 @@
Getting Started Guide
#####################
Follow this guide to get a quick start with Zephyr development where
you'll:
Follow this guide to:
- **Set up a command-line development environment** for Linux* (Ubuntu),
macOS, or Windows, with required package manager, compiler, and
build-system tools,
- **Get the sources**,
- **Build, flash, and run** a sample application on your target board.
\*Instructions for other Linux distributions are discussed in the
:ref:`advanced Linux setup document <installation_linux>`.
- Set up a command-line Zephyr development environment on Ubuntu, macOS, or
Windows (instructions for other Linux distributions are discussed in
:ref:`installation_linux`)
- Get the source code
- Build, flash, and run a sample application
.. _host_setup:
@ -22,18 +18,13 @@ you'll:
Select and Update OS
********************
Zephyr development depends on an up-to-date host system and common build system
tools. First, make sure your development system OS is updated:
Click the operating system you are using.
.. tabs::
.. group-tab:: Ubuntu
This guide covers Ubuntu version 18.04 LTS and later. See
:ref:`installation_linux` for information about other Linux
distributions and older versions of Ubuntu.
Use these commands to bring your Ubuntu system up to date:
This guide covers Ubuntu version 18.04 LTS and later.
.. code-block:: bash
@ -42,17 +33,16 @@ tools. First, make sure your development system OS is updated:
.. group-tab:: macOS
On macOS Mojave or later, you can manually check for updates by choosing
System Preferences from the Apple menu, then clicking Software Update (and
click Update Now if there are). For other macOS versions, see the
`Update macOS topic in Apple support
On macOS Mojave or later, select *System Preferences* >
*Software Update*. Click *Update Now* if necessary.
On other versions, see `this Apple support topic
<https://support.apple.com/en-us/HT201541>`_.
.. group-tab:: Windows
On Windows, you can manually check for updates by selecting Start > Settings >
Update & Security > Windows Update, and then select Check for updates.
If updates are available, install them.
Select *Start* > *Settings* > *Update & Security* > *Windows Update*.
Click *Check for updates* and install any that are available.
.. _install-required-tools:
@ -61,18 +51,14 @@ tools. First, make sure your development system OS is updated:
Install dependencies
********************
Next, use a package manager to install required support tools. Python 3
and its package manager, pip, are used extensively by Zephyr for
installing and running scripts used to compile, build, and run Zephyr
applications.
We'll also install Zephyr's multi-purpose west tool.
Next, you'll install some host dependencies using your package manager.
You'll also install :ref:`west <west>`, Zephyr's multi-purpose tool.
.. tabs::
.. group-tab:: Ubuntu
#. Use the ``apt`` package manager to install these tools:
#. Use ``apt`` to install dependencies:
.. code-block:: bash
@ -86,29 +72,31 @@ We'll also install Zephyr's multi-purpose west tool.
cmake --version
If it's not version 3.13.1 or higher, follow these steps to
add the `kitware third-party apt repository <https://apt.kitware.com/>`__
add the `Kitware third-party apt repository <https://apt.kitware.com/>`__
to get an updated version of cmake.
a) Add the kitware signing key to apt:
a) Add the Kitware signing key:
.. code-block:: bash
wget -O - https://apt.kitware.com/keys/kitware-archive-latest.asc 2>/dev/null | sudo apt-key add -
b) Add the kitware repo corresponding to the Ubuntu 18.04 LTS release:
b) Add the Kitware apt repository for your OS release. For Ubuntu
18.04 LTS:
.. code-block:: bash
sudo apt-add-repository 'deb https://apt.kitware.com/ubuntu/ bionic main'
c) Then install the updated cmake using the usual apt commands:
c) Then install the updated cmake with ``apt``:
.. code-block:: bash
sudo apt update
sudo apt install cmake
#. Install west:
#. Install west, and make sure :file:`~/.local/bin` is on your
:envvar:`PATH` :ref:`environment variable <env_vars>`:
.. code-block:: bash
@ -116,28 +104,19 @@ We'll also install Zephyr's multi-purpose west tool.
echo 'export PATH=~/.local/bin:"$PATH"' >> ~/.bashrc
source ~/.bashrc
The pip3 ``--user`` option puts installed Python packages into your
``~/.local/bin folder`` so we'll need to add this to the PATH
so these packages will be found. Adding the PATH specification to your
``.bashrc`` file ensures this setting is permanent.
.. group-tab:: macOS
#. On macOS, install :program:`Homebrew` by following instructions on the `Homebrew
site`_, and as shown here. Homebrew is a free and open-source package management system that
simplifies installing software on macOS. While installing Homebrew,
you may be prompted to install additional missing dependencies; please follow
any such instructions as well.
#. Install `Homebrew <https://brew.sh/>`_:
.. code-block:: bash
/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
#. Then, install these host dependencies with the ``brew`` command:
#. Use ``brew`` to install dependencies:
.. code-block:: bash
brew install cmake ninja gperf ccache dfu-util qemu dtc python3
brew install cmake ninja gperf python3 ccache qemu dtc
#. Install west:
@ -145,32 +124,33 @@ We'll also install Zephyr's multi-purpose west tool.
pip3 install west
.. _Homebrew site: https://brew.sh/
.. group-tab:: Windows
.. note:: Currently, the built-in `Windows Subsystem for Linux (WSL)
<https://msdn.microsoft.com/en-us/commandline/wsl/install_guide>`__
doesn't support flashing your application to the board. As such,
we don't recommend using WSL yet.
.. note::
These instructions assume you are using the Windows ``cmd.exe``
command prompt. Some of the details, such as setting environment
variables, may differ if you are using PowerShell.
Due to issues finding executables, the Zephyr Project doesn't
currently support application flashing using the `Windows Subsystem
for Linux (WSL)
<https://msdn.microsoft.com/en-us/commandline/wsl/install_guide>`_
(WSL).
An easy way to install native Windows dependencies is to first install
`Chocolatey`_, a package manager for Windows. If you prefer to install
dependencies manually, you can also download the required programs from their
respective websites and verify they can be found on your PATH.
Therefore, we don't recommend using WSL when getting started.
These instructions must be run in a ``cmd.exe`` command prompt. The
required commands differ on PowerShell.
These instructions rely on `Chocolatey`_. If Chocolatey isn't an option,
you can install dependencies from their respective websites and ensure
the command line tools are on your :envvar:`PATH` :ref:`environment
variable <env_vars>`.
|p|
#. Install :program:`Chocolatey` by following the instructions on the
`Chocolatey install`_ page.
#. `Install chocolatey`_
#. Open a command prompt (``cmd.exe``) as an **Administrator** (press the
Windows key, type "cmd.exe" in the prompt, then right-click the result and
choose "Run as Administrator").
#. Open an **Administrator** ``cmd.exe`` window: press the Windows key,
type "cmd.exe", right-click the result, and choose "Run as
Administrator".
#. Disable global confirmation to avoid having to confirm
installation of individual programs:
@ -179,30 +159,23 @@ We'll also install Zephyr's multi-purpose west tool.
choco feature enable -n allowGlobalConfirmation
#. Install CMake:
#. Use ``choco`` to install dependencies:
.. code-block:: console
choco install cmake --installargs 'ADD_CMAKE_TO_PATH=System'
choco install ninja gperf python git
#. Install the rest of the tools:
#. Open a new ``cmd.exe`` window **as a regular user** to continue.
.. code-block:: console
choco install git python ninja dtc-msys2 gperf
#. Close the Administrator command prompt window and open a
regular command prompt window to continue..
#. Install west:
#. Install west in the new window:
.. code-block:: bash
pip3 install west
.. _Chocolatey: https://chocolatey.org/
.. _Chocolatey install: https://chocolatey.org/install
.. _Install chocolatey: https://chocolatey.org/install
.. _get_the_code:
.. _clone-zephyr:
@ -212,10 +185,8 @@ We'll also install Zephyr's multi-purpose west tool.
Get the source code
*******************
Zephyr's multi-purpose west tool simplifies getting the Zephyr
project git repositories and external modules used by Zephyr.
Clone all of Zephyr's git repositories in a new :file:`zephyrproject`
directory using west:
Clone Zephyr and its :ref:`modules <modules>` into a new :term:`west workspace`
named :file:`zephyrproject`.
.. tabs::
@ -223,18 +194,16 @@ directory using west:
.. code-block:: bash
cd ~
west init zephyrproject
cd zephyrproject
west init ~/zephyrproject
cd ~/zephyrproject
west update
.. group-tab:: macOS
.. code-block:: bash
cd ~
west init zephyrproject
cd zephyrproject
west init ~/zephyrproject
cd ~/zephyrproject
west update
.. group-tab:: Windows
@ -251,41 +220,23 @@ directory using west:
Export Zephyr CMake package
***************************
Exporting Zephyr as a :ref:`cmake_pkg` makes it possible for CMake to automatically find and load
boilerplate code for building a Zephyr application.
The :ref:`Zephyr CMake package <cmake_pkg>` allows CMake to load boilerplate
code required for building Zephyr applications.
Zephyr CMake package is exported with the following command
.. code-block:: console
.. tabs::
.. group-tab:: Ubuntu
.. code-block:: bash
west zephyr-export
.. group-tab:: macOS
.. code-block:: bash
west zephyr-export
.. group-tab:: Windows
.. code-block:: bat
west zephyr-export
west zephyr-export
.. _install_py_requirements:
.. _gs_python_deps:
.. rst-class:: numbered-step
Install needed Python packages
******************************
Install Python dependencies
***************************
The Zephyr source folders we downloaded contain a ``requirements.txt`` file
that we'll use to install additional Python tools used by the Zephyr
project:
Zephyr's ``scripts/requirements.txt`` file declares additional Python
dependencies. Install them with ``pip3``.
.. tabs::
@ -307,166 +258,152 @@ project:
pip3 install -r %HOMEPATH%\zephyrproject\zephyr\scripts\requirements.txt
.. _gs_python_deps:
.. rst-class:: numbered-step
Install Software Development Toolchain
**************************************
Install a Toolchain
*******************
A toolchain includes necessary tools used to build Zephyr applications
including: compiler, assembler, linker, and their dependencies.
.. _Zephyr SDK Downloads: https://github.com/zephyrproject-rtos/sdk-ng/releases
A toolchain provides a compiler, assembler, linker, and other programs required
to build Zephyr applications.
.. tabs::
.. group-tab:: Ubuntu
Zephyr's Software Development Kit (SDK) contains necessary Linux
development tools to build Zephyr on all supported architectures.
Additionally, it includes host tools such as custom QEMU binaries and a
host compiler.
The Zephyr Software Development Kit (SDK) contains toolchains for each of
Zephyr's supported architectures. It also includes additional host tools,
such as custom QEMU binaries and a host compiler.
|p|
#. Download the `latest SDK
<https://github.com/zephyrproject-rtos/sdk-ng/releases>`_ as a
self-extracting installation binary:
#. Download the `latest SDK installer
<https://github.com/zephyrproject-rtos/sdk-ng/releases>`_:
.. code-block:: bash
cd ~
wget https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v0.11.2/zephyr-sdk-0.11.2-setup.run
#. Run the installation binary, installing the SDK in your home
folder :file:`~/zephyr-sdk-0.11.2`:
#. Run the installer, installing the SDK in :file:`~/zephyr-sdk-0.11.2`:
.. code-block:: bash
chmod +x zephyr-sdk-0.11.2-setup.run
./zephyr-sdk-0.11.2-setup.run -- -d ~/zephyr-sdk-0.11.2
#. Set environment variables to let the build system know where to
find the toolchain programs:
.. note::
You cannot move the SDK directory after you have installed it.
#. Set the :ref:`environment variables <env_vars>` required to use the
Zephyr SDK:
.. code-block:: bash
export ZEPHYR_TOOLCHAIN_VARIANT=zephyr
export ZEPHYR_SDK_INSTALL_DIR=~/zephyr-sdk-0.11.2
The SDK contains a udev rules file that provides information
needed to identify boards and grant hardware access permission to flash
tools. Install these udev rules with these commands:
#. Install `udev <https://en.wikipedia.org/wiki/Udev>`_ rules, which
allow you to flash most Zephyr boards as a regular user:
.. code-block:: bash
.. code-block:: bash
sudo cp ${ZEPHYR_SDK_INSTALL_DIR}/sysroots/x86_64-pokysdk-linux/usr/share/openocd/contrib/60-openocd.rules /etc/udev/rules.d
sudo udevadm control --reload
sudo cp ${ZEPHYR_SDK_INSTALL_DIR}/sysroots/x86_64-pokysdk-linux/usr/share/openocd/contrib/60-openocd.rules /etc/udev/rules.d
sudo udevadm control --reload
.. group-tab:: macOS
#. The Zephyr SDK is not supported on macOS. See instructions for
:ref:`installing 3rd-party toolchains<gs_toolchain>`.
Follow the instructions in :ref:`gs_toolchain`. Note that the Zephyr SDK
is not available on macOS.
#. Do not forget to set environment variables (ZEPHYR_TOOLCHAIN_VARIANT and toolchain specific ones)
to let the build system know where to find the toolchain programs.
Do not forget to set the required :ref:`environment variables <env_vars>`
(:envvar:`ZEPHYR_TOOLCHAIN_VARIANT` and toolchain specific ones).
.. group-tab:: Windows
#. The Zephyr SDK is not supported on Windows. See instructions for
:ref:`installing 3rd-party toolchains<gs_toolchain>`.
#. Do not forget to set environment variables (ZEPHYR_TOOLCHAIN_VARIANT and toolchain specific ones)
to let the build system know where to find the toolchain programs.
Follow the instructions in :ref:`gs_toolchain`. Note that the Zephyr SDK
is not available on Windows.
Do not forget to set the required :ref:`environment variables <env_vars>`
(:envvar:`ZEPHYR_TOOLCHAIN_VARIANT` and toolchain specific ones).
.. _getting_started_run_sample:
.. rst-class:: numbered-step
Build the Blinky Application
****************************
Build the Blinky Sample
***********************
The sample :ref:`blinky-sample` blinks an LED on the target board. By
building and running it, we can verify that the environment and tools
are properly set up for Zephyr development.
.. note::
.. note:: This sample is compatible with most boards supported by
Zephyr, but not all of them. See the :ref:`blinky sample requirements
<blinky-sample-requirements>` for more information. If this sample is not
compatible with your board, a good alternative to try is the
:ref:`Hello World sample <hello_world>`.
Blinky is compatible with most, but not all, :ref:`boards`. If your board
does not meet Blinky's :ref:`blinky-sample-requirements`, then
:ref:`hello_world` is a good alternative.
#. Build the blinky sample. Specify **your board name**
(see :ref:`boards`) in the command below:
Build the :ref:`blinky-sample` with :ref:`west build <west-building>`, changing
``<your-board-name>`` appropriately for your board:
.. code-block:: bash
.. tabs::
west build -p auto -b <your-board-name> samples/basic/blinky
.. group-tab:: Ubuntu
This west command uses the ``-p auto`` parameter to automatically
clean out any byproducts from a previous build if needed, useful if
you try building another sample.
.. code-block:: bash
cd ~/zephyrproject/zephyr
west build -p auto -b <your-board-name> samples/basic/blinky
.. group-tab:: macOS
.. code-block:: bash
cd ~/zephyrproject/zephyr
west build -p auto -b <your-board-name> samples/basic/blinky
.. group-tab:: Windows
.. code-block:: bat
cd %HOMEPATH%\zephyrproject\zephyr
west build -p auto -b <your-board-name> samples\basic\blinky
The ``-p auto`` option automatically cleans byproducts from a previous build
if necessary, which is useful if you try building another sample.
.. rst-class:: numbered-step
Flash and Run the Application
*****************************
Flash the Sample
****************
#. Connect a USB cable between the board and your development computer.
(Refer to the specific :ref:`boards` documentation if you're not sure
which connector to use on the board.)
#. If there's a switch, turn the board on.
#. Flash the blinky application you just built using the command:
Connect your board, usually via USB, and turn it on if there's a power switch.
If in doubt about what to do, check your board's page in :ref:`boards`.
.. tabs::
Then flash the sample using :ref:`west flash <west-flashing>`:
.. group-tab:: Ubuntu
.. code-block:: console
.. code-block:: bash
west flash
west flash
You may need to install additional :ref:`host tools <debug-host-tools>`
required by your board. The ``west flash`` command will print an error if any
required dependencies are missing.
If the flash command fails, and you've checked your
board is powered on and connected to the right on-board USB connector,
verify you've granted needed access permission by
:ref:`setting-udev-rules`.
.. group-tab:: macOS
.. code-block:: bash
west flash
.. group-tab:: Windows
.. code-block:: bat
west flash
The application will start running and you'll see blinky in action. The
actual blinking LED location is board specific.
If you're using blinky, the LED will start to blink as shown in this figure:
.. figure:: img/ReelBoard-Blinky.gif
:width: 400px
:name: reelboard-blinky
Phytec reel_board running blinky
Phytec :ref:`reel_board <reel_board>` running blinky
Next Steps
**********
Now that you've got the blinky sample running, here are some next steps
for exploring Zephyr:
Here are some next steps for exploring Zephyr:
* Try some other :ref:`samples-and-demos` that demonstrate Zephyr
capabilities.
* Learn about :ref:`application` and more details about :ref:`west`.
* Check out :ref:`beyond-GSG` for information about advanced setup
alternatives and issues.
* Try other :ref:`samples-and-demos`
* Learn about :ref:`application` and the :ref:`west <west>` tool
* Find out about west's :ref:`flashing and debugging <west-build-flash-debug>`
features, or more about :ref:`debugging` in general
* Check out :ref:`beyond-GSG` for additional setup alternatives and ideas
* Discover :ref:`project-resources` for getting help from the Zephyr
community.
community