.. _gs_installing: Installing the |ZSDK| manually ############################## .. contents:: :local: :depth: 2 .. note:: If you prefer to install the toolchain manually, or if you run into problems during the installation process, see the following documentation for instructions. To manually install the |ZSDK|, you must install all required tools and clone the |ZSDK| repositories. See the following sections for detailed instructions. The first two steps, `Installing the required tools`_ and `Installing the toolchain`_, are identical to the installation in Zephyr. If you already have your system set up to work with the Zephyr OS, you can skip these steps. See :ref:`gs_installing_os` for information on the supported operating systems and Zephyr features. .. _gs_installing_tools: Installing the required tools ***************************** The installation process is different depending on your operating system. .. tabs:: .. group-tab:: Windows The recommended way for installing the required tools on Windows is to use Chocolatey, a package manager for Windows. Chocolatey installs the tools so that you can use them from a Windows command prompt. To install the required tools, follow the :ref:`install-required-tools` section for Windows in Zephyr's :ref:`zephyr:getting_started`. .. group-tab:: Linux To install the required tools on Linux, follow the :ref:`install-required-tools` section for Linux in Zephyr's :ref:`zephyr:getting_started`. Additional information is available in the :ref:`zephyr:linux_requirements` section. .. note:: You do not need to install the Zephyr SDK. We recommend to install the compiler toolchain separately, as detailed in `Installing the toolchain`_. .. group-tab:: macOS To install the required tools, follow the :ref:`install-required-tools` section for macOS in Zephyr's :ref:`zephyr:getting_started`. Install Homebrew and install the required tools using the ``brew`` command line tool. Also see :ref:`zephyr:mac-setup-alts` for additional information. If you are interested in building `Project Connected Home over IP`_ applications, install also the `GN`_ meta-build system to generate the Ninja files that the |ZSDK| uses. .. tabs:: .. group-tab:: Windows To install the GN tool, complete the following steps: 1. Download the latest version of the GN binary archive for Windows from the `GN website`_. 2. Extract the :file:`zip` archive. 3. Ensure that the GN tool is added to your :envvar:`PATH` :ref:`environment variable `. .. group-tab:: Linux To install the GN tool, complete the following steps: 1. Download the GN binary archive and extract it by using the following commands: .. parsed-literal:: :class: highlight mkdir ${HOME}/gn && cd ${HOME}/gn wget -O gn.zip https:\ //chrome-infra-packages.appspot.com/dl/gn/gn/linux-amd64/+/latest unzip gn.zip rm gn.zip #. Add the location of the GN tool to the system PATH. For example, if you are using ``bash``, run the following commands: .. parsed-literal:: :class: highlight echo 'export PATH=${HOME}/gn:"$PATH"' >> ${HOME}/.bashrc source ${HOME}/.bashrc .. group-tab:: macOS To install the GN tool, complete the following steps: 1. Download the GN binary archive and extract it by using the following commands: .. parsed-literal:: :class: highlight mkdir ${HOME}/gn && cd ${HOME}/gn wget -O gn.zip https:\ //chrome-infra-packages.appspot.com/dl/gn/gn/mac-amd64/+/latest unzip gn.zip rm gn.zip #. Add the location of the GN tool to the system PATH. For example, if you are using ``bash``, run the following commands: .. parsed-literal:: :class: highlight echo 'export PATH=${HOME}/gn:"$PATH"' >> ${HOME}/.bashrc source ${HOME}/.bashrc .. _gs_installing_toolchain: Installing the toolchain ************************ To be able to cross-compile your applications for Xtensa targets, you must install version 8.0.15 Xplorer. .. important:: Make sure to install the version that is mentioned above. Other versions might not work with this version of the |ZSDK|. Note that other versions of the |ZSDK| might require a different toolchain version. To set up the toolchain, complete the following steps: .. _toolchain_setup: 1. Download the Xplorer for your operating system. Make sure that the folder name does not contain any spaces or special characters. #. If you want to build and program applications from the command line, define the environment variables for the XCC toolchain. Depending on your operating system: .. tabs:: .. group-tab:: Windows Open a command prompt and enter the following commands (assuming that you have installed the toolchain to ``c:\gnuarmemb``; if not, change the value for GNUARMEMB_TOOLCHAIN_PATH): .. parsed-literal:: :class: highlight set ZEPHYR_TOOLCHAIN_VARIANT=xcc set XCC_TOOLCHAIN_PATH=\ c:\\usr\\xtensa .. group-tab:: Linux Open a terminal window and enter the following commands (assuming that you have installed the toolchain to ``~/gnuarmemb``; if not, change the value for GNUARMEMB_TOOLCHAIN_PATH): .. parsed-literal:: :class: highlight export ZEPHYR_TOOLCHAIN_VARIANT=xcc export XTENSA_TOOLCHAIN_PATH=\ "~/usr/xtensa" .. group-tab:: macOS Open a terminal window and enter the following commands (assuming that you have installed the toolchain to ``~/gnuarmemb``; if not, change the value for GNUARMEMB_TOOLCHAIN_PATH): .. parsed-literal:: :class: highlight export ZEPHYR_TOOLCHAIN_VARIANT=xcc export XTENSA_TOOLCHAIN_PATH=\ "~/usr/xtensa" #. Set the environment variables persistently. Depending on your operating system: .. tabs:: .. group-tab:: Windows Add the environment variables as system environment variables or define them in the ``%userprofile%\zephyrrc.cmd`` file as described in `Setting up the build environment`_. This will allow you to avoid setting them every time you open a command prompt. .. group-tab:: Linux Define the environment variables in the ``~/.zephyrrc`` file as described in `Setting up the build environment`_. This will allow you to avoid setting them every time you open a terminal window. .. group-tab:: macOS Define the environment variables in the ``~/.zephyrrc`` file as described in `Setting up the build environment`_. This will allow you to avoid setting them every time you open a terminal window. .. _cloning_the_repositories_win: .. _cloning_the_repositories: Getting the |ZSDK| code *********************** The |ZSDK| consists of a set of Git repositories. Every |ZSDK| release consists of a combination of these repositories at different revisions. The revision of each of those repositories is determined by the current revision of the main (or manifest) repository, `ZCAN-sdk`_. .. note:: The latest state of development is on the master branch of the `ZCAN-sdk`_ repository. To ensure a usable state, the `ZCAN-sdk`_ repository defines the compatible states of the other repositories. However, this state is not necessarily tested. For a higher degree of quality assurance, check out a tagged release. Therefore, unless you are familiar with the development process, you should always work with a specific release of the |ZSDK|. To manage the combination of repositories and versions, the |ZSDK| uses :ref:`zephyr:west`. The main repository, `ZCAN-sdk`_, contains a `west manifest file`_, :file:`west.yml`, that determines the revision of all other repositories. This means that ZCAN-sdk acts as the :ref:`manifest repository `, while the other repositories are project repositories. You can find additional information about the repository and development model in the :ref:`development model section `. See the :ref:`west documentation ` for detailed information about the tool itself. Installing west =============== Install west by entering the following command: .. tabs:: .. group-tab:: Windows .. parsed-literal:: :class: highlight pip3 install west .. group-tab:: Linux .. parsed-literal:: :class: highlight pip3 install --user west .. group-tab:: macOS .. parsed-literal:: :class: highlight pip3 install west You only need to do this once. .. _west_update: Like any other Python package, the west tool is updated regularly. Therefore, remember to regularly check for updates: .. tabs:: .. group-tab:: Windows .. parsed-literal:: :class: highlight pip3 install -U west .. group-tab:: Linux .. parsed-literal:: :class: highlight pip3 install --user -U west .. group-tab:: macOS .. parsed-literal:: :class: highlight pip3 install -U west Cloning the repositories ======================== .. tip:: If you cloned the |ZSDK| repositories before they were moved to the nrfconnect GitHub organization and want to update them, follow the instructions in :ref:`repo_move`. To clone the repositories, complete the following steps: 1. Create a folder named ``ZCAN-IOT``. This folder will hold all |ZSDK| repositories. #. Open a command window in the ``ncs`` folder. #. Determine what revision of the |ZSDK| you want to work with. The recommended way is to work with a specific release. * To work with a specific release, the revision is the corresponding tag (for example, |release_tt|). You can find the tag in the :ref:`release_notes` of the release. * To work with a development tag, the revision is the corresponding tag (for example, ``v1.2.99-dev1``) * To work with a branch, the revision is the branch name (for example, ``master`` to work with the latest state of development). * To work with a specific state, the revision is the SHA (for example, ``224bee9055d986fe2677149b8cbda0ff10650a6e``). #. Initialize west with the revision of the |ZSDK| that you want to check out, replacing *ZSDK_revision* with the revision: .. parsed-literal:: :class: highlight west init -m https\://gitee.com/ZCAN-IOT/ZCAN-sdk For example, to check out the |release| release, enter the following command: .. parsed-literal:: :class: highlight west init -m https\://gitee.com/ZCAN-IOT/ZCAN-sdk To check out the latest state of development, enter the following command:: west init -m https://gitee.com/ZCAN-IOT/ZCAN-sdk .. west-error-start .. note:: If you get an error message when running west, :ref:`update west ` to the latest version. See :ref:`zephyr:west-troubleshooting` if you need more information. .. west-error-end Initializing west with a specific revision of the manifest file does not lock your repositories to this version. Checking out a different branch or tag in the `ZCAN-sdk`_ repository and running ``west update`` changes the version of the |ZSDK| that you work with. This will clone the manifest repository `ZCAN-sdk`_ into :file:`ZCAN-sdk`. #. Enter the following command to clone the project repositories:: west update #. Export a :ref:`Zephyr CMake package `. This allows CMake to automatically load the boilerplate code required for building |ZSDK| applications:: west zephyr-export Your directory structure now looks similar to this:: ncs |___ .west |___ bootloader |___ modules |___ ZCAN-sdk |___ ZCAN-xlib |___ zephyr |___ ... Note that there are additional folders, and that the structure might change. The full set of repositories and folders is defined in the manifest file. Updating the repositories ========================= If you work with a specific release of the |ZSDK|, you do not need to update your repositories, because the release will not change. However, you might want to switch to a newer release or check out the latest state of development. To manage the ``ZCAN-sdk`` repository (the manifest repository), use Git. To make sure that you have the latest changes, run ``git fetch origin`` to :ref:`fetch the latest code ` from the `ZCAN-sdk`_ repository. Checking out a branch or tag in the ``ZCAN-sdk`` repository gives you a different version of the manifest file. Running ``west update`` will then update the project repositories to the state specified in this manifest file. .. include:: ../../../zcansdk/gs_installing.rst :start-after: west-error-start :end-before: west-error-end For example, to switch to release |release| of the |ZSDK|, enter the following commands in the ``ZCAN-IOT/ZCAN-sdk`` directory: .. parsed-literal:: :class: highlight git fetch origin git checkout |release| west update To update to a particular revision (SHA), make sure that you have that particular revision locally before you check it out (by running ``git fetch origin``):: git fetch origin git checkout 224bee9055d986fe2677149b8cbda0ff10650a6e west update To switch to the latest state of development, enter the following commands:: git fetch origin git checkout origin/master west update .. note:: Run ``west update`` every time you change or modify the current working branch (for example, when you pull, rebase, or check out a different branch). This will bring the project repositories to the matching revision defined by the manifest file. Installing additional Python dependencies ***************************************** The |ZSDK| requires additional Python packages to be installed. Use the following commands to install the requirements for each repository. .. tabs:: .. group-tab:: Windows Open a command prompt in the ``ZCAN-IOT`` folder and enter the following commands: .. parsed-literal:: :class: highlight pip3 install -r zephyr/scripts/requirements.txt pip3 install -r ZCAN-sdk/scripts/requirements.txt pip3 install -r bootloader/mcuboot/scripts/requirements.txt .. group-tab:: Linux Open a terminal window in the ``ZCAN-IOT`` folder and enter the following commands: .. parsed-literal:: :class: highlight pip3 install --user -r zephyr/scripts/requirements.txt pip3 install --user -r ZCAN-sdk/scripts/requirements.txt pip3 install --user -r bootloader/mcuboot/scripts/requirements.txt .. group-tab:: macOS Open a terminal window in the ``ZCAN-IOT`` folder and enter the following commands: .. parsed-literal:: :class: highlight pip3 install -r zephyr/scripts/requirements.txt pip3 install -r ZCAN-sdk/scripts/requirements.txt pip3 install -r bootloader/mcuboot/scripts/requirements.txt .. _build_environment_cli: Setting up the command line build environment ============================================= If you want to build and program your application from the command line, you must set up your build environment by defining the required environment variables every time you open a new command prompt or terminal window. See :ref:`zephyr:env_vars_important` information about the various relevant environment variables. Define the required environment variables as follows, depending on your operating system: .. tabs:: .. group-tab:: Windows Navigate to the ``ZCAN-IOT`` folder and enter the following command: ``zephyr\zephyr-env.cmd`` If you need to define additional environment variables, create the file ``%userprofile%\zephyrrc.cmd`` and add the variables there. This file is loaded automatically when you run the above command. .. group-tab:: Linux Navigate to the ``ZCAN-IOT`` folder and enter the following command: ``source zephyr/zephyr-env.sh`` If you need to define additional environment variables, create the file ``~/.zephyrrc`` and add the variables there. This file is loaded automatically when you run the above command. .. group-tab:: macOS Navigate to the ``ZCAN-IOT`` folder and enter the following command: ``source zephyr/zephyr-env.sh`` If you need to define additional environment variables, create the file ``~/.zephyrrc`` and add the variables there. This file is loaded automatically when you run the above command.