From d5533765ff44b04d5f8b85ce4374ca30fae00aa5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mart=C3=AD=20Bol=C3=ADvar?= Date: Tue, 31 Mar 2020 14:49:11 -0700 Subject: [PATCH] doc: gsg: simplifications and fixups MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- doc/getting_started/index.rst | 353 ++++++++++++++-------------------- 1 file changed, 145 insertions(+), 208 deletions(-) diff --git a/doc/getting_started/index.rst b/doc/getting_started/index.rst index ac01fe3d03d..27792c80a98 100644 --- a/doc/getting_started/index.rst +++ b/doc/getting_started/index.rst @@ -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 `. +- 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 `_. .. 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 `, 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 `__ + add the `Kitware third-party apt repository `__ 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 `: .. 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 `_: .. 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) - `__ - 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) + `_ + (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 `. |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 ` 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 ` 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 - `_ as a - self-extracting installation binary: + #. Download the `latest SDK installer + `_: .. 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 ` 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 `_ 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`. + 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 ` + (: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`. - - #. 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 ` + (: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 - ` for more information. If this sample is not - compatible with your board, a good alternative to try is the - :ref:`Hello World sample `. + 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 `, changing +```` appropriately for your board: - .. code-block:: bash +.. tabs:: - west build -p auto -b 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 samples/basic/blinky + + .. group-tab:: macOS + + .. code-block:: bash + + cd ~/zephyrproject/zephyr + west build -p auto -b samples/basic/blinky + + .. group-tab:: Windows + + .. code-block:: bat + + cd %HOMEPATH%\zephyrproject\zephyr + west build -p auto -b 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 `: - .. group-tab:: Ubuntu +.. code-block:: console - .. code-block:: bash + west flash - west flash +You may need to install additional :ref:`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 ` 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 ` tool +* Find out about west's :ref:`flashing and debugging ` + 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