353 lines
12 KiB
ReStructuredText
353 lines
12 KiB
ReStructuredText
.. _installing_zephyr_win:
|
|
|
|
Development Environment Setup on Windows
|
|
########################################
|
|
|
|
This section describes how to configure your development environment and
|
|
to build Zephyr applications in a Microsoft Windows environment.
|
|
|
|
This guide was tested by building the Zephyr :ref:`hello_world` sample
|
|
application on Windows versions 7, 8.1, and 10.
|
|
|
|
Update Your Operating System
|
|
****************************
|
|
|
|
Before proceeding with the build, ensure that you are running your
|
|
Windows system with the latest updates installed.
|
|
|
|
.. _windows_requirements:
|
|
|
|
Installing Requirements and Dependencies
|
|
****************************************
|
|
|
|
There are 3 different ways of developing for Zephyr on Microsoft Windows.
|
|
The first one is fully Windows native, whereas the 2 additional ones require
|
|
emulation layers that slow down build times and are not as optimal. All of
|
|
them are presented here for completeness, but unless you have a particular
|
|
requirement for a UNIX tool that is not available on Windows, we strongly
|
|
recommend you use the Windows Command Prompt for performance and minimal
|
|
dependency set.
|
|
|
|
Using Windows Command Prompt (Recommended, fastest)
|
|
===================================================
|
|
|
|
The easiest way to install the dependencies natively on Microsoft Windows is
|
|
to use the :program:`Chocolatey` package manager (`Chocolatey website`_).
|
|
If you prefer to install those manually then simply download the required
|
|
packages from their respective websites.
|
|
|
|
.. note::
|
|
There are multiple ``set`` statements in this tutorial. You can avoid
|
|
typing them every time by placing them inside a ``.cmd`` file and
|
|
running that every time you open a Command Prompt.
|
|
|
|
#. If you're behind a corporate firewall, you'll likely need to specify a
|
|
proxy to get access to internet resources::
|
|
|
|
set HTTP_PROXY=http://user:password@proxy.mycompany.com:1234
|
|
set HTTPS_PROXY=http://user:password@proxy.mycompany.com:1234
|
|
|
|
#. Install :program:`Chocolatey` by following the instructions on the
|
|
`Chocolatey install`_ website.
|
|
|
|
#. Open a Command Prompt (`cmd.exe`) as an **Administrator**.
|
|
|
|
#. Optionally disable global confirmation to avoid having to add `-y` to all
|
|
commands:
|
|
|
|
.. code-block:: console
|
|
|
|
choco feature enable -n allowGlobalConfirmation
|
|
|
|
#. Install CMake and DTC:
|
|
|
|
.. code-block:: console
|
|
|
|
choco install cmake --installargs 'ADD_CMAKE_TO_PATH=System'
|
|
choco install dtc-msys2 --version 1.4.4
|
|
|
|
#. Install the rest of the tools:
|
|
|
|
.. code-block:: console
|
|
|
|
choco install git python ninja gperf
|
|
|
|
#. Close the Command Prompt window.
|
|
|
|
#. Open a Command Prompt (`cmd.exe`) as a **regular user**.
|
|
|
|
#. Clone a copy of the Zephyr source into your home directory using Git.
|
|
|
|
.. code-block:: console
|
|
|
|
cd %userprofile%
|
|
git clone https://github.com/zephyrproject-rtos/zephyr.git
|
|
|
|
#. Install the required Python modules::
|
|
|
|
cd %userprofile%\zephyr
|
|
pip install --user -r scripts/requirements.txt
|
|
|
|
#. The build system should now be ready to work with any toolchain installed in
|
|
your system. In the next step you'll find instructions for installing
|
|
toolchains for building both x86 and ARM applications.
|
|
|
|
#. Install cross compiler toolchain:
|
|
|
|
* For x86, install the 2017 Windows host ISSM toolchain from the Intel
|
|
Developer Zone: `ISSM Toolchain`_. Use your web browser to
|
|
download the toolchain's ``tar.gz`` file. You can then use 7-Zip or a
|
|
similar tool to extract it into a destination folder.
|
|
|
|
.. note::
|
|
|
|
The ISSM toolset only supports development for Intel |reg| Quark |trade|
|
|
Microcontrollers, for example, the Arduino 101 board. (Check out the
|
|
"Zephyr Development Environment
|
|
Setup" in this `Getting Started on Arduino 101 with ISSM`_ document.)
|
|
Additional setup is required to use the ISSM GUI for development.
|
|
|
|
|
|
* For ARM, install GNU ARM Embedded from the ARM developer website:
|
|
`GNU ARM Embedded`_ (install to :file:`c:\\gccarmemb`).
|
|
|
|
#. Within the Command Prompt, set up environment variables for the installed
|
|
tools and for the Zephyr environment:
|
|
|
|
For x86:
|
|
|
|
.. code-block:: console
|
|
|
|
set ZEPHYR_GCC_VARIANT=issm
|
|
set ISSM_INSTALLATION_PATH=c:\issm0-toolchain-windows-2017-01-25
|
|
|
|
Use the path where you extracted the ISSM toolchain.
|
|
|
|
For ARM:
|
|
|
|
.. code-block:: console
|
|
|
|
set ZEPHYR_GCC_VARIANT=gccarmemb
|
|
set GCCARMEMB_TOOLCHAIN_PATH=c:\gccarmemb
|
|
|
|
And for either, set the `ZEPHYR_BASE` environment variable to the root
|
|
of the Zephyr repository you cloned:
|
|
|
|
.. code-block:: console
|
|
|
|
set ZEPHYR_BASE=%userprofile%\zephyr
|
|
|
|
#. Finally, you can try building the :ref:`hello_world` sample to check things
|
|
out.
|
|
|
|
To build for the Intel |reg| Quark |trade| (x86-based) Arduino 101:
|
|
|
|
.. zephyr-app-commands::
|
|
:zephyr-app: samples/hello_world
|
|
:host-os: win
|
|
:generator: ninja
|
|
:board: arduino_101
|
|
:goals: build
|
|
|
|
To build for the ARM-based Nordic nRF52 Development Kit:
|
|
|
|
.. zephyr-app-commands::
|
|
:zephyr-app: samples/hello_world
|
|
:host-os: win
|
|
:generator: ninja
|
|
:board: nrf52_pca10040
|
|
:goals: build
|
|
|
|
This should check that all the tools and toolchain are set up correctly for
|
|
your own Zephyr development.
|
|
|
|
Using MSYS2
|
|
===========
|
|
|
|
The Zephyr development environment on Windows relies on MSYS2, a modern UNIX
|
|
environment for Windows. Follow the steps below to set it up:
|
|
|
|
#. Download and install :program:`MSYS2`. Download the appropriate (32 or
|
|
64-bit) MSYS2 installer from the `MSYS2 website`_ and execute it. On the
|
|
final installation screen, check the "Run MSYS2 now." box to start up an
|
|
MSYS2 shell when installation is complete. Follow the rest of the
|
|
installation instructions on the MSYS2 website to update the package
|
|
database and core system packages. You may be advised to "terminate MSYS2
|
|
without returning to shell and check for updates again". If so, simply
|
|
close the ``MSYS2 MSYS Shell`` desktop app and run it again to complete the update.)
|
|
|
|
#. Launch the ``MSYS2 MSYS Shell`` desktop app from your start menu (if it's not still open).
|
|
|
|
.. note::
|
|
|
|
Make sure you start ``MSYS2 MSYS Shell``, not ``MSYS2 MinGW Shell``.
|
|
|
|
.. note::
|
|
|
|
If you need to inherit the existing Windows environment variables into
|
|
MSYS2 you will need to create a **Windows** environment variable like so::
|
|
``MSYS2_PATH_TYPE=inherit``.
|
|
|
|
.. note::
|
|
There are multiple ``export`` statements in this tutorial. You can avoid
|
|
typing them every time by placing them at the bottom of your
|
|
``~/.bash_profile`` file.
|
|
|
|
#. If you're behind a corporate firewall, you'll likely need to specify a
|
|
proxy to get access to internet resources::
|
|
|
|
export http_proxy=http://proxy.mycompany.com:123
|
|
export https_proxy=$http_proxy
|
|
|
|
#. Update MSYS2's packages and install the dependencies required to build
|
|
Zephyr (you may need to restart the MSYS2 shell):
|
|
|
|
.. code-block:: console
|
|
|
|
pacman -Syu
|
|
pacman -S git cmake make gcc dtc diffutils ncurses-devel python3 gperf
|
|
|
|
#. From within the MSYS2 MSYS Shell, clone a copy of the Zephyr source
|
|
into your home directory using Git. (Some Zephyr tools require
|
|
Unix-style line endings, so we'll configure Git for this repo to
|
|
not do the automatic Unix/Windows line ending conversion (using
|
|
``--config core.autocrlf=false``).
|
|
|
|
.. code-block:: console
|
|
|
|
cd ~
|
|
git clone --config core.autocrlf=false https://github.com/zephyrproject-rtos/zephyr.git
|
|
|
|
#. Install pip and the required Python modules::
|
|
|
|
curl -O 'https://bootstrap.pypa.io/get-pip.py'
|
|
./get-pip.py
|
|
rm get-pip.py
|
|
cd ~/zephyr # or to the folder where you cloned the zephyr repo
|
|
pip install --user -r scripts/requirements.txt
|
|
|
|
#. The build system should now be ready to work with any toolchain installed in
|
|
your system. In the next step you'll find instructions for installing
|
|
toolchains for building both x86 and ARM applications.
|
|
|
|
#. Install cross compiler toolchain:
|
|
|
|
* For x86, install the 2017 Windows host ISSM toolchain from the Intel
|
|
Developer Zone: `ISSM Toolchain`_. Use your web browser to
|
|
download the toolchain's ``tar.gz`` file.
|
|
|
|
You'll need the tar application to unpack this file. In an ``MSYS2 MSYS``
|
|
console, install ``tar`` and use it to extract the toolchain archive::
|
|
|
|
pacman -S tar
|
|
tar -zxvf /c/Users/myusername/Downloads/issm-toolchain-windows-2017-01-15.tar.gz -C /c
|
|
|
|
substituting the .tar.gz path name with the one you downloaded.
|
|
|
|
.. note::
|
|
|
|
The ISSM toolset only supports development for Intel |reg| Quark |trade|
|
|
Microcontrollers, for example, the Arduino 101 board. (Check out the
|
|
"Zephyr Development Environment
|
|
Setup" in this `Getting Started on Arduino 101 with ISSM`_ document.)
|
|
Additional setup is required to use the ISSM GUI for development.
|
|
|
|
|
|
* For ARM, install GNU ARM Embedded from the ARM developer website:
|
|
`GNU ARM Embedded`_ (install to :file:`c:\\gccarmemb`).
|
|
|
|
#. Within the MSYS console, set up environment variables for the installed
|
|
tools and for the Zephyr environment (using the provided shell script):
|
|
|
|
For x86:
|
|
|
|
.. code-block:: console
|
|
|
|
export ZEPHYR_GCC_VARIANT=issm
|
|
export ISSM_INSTALLATION_PATH=/c/issm0-toolchain-windows-2017-01-25
|
|
|
|
Use the path where you extracted the ISSM toolchain.
|
|
|
|
For ARM:
|
|
|
|
.. code-block:: console
|
|
|
|
export ZEPHYR_GCC_VARIANT=gccarmemb
|
|
export GCCARMEMB_TOOLCHAIN_PATH=/c/gccarmemb
|
|
|
|
And for either, run the provided script to set up zephyr project specific
|
|
variables:
|
|
|
|
.. code-block:: console
|
|
|
|
unset ZEPHYR_SDK_INSTALL_DIR
|
|
cd <zephyr git clone location>
|
|
source zephyr-env.sh
|
|
|
|
#. Within the MSYS console, build Kconfig in :file:`$ZEPHYR_BASE/build` and
|
|
add it to path
|
|
|
|
.. code-block:: console
|
|
|
|
cd $ZEPHYR_BASE
|
|
mkdir build && cd build
|
|
cmake $ZEPHYR_BASE/scripts
|
|
make
|
|
echo "export PATH=$PWD/kconfig:\$PATH" >> $HOME/.zephyrrc
|
|
source $ZEPHYR_BASE/zephyr-env.sh
|
|
|
|
.. note::
|
|
|
|
You only need to do this once after cloning the git repository.
|
|
|
|
#. Finally, you can try building the :ref:`hello_world` sample to check things
|
|
out.
|
|
|
|
To build for the Intel |reg| Quark |trade| (x86-based) Arduino 101:
|
|
|
|
.. zephyr-app-commands::
|
|
:zephyr-app: samples/hello_world
|
|
:board: arduino_101
|
|
:host-os: win
|
|
:goals: build
|
|
|
|
To build for the ARM-based Nordic nRF52 Development Kit:
|
|
|
|
.. zephyr-app-commands::
|
|
:zephyr-app: samples/hello_world
|
|
:board: nrf52_pca10040
|
|
:host-os: win
|
|
:goals: build
|
|
|
|
This should check that all the tools and toolchain are set up correctly for
|
|
your own Zephyr development.
|
|
|
|
Using Windows 10 WSL (Windows Subsystem for Linux)
|
|
==================================================
|
|
|
|
If you are running a recent version of Windows 10 you can make use of the
|
|
built-in functionality to natively run Ubuntu binaries directly on a standard
|
|
command-prompt. This allows you to install the standard Zephyr SDK and build
|
|
for all supported architectures without the need for a Virtual Machine.
|
|
|
|
#. Install Windows Subsystem for Linux (WSL) following the instructions on the
|
|
official Microsoft website: `WSL Installation`_
|
|
|
|
.. note::
|
|
For the Zephyr SDK to function properly you will need Windows 10
|
|
build 15002 or greater. You can check which Windows 10 build you are
|
|
running in the "About your PC" section of the System Settings.
|
|
If you are running an older Windows 10 build you might need to install
|
|
the Creator's Update.
|
|
|
|
#. Follow the instructions for Ubuntu detailed in the Zephyr Linux Getting
|
|
Started Guide which can be found here: :ref:`installation_linux`
|
|
|
|
.. _GNU ARM Embedded: https://developer.arm.com/open-source/gnu-toolchain/gnu-rm/downloads
|
|
.. _Chocolatey website: https://chocolatey.org/
|
|
.. _Chocolatey install: https://chocolatey.org/install
|
|
.. _MSYS2 website: http://www.msys2.org/
|
|
.. _ISSM Toolchain: https://software.intel.com/en-us/articles/issm-toolchain-only-download
|
|
.. _Getting Started on Arduino 101 with ISSM: https://software.intel.com/en-us/articles/getting-started-arduino-101genuino-101-with-intel-system-studio-for-microcontrollers
|
|
.. _WSL Installation: https://msdn.microsoft.com/en-us/commandline/wsl/install_guide
|