Build Tools

Purpose

The purpose of the update and build tools is to ensure the examples in this repo are updated to match the Azure Sphere SDK installed on your computer.

Supported platforms

The PowerShell build tools are supported on Linux and Windows.

Introduction

• Build All: Run the build_all tool after the Update Config tool. The build_all tool will build of all the projects in AzureSphereDevX.Examples folder. On completion, check the output of the build_all script to confirm success or failure of the build process.

Software requirements

For information on installing the following software on your computer, refer to the appendix.

1. Install the Azure Sphere SDK
2. Install PowerShell
3. Install CMake and Ninja
4. Install GNU Arm Embedded Toolchain. The build_all PowerShell script expects to find the toolchain at /opt/gcc-arm-none<version>

These examples are evergreen

Each examples automatically updates the CMake Azure Sphere configuration to match the Azure Sphere SDK you've installed on your computer. This is fine for examples, but for production applications, setting the Azure Sphere configuration in CMake should be intentional and tested.

In the CMakeLists.txt file, the auto_generate_azsphere_config CMake function is called to generate the azsphere_configure_tools and azsphere_configure_api settings.

if (EXISTS "${CMAKE_SOURCE_DIR}/Tools/cmake/azsphere_config.cmake")

    include(Tools/cmake/azsphere_config.cmake)
    auto_generate_azsphere_config()

else()

    # For information on setting tools revision and target api set see
    # https://docs.microsoft.com/en-us/azure-sphere/app-development/using-cmake-functions

    azsphere_configure_tools(TOOLS_REVISION "21.07")
    azsphere_configure_api(TARGET_API_SET "10")

endif()

For production applications, remove this block and replace it with the following CMake commands.

    azsphere_configure_tools(TOOLS_REVISION "<YOUR_TOOLS_VERSION>")
    azsphere_configure_api(TARGET_API_SET "<THE_TARGET_API_SET_YOU_ARE_TESTING_AGAINST")

Build All

The Build All tool:

1. builds all the examples in the \AzureSphereDevX.Examples folder.
2. assumes the Azure Sphere toolchains are installed in their default locations.

Follow these steps to run the Build All tool:

1. Open command prompt
2. Navigate to the AzureSphereDevX.Examples folder
3. Run the tool.

pwsh .\tools\build-tools\build_all.ps1

Note the completion status message to ensure all examples built correctly. The Build All tool will halt on the first error encountered.

---

Appendix

Install the Azure Sphere SDK

These tools and the examples in the AzureSphereDevX.Examples folder assume the latest Azure Sphere SDK is installed on your computer and the new CLI V2 is enabled.

Install PowerShell

Install latest version of PowerShell on your computer.

• Linux
• Windows

Install CMake and Ninja

The tools require CMake and Ninja to be installed on your computer.

Windows

From the CMake website, download and install CMake .MSI file. Install for the current user, and add to the path.

Download Ninja zip file for Windows. To install Ninja, open the zip file, select Extract All, and note the file location of the extracted file ninja.exe.

Add the directory containing ninja.exe to your PATH environment variable. To find information about setting this environment variable in Windows, type "path" in the Search box.

Linux

On Linux, install the CMake and Ninja applications using the following command.

sudo apt install cmake ninja-build

Install the GNU Arm Embedded Toolchain for Azure Sphere real-time apps

There are real-time applications examples in the AzureSphereDevX.Examples folder.

Windows

Install the GNU Arm Embedded Toolchain for Windows.

1. Download the GNU Arm Embedded Toolchain for Windows.
2. Install the GNU Arm Embedded Toolchain

Linux

On Linux, you need to manually install the GNU Arm Embedded Toolchain. The Build All tool assumes the installation location is in the opt folder.

To install the GCC ARM compiler, follow these steps:

1. Download the GNU Arm Embedded Toolchain. At the time of writing this is Version gcc-arm-none-eabi-10.3-2021.07-x86_64-linux.tar.bz2.
2. Install the downloaded package. The following installs the toolchain in the /opt directory.

sudo tar -xjvf gcc-arm-none-eabi-10.3-2021.07-x86_64-linux.tar.bz2 -C /opt

1. Update your path. Open ~/.bashrc and add to the end.

export PATH=$PATH:/opt/gcc-arm-none-eabi-10.3-2021.07/bin

1. Optional: The real-time core debugger relies on the libncurses.so.5 library. Depending on your system setup, this library may already be install, if not, then run the following commands.

sudo add-apt-repository universe
sudo apt-get install libncurses5

Installing Azure Sphere SDK and toolchains in WSL (Ubuntu 20.04)

Tip: This assumes your default WSL distro is Ubuntu 20.04. Download required software from Windows. Navigate to Downloads folder, open a Windows command prompt in the Downloads folder, run wsl, this will open Ubuntu in the Windows downloads folder. From Ubuntu, install the required software.

1. Follow the guide to installing Azure Sphere for Linux tools.

2. Update the PATH statement in ~/.bashrc

   export PATH=/opt/azurespheresdk/Tools_v2:$PATH
   export PATH=/opt/gcc-arm-none-eabi-10.3-2021.07/bin:$PATH
   

3. Update the PATH for current session.

   source ~/.bashrc