diff --git a/doc/README.rst b/doc/README.rst index 9c6139898f0..2d3a5437aa8 100644 --- a/doc/README.rst +++ b/doc/README.rst @@ -55,10 +55,50 @@ Our documentation processing has been tested to run with: * sphinxcontrib-svg2pdfconverter version 0.1.0 * Latexmk version version 4.56 -In order to install the documentation tools, clone a copy of the git repository -for the Zephyr project and set up your development environment as described in -:ref:`getting_started`. This will ensure all the required tools are installed -on your system. +In order to install the documentation tools, first install Zephyr as +described in :ref:`getting_started`. Then install additional tools +that are only required to generate the documentation, +as described below: + +On Ubuntu Linux: + +.. code-block:: console + + sudo apt-get install --no-install-recommends doxygen librsvg2-bin \ + texlive-latex-base texlive-latex-extra latexmk texlive-fonts-recommended + +On Fedora Linux: + +.. code-block:: console + + sudo dnf install doxygen texlive-latex latexmk \ + texlive-collection-fontsrecommended librsvg2-tools + +On Clear Linux: + +.. code-block:: console + + sudo swupd bundle-add texlive + +On Arch Linux: + +.. code-block:: console + + sudo pacman -S doxygen librsvg texlive-core texlive-bin + +On macOS: + +.. code-block:: console + + brew install doxygen mactex librsvg + tlmgr install latexmk + tlmgr install collection-fontsrecommended + +On Windows in an Administrator ``cmd.exe`` prompt: + +.. code-block:: console + + choco install doxygen.install strawberryperl miktex rsvg-convert .. note:: On Windows, the Sphinx executable ``sphinx-build.exe`` is placed in diff --git a/doc/getting_started/getting_started.rst b/doc/getting_started/getting_started.rst index fa930dc437e..6cfe8b5c9e3 100644 --- a/doc/getting_started/getting_started.rst +++ b/doc/getting_started/getting_started.rst @@ -3,84 +3,163 @@ Getting Started Guide ##################### -Use this guide to get started with your :ref:`Zephyr ` -development. +Follow this guide to set up a :ref:`Zephyr ` development +environment on your system, and then build and run a sample application. -Checking Out the Source Code Anonymously -**************************************** +.. _host_setup: -The Zephyr source code is hosted in a GitHub repo that supports -anonymous cloning via git. There are scripts and such in this repo that -you'll need to set up your development environment, and we'll be using -Git to get this repo. (If you don't have Git installed, see the -beginning of the OS-specific instructions below for help.) +Set Up a Development System +*************************** -We'll begin by -using Git to clone the repository anonymously. Enter: - -.. code-block:: console - - # On Linux/macOS - cd ~ - # On Windows - cd %userprofile% - - git clone https://github.com/zephyrproject-rtos/zephyr.git - -You have successfully checked out a copy of the source code to your local -machine in a ``zephyr`` folder in your home directory. - -.. _getting_started_cmake: - -A brief note on the Zephyr build system -*************************************** - -The Zephyr project uses `CMake`_ as a tool for managing the building of the -project. CMake is able to generate build files in different formats (also -known as "generators"), and the following ones are currently supported -by Zephyr: - - * ``make``: Supported on UNIX-like platforms (Linux, macOS). - * ``ninja``: Supported on all platforms. - -Most of the examples in the Zephyr documentation use ``ninja`` as a build tool, -but you should be able to use any generator on any of the examples listed. - -Set Up the Development Environment -********************************** - -The Zephyr project supports these operating systems: - -* Linux -* macOS -* Microsoft Windows - -Use the following procedures to create a new development environment. +Follow one of the following guides for your host operating system. .. toctree:: :maxdepth: 1 - installation_linux.rst - installation_mac.rst - installation_win.rst + Linux + macOS + Windows +Clone the Zephyr Repository +*************************** + +To clone the Zephyr source code repository from GitHub: + +.. code-block:: console + + git clone https://github.com/zephyrproject-rtos/zephyr + +.. warning:: + + Don't clone Zephyr to a directory with spaces anywhere in the path. + For example, on Windows, :file:`C:\\Users\\YourName\\zephyr` will + work, but :file:`C:\\Users\\Your Name\\zephyr` will cause cryptic + errors when you try to build an application. + +Install Python Dependencies +*************************** + +Next, install additional Python packages required by Zephyr in a shell or +``cmd.exe`` prompt: + +.. code-block:: console + + # Linux + pip3 install -r --user zephyr/scripts/requirements.txt + + # macOS and Windows + pip3 install -r zephyr/scripts/requirements.txt + +Some notes on pip's ``--user`` option: + +- Installing with ``--user`` is the default behavior on Debian-based + distributions and is generally recommended on Linux to avoid conflicts with + Python packages installed using the system package manager. + +- On macOS, Homebrew disables the ``--user`` flag\ [#homebrew_user]_. + +- On Windows using ``cmd.exe``, although it's possible to use the ``--user`` + flag, it makes it harder for the command prompt to find executables installed + by pip. + +Set Up a Toolchain +****************** + +.. note:: + + On Linux, you can skip this step if you installed the :ref:`Zephyr SDK + `, which includes toolchains for all supported Zephyr + architectures. + + If you want, you can use the SDK host tools (such as OpenOCD) with a + different toolchain by keeping the :envvar:`ZEPHYR_SDK_INSTALL_DIR` + environment variable set to the Zephyr SDK installation directory, while + setting :envvar:`ZEPHYR_TOOLCHAIN_VARIANT` appropriately for a non-SDK + toolchain. + +Zephyr binaries are compiled using software called a *toolchain*. You need to +*install* and *configure* a toolchain to develop Zephyr applications\ +[#tools_native_posix]_. + +Toolchains can be *installed* in different ways, including using installer +programs, system package managers, or simply downloading a zip file or other +archive and extracting the files somewhere on your computer. You *configure* +the toolchain by setting the environment variable +:envvar:`ZEPHYR_TOOLCHAIN_VARIANT` to a recognized value, along with some +additional variable(s) specific to that toolchain (usually, this is just one +more variable which contains the path where you installed the toolchain on your +file system). + +.. note:: + + In previous releases of Zephyr, the ``ZEPHYR_TOOLCHAIN_VARIANT`` variable + was called ``ZEPHYR_GCC_VARIANT``. + +The following toolchain installation options are available. The right choice +for you depends on where you want to run Zephyr and any other requirements you +may have. Check your :ref:`board-level documentation ` if you are +unsure about what choice to use. + +.. toctree:: + :maxdepth: 2 + + toolchain_3rd_party_x_compilers.rst + toolchain_other_x_compilers.rst + toolchain_custom_cmake.rst + + +To use the same toolchain in new sessions in the future you can make +sure the variables are set persistently. + +On macOS and Linux, you can set the variables by putting the ``export`` lines +setting environment variables in a file :file:`~/.zephyrrc`. On Windows, you +can put the ``set`` lines in :file:`%userprofile%\\zephyrrc.cmd`. These files +are used to modify your environment when you run ``zephyr-env.sh`` (Linux, +macOS) and ``zephyr-env.cmd`` (Windows), which you will learn about in the next +step. .. _getting_started_run_sample: -Building and Running an Application -*********************************** +Build and Run an Application +**************************** -Next, build a sample Zephyr application. You can then run it either in -emulation or using POSIX APIs available on your host. +Next, build a sample Zephyr application. You can then flash and run it on real +hardware using any supported host system. Depending on your operating system, +you can also run it in emulation with QEMU or as a native POSIX application. -If your board is supported by Zephyr (see :ref:`boards` for a list), -consult its documentation for flashing and running instructions. +.. _getting_started_cmake: -Building a Sample Application -============================= +A Brief Note on the Zephyr Build System +======================================= -Follow these steps to build the :ref:`hello_world` sample application -provided with Zephyr. +The Zephyr build system uses `CMake`_. CMake creates build systems in different +formats, called `generators`_. Zephyr supports the following generators: + + * ``Unix Makefiles``: Supported on UNIX-like platforms (Linux, macOS). + * ``Ninja``: Supported on all platforms. + +This documentation and Zephyr's continuous integration system mainly use +``Ninja``, but you should be able to use any supported generator to build +Zephyr applications. + +Build the Application +===================== + +Follow these steps to build the :ref:`hello_world` sample application provided +with Zephyr. + +Zephyr applications have to be configured and built to run on some hardware +configuration, which is called a "board"\ [#board_misnomer]_. These steps show +how to build the Hello World application for the :ref:`arduino_101` board. You +can build for a different board by changing ``arduino_101`` to another +supported value. See :ref:`boards` for more information, or run ``ninja usage`` +from the build directory (once you've run ``cmake``) to get a list. + +.. note:: + + If you want to re-use your existing build directory to build for another + board, you must delete that directory's contents first by running ``ninja + pristine``. #. Navigate to the main project directory: @@ -97,203 +176,53 @@ provided with Zephyr. # On Windows zephyr-env.cmd -#. Build the :ref:`hello_world` example for the `arduino_101` board, enter: +#. Build the Hello World sample for the ``arduino_101``: + + .. Note: we don't use :zephyr-app: here because we just told the user to cd + to ZEPHYR_BASE, so it's not necessary for clarity and would clutter the + instructions a bit. .. zephyr-app-commands:: - :zephyr-app: samples/hello_world + :app: samples/hello_world :board: arduino_101 - :build-dir: arduino_101 :goals: build On Linux/macOS you can also build with ``make`` instead of ``ninja``: .. zephyr-app-commands:: - :zephyr-app: samples/hello_world + :app: samples/hello_world :generator: make :host-os: unix :board: arduino_101 - :build-dir: arduino_101 :goals: build -You can build for a different board by defining the variable BOARD -with another of the supported boards, for example: +The main build products are in :file:`zephyr/samples/hello_world/build/zephyr`. +The final application binary in ELF format is named :file:`zephyr.elf` by +default. Other binary formats and byproducts such as disassembly and map files +will be present depending on the target and build system configuration. - .. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: arduino_due - :build-dir: arduino_due - :goals: build +Other sample projects demonstrating Zephyr's features are located in +:file:`zephyr/samples` and are documented in :ref:`samples-and-demos`. -For further information on the supported boards go see -:ref:`here `. Alternatively, run the following command to obtain a list -of the supported boards: +Run the Application by Flashing to Another Board +================================================ -.. code-block:: console +Most "real hardware" boards supported by Zephyr can be flashed by running +``ninja flash`` from the build directory. However, this may require +board-specific tool installation and configuration to work properly. - ninja usage +See :ref:`application_run` in the Application Development Primer and the +documentation provided with your board at :ref:`boards` for additional details +if you get an error. -Sample projects for different features of the project are available at -at :file:`ZEPHYR_BASE/samples`. -After building an application successfully, the results can be found in the -directory where cmake was invoked. +Run the Application in QEMU +=========================== -The ELF binaries generated by the build system are named by default -:file:`zephyr.elf`. This value can be overridden in the application -configuration The build system generates different names for different use cases -depending on the hardware and boards used. +On Linux and macOS, you can run Zephyr applications in emulation on your host +system using QEMU when targeting either the X86 or ARM Cortex-M3 architectures. -.. _sdkless_builds: - -Building without the Zephyr SDK -=============================== - -The Zephyr SDK is provided for convenience and ease of use. It provides -cross-compilers for all ports supported by the Zephyr OS and does not require -any extra flags when building applications or running tests. In addition to -cross-compilers, the Zephyr SDK also provides prebuilt host tools. - -It is, however, possible to build without the SDK. If you are using 3rd party -cross compilers, jump forward to `Using 3rd Party Cross Compilers`_ for -details. A "3rd party cross compiler" is a toolchain that the Zephyr build -system already knows about, such as `GNU ARM Embedded`_ that we use in this -document. - -If you are going to use custom compilers, check `Using Custom Cross Compilers`_ -for more detail. A "custom compiler" would be the one your Linux distribution -packaged, the one you compiled on your own, or the one you downloaded from the -net. The Zephyr build system doesn't know about them and doesn't officially -support them. - -As already noted above, the SDK also includes prebuilt host tools. To use the -SDK's prebuilt host tools alongside a 3rd party or custom cross-compiler, keep -the ZEPHYR_SDK_INSTALL_DIR environment variable set to the Zephyr SDK -installation directory. To build without the Zephyr SDK's prebuilt host tools, -the ZEPHYR_SDK_INSTALL_DIR environment variable must be unset - -Follow the steps below to build without the Zephyr SDK: - - .. code-block:: console - - # On Linux/macOS - unset ZEPHYR_SDK_INSTALL_DIR - cd - source zephyr-env.sh - # On Windows - set ZEPHYR_SDK_INSTALL_DIR= - cd - zephyr-env.cmd - -.. _third_party_x_compilers: - -Using 3rd Party Cross Compilers -=============================== - -To use a 3rd party cross compiler that is not provided by the Zephyr -SDK, follow the steps below. - -#. We will use the `GNU ARM Embedded`_ compiler for this example, download the - package suitable for your operating system from the `GNU ARM Embedded`_ website - and extract it on your file system. This example assumes the compiler was - extracted to: :file:`/gcc-arm-none-eabi-7-2018-q2-update/`. - -#. Build the example :ref:`hello_world` project, enter: - - .. code-block:: console - - # On Linux/macOS - export GNUARMEMB_TOOLCHAIN_PATH="~/gcc-arm-none-eabi-7-2018-q2-update/" - export ZEPHYR_TOOLCHAIN_VARIANT=gnuarmemb - # On Windows - set GNUARMEMB_TOOLCHAIN_PATH="%userprofile%\gcc-arm-none-eabi-7-2018-q2-update\" - set ZEPHYR_TOOLCHAIN_VARIANT=gnuarmemb - - .. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: arduino_due - :goals: build - -Make sure to unset the ZEPHYR_SDK_INSTALL_DIR if you don't use the -SDK's host tools. See `Building without the Zephyr SDK`_ for details. - -It is possible to use the Zephyr SDK's host tools along with a 3rd -party cross compiler. To do that, keep the ZEPHYR_SDK_INSTALL_DIR -environment variable set to the Zephyr SDK installation directory. -See `Set Up the Development Environment`_ for more details on the -ZEPHYR_SDK_INSTALL_DIR environment variable. - -Using Custom Cross Compilers -============================ - -To use a custom cross compiler, follow the steps below. - -#. Install a cross compiler suitable for your system. We will use the - gcc-arm-none-eabi compiler on Debian system for this example. - - .. code-block:: console - - # On Debian or Ubuntu - sudo apt-get install gcc-arm-none-eabi - # On Fedora or Red hat - sudo dnf install arm-none-eabi-newlib - -#. Build the example :ref:`hello_world` project, enter: - - .. code-block:: console - - # On Linux - unset GNUARMEMB_TOOLCHAIN_PATH - export ZEPHYR_TOOLCHAIN_VARIANT=cross-compile - export CROSS_COMPILE=/usr/bin/arm-none-eabi- - - .. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: arduino_zero - :goals: build - -Note that the Zephyr build system assumes that all the tools within your -toolchain used to compile and link your code, reside in the same directory and -have a common prefix. Set the ``CROSS_COMPILE`` environment variable to the -path of your toolchain's location and that common prefix. In the example above, -gcc-arm-none-eabi is installed in ``/usr/bin/`` with the common prefix of -``arm-none-eabi-``. If your toolchain is at ``/opt/mytoolchain/bin`` with the -prefix of ``myarch-none-elf-``, it would be -``CROSS_COMPILE=/opt/mytoolchain/bin/arch-none-elf-``. - -Make sure to unset the ZEPHYR_SDK_INSTALL_DIR if you don't use the SDK's host -tools. See `Building without the Zephyr SDK`_ and `Set Up the Development -Environment`_ for more details. - -Using Custom Cmake Toolchains -============================= - -To use a custom toolchain defined in an external cmake file, export the -following environment variables: - - .. code-block:: console - - export ZEPHYR_TOOLCHAIN_VARIANT= - export TOOLCHAIN_ROOT= - -or set them as cmake variables: - - .. code-block:: console - - cmake -DZEPHYR_TOOLCHAIN_VARIANT=... -DTOOLCHAIN_ROOT=... - -Zephyr will then include the toolchain cmake file located in: -``/cmake/toolchain/.cmake`` - -Running a Sample Application in QEMU -==================================== - -To perform rapid testing of an application in the development environment you -can use the QEMU emulation board configuration available for both X86 and ARM -Cortex-M3 architectures. This can be easily accomplished by calling a special -target when building an application that invokes QEMU once the build process is -completed. - -To run an application using the x86 emulation board configuration (qemu_x86), -type: +To build and run Hello World using the x86 emulation board configuration +(``qemu_x86``), type: .. zephyr-app-commands:: :zephyr-app: samples/hello_world @@ -301,24 +230,22 @@ type: :board: qemu_x86 :goals: build run -To exit the qemu emulator, press ``Ctrl-a``, followed by ``x``. +To exit, type :kbd:`Ctrl-a`, then :kbd:`x`. -Use the ``qemu_cortex_m3`` board configuration to test the ARM build. - -QEMU is not supported on all boards and SoCs. When developing for a specific -hardware target you should always test on the actual hardware and should not -rely on testing in the QEMU emulation environment only. +Use the ``qemu_cortex_m3`` board configuration to run on an emulated Arm +Cortex-M3. Running a Sample Application natively (POSIX OS) ================================================ -It is also possible to compile some of the sample and test applications to run -as native process on a POSIX OS (e.g. Linux). -To be able to do this, remember to have installed the 32 bit libC if your OS is -natively 64bit. See the :ref:`native_posix` section on host dependencies -for more information. +Finally, it is also possible to compile some samples to run as native processes +on a POSIX OS. This is currently only tested on Linux hosts. -To compile and run an application in this way, type: +On 64 bit host operating systems, you will also need a 32 bit C library +installed. See the :ref:`native_posix` section on host dependencies for more +information. + +To compile and run Hello World in this way, type: .. zephyr-app-commands:: :zephyr-app: samples/hello_world @@ -339,9 +266,38 @@ and then: You can run ``zephyr/zephyr.exe --help`` to get a list of available options. See the :ref:`native_posix` document for more information. -This executable can be instrumented like any other Linux process. For ex. with gdb -or valgrind. -Note that the native port is currently only tested in Linux. +This executable can be instrumented using standard tools, such as gdb or +valgrind. + +.. rubric:: Footnotes + +.. [#homebrew_user] + + For details, see + https://docs.brew.sh/Homebrew-and-Python#note-on-pip-install---user. + +.. [#tools_native_posix] + + Usually, the toolchain is a cross-compiler and related tools which are + different than the host compilers and other programs available for + developing software to run natively on your operating system. + + One exception is when building Zephyr as a host binary to run on a POSIX + operating system. In this case, you still need to set up a toolchain, but it + will provide host compilers instead of cross compilers. For details on this + option, see :ref:`native_posix`. + +.. [#board_misnomer] + + This has become something of a misnomer over time. While the target can be, + and often is, a microprocessor running on its own dedicated hardware + board, Zephyr also supports using QEMU to run targets built for other + architectures in emulation, targets which produce native host system + binaries that implement Zephyr's driver interfaces with POSIX APIs, and even + running different Zephyr-based binaries on CPU cores of differing + architectures on the same physical chip. Each of these hardware + configurations is called a "board," even though that doesn't always make + perfect sense in context. -.. _GNU ARM Embedded: https://developer.arm.com/open-source/gnu-toolchain/gnu-rm .. _CMake: https://cmake.org +.. _generators: https://cmake.org/cmake/help/v3.8/manual/cmake-generators.7.html diff --git a/doc/getting_started/installation_linux.rst b/doc/getting_started/installation_linux.rst index a26e936272b..17297d1b9e0 100644 --- a/doc/getting_started/installation_linux.rst +++ b/doc/getting_started/installation_linux.rst @@ -3,32 +3,28 @@ Development Environment Setup on Linux ###################################### -This section describes how to set up a Linux development system. +.. important:: -After completing these steps, you will be able to compile and run your Zephyr -applications on the following Linux distributions: + This section only describes OS-specific setup instructions; it is the first step in the + complete Zephyr :ref:`getting_started`. -* Ubuntu 16.04 LTS 64-bit -* Fedora 25 64-bit +This section describes how to set up a Zephyr development environment on the +following Linux distributions: + +* Ubuntu 16.04 LTS or 18.04 LTS 64-bit +* Fedora 28 64-bit * Clear Linux -* Arch Linux (install `zephyr-sdk `_ package from AUR) +* Arch Linux -Where needed, alternative instructions are listed for specific Linux +Where needed, instructions are given which only apply to specific Linux distributions. -Installing the Host's Operating System -************************************** - -Building the project's software components including the kernel has been -tested on Ubuntu and Fedora systems. Instructions for installing these OSes -are beyond the scope of this document. - Update Your Operating System **************************** -Before proceeding with the build, ensure your OS is up to date. On Ubuntu, -you'll first need to update the local database list of available packages -before upgrading: +Ensure your host system is up to date before proceeding. + +On Ubuntu: .. code-block:: console @@ -42,7 +38,7 @@ On Fedora: sudo dnf upgrade Note that having a newer version available for an installed package -(and reported by ``dnf check-update``) does not imply a subsequent +(as reported by ``dnf check-update``) does not imply a subsequent ``dnf upgrade`` will install it, because it must also ensure dependencies and other restrictions are satisfied. @@ -52,43 +48,56 @@ On Clear Linux: sudo swupd update -Installing Requirements and Dependencies -**************************************** +On Arch Linux: -Install the following required packages using either apt-get or dnf. +.. code-block:: console -On Ubuntu host system: + sudo pacman -Syu + +Install Requirements and Dependencies +************************************* + +.. NOTE FOR DOCS AUTHORS: DO NOT PUT DOCUMENTATION BUILD DEPENDENCIES HERE. + + This section is for dependencies to build Zephyr binaries, *NOT* this + documentation. If you need to add a dependency only required for building + the docs, add it to doc/README.rst. (This change was made following the + introduction of LaTeX->PDF support for the docs, as the texlive footprint is + massive and not needed by users not building PDF documentation.) + +Install the following packages using your system's package manager. Note that +both Ninja and Make are installed; you may prefer only to install one. + +On Ubuntu: .. code-block:: console sudo apt-get install --no-install-recommends git cmake ninja-build gperf \ - ccache doxygen dfu-util device-tree-compiler \ - python3-ply python3-pip python3-setuptools python3-wheel xz-utils file \ - make gcc-multilib autoconf automake libtool librsvg2-bin \ - texlive-latex-base texlive-latex-extra latexmk texlive-fonts-recommended + ccache dfu-util device-tree-compiler wget \ + python3-pip python3-setuptools python3-wheel xz-utils file make -On Fedora host system: +On Fedora: .. code-block:: console - sudo dnf group install "Development Tools" "C Development Tools and Libraries" - sudo dnf install git cmake ninja-build gperf ccache\ - doxygen dfu-util dtc python3-pip \ - python3-ply python3-yaml dfu-util dtc python3-pykwalify \ - glibc-devel.i686 libstdc++-devel.i686 autoconf automake libtool \ - texlive-latex latexmk texlive-collection-fontsrecommended librsvg2-tools -On Clear Linux host system: + sudo dnf group install "Development Tools" "C Development Tools and Libraries" + dnf install git cmake ninja-build gperf ccache dfu-util dtc wget \ + python3-pip xz file glibc-devel.i686 libstdc++-devel.i686 + +On Clear Linux: .. code-block:: console sudo swupd bundle-add c-basic dev-utils dfu-util dtc \ - os-core-dev python-basic python3-basic texlive + os-core-dev python-basic python3-basic -Install additional packages required for development with Zephyr:: +On Arch: - cd ~/zephyr # or to your directory where zephyr is cloned - pip3 install --user -r scripts/requirements.txt +.. code-block:: console + + sudo pacman -S git cmake ninja gperf ccache dfu-util dtc wget \ + python-pip python-setuptools python-wheel xz file make CMake version 3.8.2 or higher is required. Check what version you have using ``cmake --version``; if you have an older version, check the backports or @@ -99,25 +108,30 @@ install a more recent version manually. For example, to install version wget https://cmake.org/files/v3.8/cmake-3.8.2-Linux-x86_64.sh yes | sh cmake-3.8.2-Linux-x86_64.sh | cat echo "export PATH=$PWD/cmake-3.8.2-Linux-x86_64/bin:\$PATH" >> $HOME/.zephyrrc - source /zephyr-env.sh cmake --version .. _zephyr_sdk: -Installing the Zephyr Software Development Kit -============================================== +Install the Zephyr Software Development Kit (SDK) +************************************************* + +.. note:: + + Use of the Zephyr SDK is optional, but recommended. Some of the requirements + and dependencies in the previous section are only needed for installing the + SDK. Zephyr's :abbr:`SDK (Software Development Kit)` contains all necessary tools -and cross-compilers needed to build the kernel on all supported +and cross-compilers needed to build Zephyr on all supported architectures. Additionally, it includes host tools such as custom QEMU binaries and a host compiler for building host tools if necessary. The SDK supports the -following architectures: +following target architectures: * :abbr:`X86 (Intel Architecture 32 bits)` * :abbr:`X86 IAMCU ABI (Intel Architecture 32 bits IAMCU ABI)` -* :abbr:`ARM (Advanced RISC Machines)` +* :abbr:`Arm (Advanced RISC Machine)` * :abbr:`ARC (Argonaut RISC Core)` @@ -147,7 +161,7 @@ Follow these steps to install the SDK on your Linux host system. .. important:: If this fails, make sure Zephyr's dependencies were installed - as described in `Installing Requirements and Dependencies`_. + as described in `Install Requirements and Dependencies`_. #. Follow the installation instructions on the screen. The toolchain's default installation location is :file:`/opt/zephyr-sdk/`, but it @@ -164,23 +178,29 @@ Follow these steps to install the SDK on your Linux host system. export ZEPHYR_TOOLCHAIN_VARIANT=zephyr export ZEPHYR_SDK_INSTALL_DIR= - To use the same toolchain in new sessions in the future, you can set the - variables in the file :file:`${HOME}/.zephyrrc`, for example: +.. _sdkless_builds: - .. code-block:: console +Building on Linux without the Zephyr SDK +**************************************** - cat < ~/.zephyrrc - export ZEPHYR_TOOLCHAIN_VARIANT=zephyr - export ZEPHYR_SDK_INSTALL_DIR=/opt/zephyr-sdk - EOF +The Zephyr SDK is provided for convenience and ease of use. It provides +toolchains for all Zephyr target architectures, and does not require any extra +flags when building applications or running tests. In addition to +cross-compilers, the Zephyr SDK also provides prebuilt host tools. It is, +however, possible to build without the SDK's toolchain by using another +toolchain as as described in the main :ref:`getting_started` document. - .. note:: - Use ```` in place of ``/opt/zephyr-sdk/`` in the - above shown example if the SDK installation location is not default. +As already noted above, the SDK also includes prebuilt host tools. To use the +SDK's prebuilt host tools with a toolchain from another source, keep the +:envvar:`ZEPHYR_SDK_INSTALL_DIR` environment variable set to the Zephyr SDK +installation directory. To build without the Zephyr SDK's prebuilt host tools, +the :envvar:`ZEPHYR_SDK_INSTALL_DIR` environment variable must be unset before +you run ``source zephyr-env.sh`` later on in the Getting Started Guide. +To make sure this variable is unset, run: - .. note:: In previous releases of Zephyr, the ``ZEPHYR_TOOLCHAIN_VARIANT`` - variable was called ``ZEPHYR_GCC_VARIANT``. +.. code-block:: console -.. _Zephyr Downloads: - https://www.zephyrproject.org/developers/#downloads + unset ZEPHYR_SDK_INSTALL_DIR + +.. _Zephyr Downloads: https://www.zephyrproject.org/developers/#downloads diff --git a/doc/getting_started/installation_mac.rst b/doc/getting_started/installation_mac.rst index a48dd01eb0b..a40214da61f 100644 --- a/doc/getting_started/installation_mac.rst +++ b/doc/getting_started/installation_mac.rst @@ -3,145 +3,54 @@ Development Environment Setup on macOS ###################################### -This section describes how to set up a macOS development system. +.. important:: -After completing these steps, you will be able to compile and run your Zephyr -applications on the following macOS version: + This section only describes OS-specific setup instructions; it is the first step in the + complete Zephyr :ref:`getting_started`. + +This section describes how to set up a Zephyr development environment on macOS. + +These instructions have been tested on the following macOS versions: * Mac OS X 10.11 (El Capitan) * macOS Sierra 10.12 -Developing for Zephyr on macOS generally requires you to build the -toolchain yourself. However, if there is already an macOS toolchain for your -target architecture you can use it directly. - -Using a 3rd Party toolchain -*************************** - -If a toolchain is available for the architecture you plan to build for, then -you can use it as explained in: :ref:`third_party_x_compilers`. - -An example of an available 3rd party toolchain is GCC ARM Embedded for the -Cortex-M family of cores. - -.. _mac_requirements: - -Installing Requirements and Dependencies -**************************************** - -To install the software components required to build the Zephyr kernel on a -Mac, you will need to build a cross compiler for the target devices you wish to -build for and install tools that the build system requires. - -.. note:: - Minor version updates of the listed required packages might also - work. +Update Your Operating System +**************************** Before proceeding with the build, ensure your OS is up to date. -First, install the :program:`Homebrew` (The missing package manager for -macOS). Homebrew is a free and open-source software package management system -that simplifies the installation of software on Apple's macOS operating -system. +.. _mac_requirements: -To install :program:`Homebrew`, visit the `Homebrew site`_ and follow the -installation instructions on the site. +Install Requirements and Dependencies +************************************* -To complete the Homebrew installation, you might be prompted to install some -missing dependency. If so, follow please follow the instructions provided. +.. NOTE FOR DOCS AUTHORS: DO NOT PUT DOCUMENTATION BUILD DEPENDENCIES HERE. + + This section is for dependencies to build Zephyr binaries, *NOT* this + documentation. If you need to add a dependency only required for building + the docs, add it to doc/README.rst. (This change was made following the + introduction of LaTeX->PDF support for the docs, as the texlive footprint is + massive and not needed by users not building PDF documentation.) + +.. note:: + + Zephyr requires Python 3, while macOS only provides a Python 2 + installation. After following these instructions, the version of Python 2 + provided by macOS in ``/usr/bin/`` will sit alongside the Python 3 + installation from Homebrew in ``/usr/local/bin``. + +First, install :program:`Homebrew` by following instructions on the `Homebrew +site`_. Homebrew is a free and open-source package management system that +simplifies the installation of software on macOS. While installing Homebrew, +you may be prompted to install additional missing dependencies; please follow +any such instructions as well. After Homebrew is successfully installed, install the following tools using -the brew command line. - -.. note:: - Zephyr requires Python 3 in order to be built. Since macOS comes bundled - only with Python 2, we will need to install Python 3 with Homebrew. After - installing it you should have the macOS-bundled Python 2 in ``/usr/bin/`` - and the Homebrew-provided Python 3 in ``/usr/local/bin``. - -Install tools to build Zephyr binaries: +the ``brew`` command line tool in the Terminal application. .. code-block:: console - brew install cmake ninja dfu-util doxygen qemu dtc python3 gperf - cd ~/zephyr # or to the folder where you cloned the zephyr repo - pip3 install --user -r scripts/requirements.txt - -.. note:: - If ``pip3`` does not seem to have been installed correctly use - ``brew reinstall python3`` in order to reinstall it. - -Source :file:`zephyr-env.sh` wherever you have cloned the Zephyr Git repository: - -.. code-block:: console - - unset ZEPHYR_SDK_INSTALL_DIR - cd - source zephyr-env.sh - -Finally, assuming you are using a 3rd-party toolchain you can try building the :ref:`hello_world` sample to check things out. - -To build for the ARM-based Nordic nRF52 Development Kit: - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: nrf52_pca10040 - :host-os: unix - :goals: build - -Install tools to build Zephyr documentation: - -.. code-block:: console - - brew install mactex librsvg - tlmgr install latexmk - tlmgr install collection-fontsrecommended - -.. _setting_up_mac_toolchain: - -Setting Up the Toolchain -************************ - -In case a toolchain is not available for the board you are using, you can build -a toolchain from scratch using crosstool-NG. Follow the steps on the -crosstool-NG website to `prepare your host -`_ - -Follow the `Zephyr SDK with Crosstool NG instructions `_ to build -the toolchain for various architectures. You will need to clone the ``sdk-ng`` -repo and run the following command:: - - ./go.sh - -.. note:: - Currently only i586 and arm builds are verified. - - -Repeat the step for all architectures you want to support in your environment. - -To use the toolchain with Zephyr, export the following environment variables -and use the target location where the toolchain was installed, type: - -.. code-block:: console - - export ZEPHYR_TOOLCHAIN_VARIANT=xtools - export XTOOLS_TOOLCHAIN_PATH=/Volumes/CrossToolNGNew/build/output/ - - -To use the same toolchain in new sessions in the future you can set the -variables in the file :file:`${HOME}/.zephyrrc`, for example: - -.. code-block:: console - - cat < ~/.zephyrrc - export XTOOLS_TOOLCHAIN_PATH=/Volumes/CrossToolNGNew/build/output/ - export ZEPHYR_TOOLCHAIN_VARIANT=xtools - EOF - -.. note:: In previous releases of Zephyr, the ``ZEPHYR_TOOLCHAIN_VARIANT`` - variable was called ``ZEPHYR_GCC_VARIANT``. - -.. _Homebrew site: http://brew.sh/ - -.. _crosstool-ng site: http://crosstool-ng.org + brew install cmake ninja gperf ccache dfu-util qemu dtc python3 +.. _Homebrew site: https://brew.sh/ diff --git a/doc/getting_started/installation_win.rst b/doc/getting_started/installation_win.rst index 29f3a3d4135..d9bbd8d07b7 100644 --- a/doc/getting_started/installation_win.rst +++ b/doc/getting_started/installation_win.rst @@ -3,7 +3,12 @@ Development Environment Setup on Windows ######################################## -This section describes how to configure your development environment and +.. important:: + + This section only describes OS-specific setup instructions; it is the first step in the + complete Zephyr :ref:`getting_started`. + +This section describes how to configure your development environment to build Zephyr applications in a Microsoft Windows environment. This guide was tested by building the Zephyr :ref:`hello_world` sample @@ -17,29 +22,49 @@ Windows system with the latest updates installed. .. _windows_requirements: -Installing Requirements and Dependencies -**************************************** +Install 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. +.. NOTE FOR DOCS AUTHORS: DO NOT PUT DOCUMENTATION BUILD DEPENDENCIES HERE. + + This section is for dependencies to build Zephyr binaries, *NOT* this + documentation. If you need to add a dependency only required for building + the docs, add it to doc/README.rst. (This change was made following the + introduction of LaTeX->PDF support for the docs, as the texlive footprint is + massive and not needed by users not building PDF documentation.) + +There are 3 different ways of developing for Zephyr on Microsoft Windows: + +#. :ref:`windows_install_native` +#. :ref:`windows_install_wsl` +#. :ref:`windows_install_msys2` + +The first option is fully Windows native; the rest require emulation layers +that may result in slower build times. All three are included 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 +option for performance and minimal dependency set. If you have a Unix tool +requirement, then we recommend trying the Windows Subsystem for Linux instead of +MSYS2. + +.. _windows_install_native: Option 1: Windows Command Prompt -=================================================== +================================ -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. +These instructions assume you are using the ``cmd.exe`` command prompt. Some of +the details, such as setting environment variables, may differ if you are using +PowerShell. + +The easiest way to install the 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. .. 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. + 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: @@ -50,12 +75,14 @@ packages from their respective websites. set HTTPS_PROXY=http://user:password@proxy.mycompany.com:1234 #. Install :program:`Chocolatey` by following the instructions on the - `Chocolatey install`_ website. + `Chocolatey install`_ page. -#. Open a Command Prompt (`cmd.exe`) as an **Administrator**. +#. 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"). -#. Optionally disable global confirmation to avoid having to add `-y` to all - commands: +#. Optionally disable global confirmation to avoid having to confirm + installation of individual programs: .. code-block:: console @@ -71,119 +98,40 @@ packages from their respective websites. .. code-block:: console - choco install git python ninja dtc-msys2 gperf doxygen.install + choco install git python ninja dtc-msys2 gperf -#. **Optionally** install the tools required to build the documentation in .pdf - format: +#. Close the Administrator command prompt window. - .. code-block:: console +.. NOTE FOR DOCS AUTHORS: as a reminder, do *NOT* put dependencies for building + the documentation itself here. - choco install strawberryperl miktex rsvg-convert +.. _windows_install_wsl: -#. Close the Command Prompt window. +Option 2: Windows 10 WSL (Windows Subsystem for Linux) +====================================================== -#. Open a Command Prompt (`cmd.exe`) as a **regular user**. +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 use software such as the :ref:`Zephyr SDK +` without setting up a virtual machine. -#. 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: - - .. code-block:: console - - cd %userprofile%\zephyr - pip3 install -r scripts/requirements.txt +#. `Install the Windows Subsystem for Linux (WSL)`_. .. 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. - Although pip can install packages in the user's directory by means - of the ``--user`` flag, this makes it harder for the Command Prompt - to find the executables in Python modules installed by ``pip3``. +#. Follow the Ubuntu instructions in the :ref:`installation_linux` document. -#. 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. +.. NOTE FOR DOCS AUTHORS: as a reminder, do *NOT* put dependencies for building + the documentation itself here. -#. Install cross compiler toolchain: +.. _windows_install_msys2: - * 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:\\gnuarmemb`). - -#. Within the Command Prompt, set up environment variables for the installed - tools and for the Zephyr environment: - - For x86: - - .. code-block:: console - - set ZEPHYR_TOOLCHAIN_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_TOOLCHAIN_VARIANT=gnuarmemb - set GNUARMEMB_TOOLCHAIN_PATH=c:\gnuarmemb - - To use the same toolchain in new sessions in the future you can set the - variables in the file :file:`%userprofile%\\zephyrrc.cmd`. - - And for either, run the :file:`zephyr-env.cmd` file in order to set the - :makevar:`ZEPHYR_BASE` environment variable: - - .. code-block:: console - - zephyr-env.cmd - - .. note:: In previous releases of Zephyr, the ``ZEPHYR_TOOLCHAIN_VARIANT`` - variable was called ``ZEPHYR_GCC_VARIANT``. - -#. 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. - -Option 2: MSYS2 +Option 3: MSYS2 =============== Alternatively, one can set up the Zephyr development environment with @@ -228,7 +176,7 @@ to set it up: .. code-block:: console pacman -Syu - pacman -S git cmake make gcc dtc diffutils ncurses-devel python3 gperf + pacman -S git cmake make gcc dtc diffutils ncurses-devel python3 gperf tar #. Compile :program:`Ninja` from source (Ninja is not available as an MSYS2 package) and install it: @@ -240,130 +188,29 @@ to set it up: ./configure.py --bootstrap cp ninja.exe /usr/bin/ -#. 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. +You're now almost ready to continue with the rest of the getting started guide. -#. 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:\\gnuarmemb`). - -#. Within the MSYS console, set up environment variables for the installed - tools and for the Zephyr environment (using the provided shell script): - - For x86: +Since you're using MSYS2, when you're cloning Zephyr in the next step of the +guide, use this command line instead (i.e. add the ``--config +core.autocrlf=false`` option). .. code-block:: console - export ZEPHYR_TOOLCHAIN_VARIANT=issm - export ISSM_INSTALLATION_PATH=/c/issm0-toolchain-windows-2017-01-25 + git clone --config core.autocrlf=false https://github.com/zephyrproject-rtos/zephyr - Use the path where you extracted the ISSM toolchain. +Furthermore, when you start installing Python dependencies, you'll want to add +the ``--user`` option as is recommended on Linux. - For ARM: +.. NOTE FOR DOCS AUTHORS: as a reminder, do *NOT* put dependencies for building + the documentation itself here. - .. code-block:: console - - export ZEPHYR_TOOLCHAIN_VARIANT=gnuarmemb - export GNUARMEMB_TOOLCHAIN_PATH=/c/gnuarmemb - - And for either, run the provided script to set up zephyr project specific - variables: - - .. code-block:: console - - unset ZEPHYR_SDK_INSTALL_DIR - cd - source zephyr-env.sh - -#. 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. - -Option 3: 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: 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 +.. _Install the Windows Subsystem for Linux (WSL): https://msdn.microsoft.com/en-us/commandline/wsl/install_guide diff --git a/doc/getting_started/toolchain_3rd_party_x_compilers.rst b/doc/getting_started/toolchain_3rd_party_x_compilers.rst new file mode 100644 index 00000000000..2ebfbe611e9 --- /dev/null +++ b/doc/getting_started/toolchain_3rd_party_x_compilers.rst @@ -0,0 +1,120 @@ +.. _third_party_x_compilers: + +3rd Party Toolchains +#################### + +A "3rd party toolchain" is an officially supported toolchain provided by an +external organization. Several of these are available. + +GNU ARM Embedded +**************** + +#. Download and install a `GNU ARM Embedded`_ build for your operating system + and extract it on your file system. + + .. warning:: + + Like the Zephyr repository, do not install the toolchain in a directory + with spaces anywhere in the path. On Windows, we'll assume you install + into the directory :file:`C:\\gnu_arm_embedded`. + +#. Configure the environment variables needed to inform the Zephyr build system + to use this toolchain: + + - Set :envvar:`ZEPHYR_TOOLCHAIN_VARIANT` to ``gnuarmemb``. + - Set :envvar:`GNUARMEMB_TOOLCHAIN_PATH` to the toolchain installation + directory. + + For example: + + .. code-block:: console + + # Linux or macOS + export ZEPHYR_TOOLCHAIN_VARIANT=gnuarmemb + export GNUARMEMB_TOOLCHAIN_PATH="~/gnu_arm_embedded" + + # Windows in cmd.exe + set ZEPHYR_TOOLCHAIN_VARIANT=gnuarmemb + set GNUARMEMB_TOOLCHAIN_PATH="C:\gnu_arm_embedded" + +Intel ISSM +********** + +.. 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. + +#. Install the ISSM toolchain by downloading it from the Intel Developer Zone's + `ISSM Toolchain`_ downloads page, then extracting the archive somewhere on + your system. + + .. warning:: + + Like the Zephyr repository, do not install the toolchain in a directory + with spaces anywhere in the path. + +#. Configure the environment variables needed to inform the Zephyr build system + to use this toolchain: + + - Set :envvar:`ZEPHYR_TOOLCHAIN_VARIANT` to ``issm``. + - Set :envvar:`ISSM_INSTALLATION_PATH` to the directory containing the + extracted files. + + For example: + + .. code-block:: console + + # Linux + export ZEPHYR_TOOLCHAIN_VARIANT=issm + export ISSM_INSTALLATION_PATH=/home/you/Downloads/issm0-toolchain-windows-2017-02-07 + + # Windows in cmd.exe + set ZEPHYR_TOOLCHAIN_VARIANT=issm + set ISSM_INSTALLATION_PATH=c:\issm0-toolchain-windows-2017-01-25 + +.. _xtools_x_compilers: + +Crosstool-NG +************ + +You can build toolchains from source code using crosstool-NG. + +#. Follow the steps on the crosstool-NG website to `prepare your host + `_. + +#. Follow the `Zephyr SDK with Crosstool NG instructions + `_ to + build your toolchain. Repeat as necessary to build toolchains for multiple + target architectures. + + You will need to clone the ``sdk-ng`` repo and run the following command: + + .. code-block:: console + + ./go.sh + + .. note:: + + Currently, only i586 and Arm toolchain builds are verified. + +#. Configure the environment variables needed to inform the Zephyr build system + to use this toolchain: + + - Set :envvar:`ZEPHYR_TOOLCHAIN_VARIANT` to ``xtools``. + - Set :envvar:`XTOOLS_TOOLCHAIN_PATH` to the toolchain build directory. + + For example: + + .. code-block:: console + + export ZEPHYR_TOOLCHAIN_VARIANT=xtools + export XTOOLS_TOOLCHAIN_PATH=/Volumes/CrossToolNGNew/build/output/ + +.. _GNU ARM Embedded: https://developer.arm.com/open-source/gnu-toolchain/gnu-rm +.. _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 +.. _crosstool-ng site: http://crosstool-ng.org diff --git a/doc/getting_started/toolchain_custom_cmake.rst b/doc/getting_started/toolchain_custom_cmake.rst new file mode 100644 index 00000000000..86714a6cdcb --- /dev/null +++ b/doc/getting_started/toolchain_custom_cmake.rst @@ -0,0 +1,27 @@ +.. _custom_cmake_toolchains: + +Custom CMake Toolchains +####################### + +To use a custom toolchain defined in an external CMake file, export the +following environment variables: + +.. code-block:: console + + # Linux and macOS + export ZEPHYR_TOOLCHAIN_VARIANT= + export TOOLCHAIN_ROOT= + + # Windows + set ZEPHYR_TOOLCHAIN_VARIANT= + set TOOLCHAIN_ROOT= + +You can also set them as CMake variables when generating a build +system for a Zephyr application, like so: + +.. code-block:: console + + cmake -DZEPHYR_TOOLCHAIN_VARIANT=... -DTOOLCHAIN_ROOT=... + +Zephyr will then include the toolchain cmake file located in: +``/cmake/toolchain/.cmake``. diff --git a/doc/getting_started/toolchain_other_x_compilers.rst b/doc/getting_started/toolchain_other_x_compilers.rst new file mode 100644 index 00000000000..d5f2cb90889 --- /dev/null +++ b/doc/getting_started/toolchain_other_x_compilers.rst @@ -0,0 +1,58 @@ +.. _other_x_compilers: + +Other Cross Compilers +###################### + +This toolchain variant is borrowed from the Linux kernel build system's +mechanism of using a :envvar:`CROSS_COMPILE` environment variable to set up a +GNU-based cross toolchain. + +Examples of such "other cross compilers" are cross toolchains that your Linux +distribution packaged, that you compiled on your own, or that you downloaded +from the net. Unlike toolchains specifically listed in +:ref:`third_party_x_compilers`, the Zephyr build system may not have been +tested with them, and doesn't officially support them. (Nonetheless, the +toolchain set-up mechanism itself is supported.) + +Follow these steps to use one of these toolchains. + +#. Install a cross compiler suitable for your host and target systems. + + For example, you might install the ``gcc-arm-none-eabi`` package on + Debian-based Linux systems, or ``arm-none-eabi-newlib`` on Fedora or Red + Hat: + + .. code-block:: console + + # On Debian or Ubuntu + sudo apt-get install gcc-arm-none-eabi + # On Fedora or Red Hat + sudo dnf install arm-none-eabi-newlib + +#. Configure the environment variables needed to inform the Zephyr build system + to use this toolchain: + + - Set :envvar:`ZEPHYR_TOOLCHAIN_VARIANT` to ``cross-compile``. + - Set :envvar:`CROSS_COMPILE` to the common path prefix which your + toolchain's binaries have, e.g. the path to the directory containing the + compiler binaries plus the target triplet and trailing dash. + + Continuing the above Debian or Ubuntu example: + + .. code-block:: console + + export ZEPHYR_TOOLCHAIN_VARIANT=cross-compile + export CROSS_COMPILE=/usr/bin/arm-none-eabi- + + You can also set ``CROSS_COMPILE`` as a CMake variable, or using the Kconfig + symbol :option:`CONFIG_CROSS_COMPILE`. + +When using this option, all of your toolchain binaries must reside in the same +directory and have a common file name prefix. The ``CROSS_COMPILE`` variable +is set to the directory concatenated with the file name prefix. In the Debian +example above, the ``gcc-arm-none-eabi`` package installs binaries such as +``arm-none-eabi-gcc`` and ``arm-none-eabi-ld`` in directory ``/usr/bin/``, so +the common prefix is ``/usr/bin/arm-none-eabi-`` (including the trailing dash, +``-``). If your toolchain is installed in ``/opt/mytoolchain/bin`` with binary +names based on target triplet ``myarch-none-elf``, ``CROSS_COMPILE`` would be +set to ``/opt/mytoolchain/bin/myarch-none-elf-``.