Build, deploy, and debug a high-level application from the Windows command line

This section shows how to build, package, and debug an Azure Sphere high-level application from the command line. To build your application you will need to find the correct compilation tools, headers, and libraries—collectively called the sysroot—on your computer. The Azure Sphere SDK ships with multiple sysroots so that applications can target different API sets, as described in Application runtime version, sysroots, and Beta APIs. The sysroots are installed in the Azure Sphere SDK installation folder under Sysroots.

The instructions that follow use the HelloWorld_HighLevelApp sample application as an example.

Prepare for development

Compile and build the application

  1. Create or navigate to the directory that will contain the files to be generated during the build process.

  2. If your application depends on another application, mark the applications as partners in their files.

  3. Add or update the CMakeLists.txt file for your application to call the Azure Sphere CMake functions as necessary.

  4. At an Azure Sphere Developer Command Prompt, run CMake by entering the following command:

    cmake [options] <path to sample source>

    For example, to build the HelloWorld_HighLevelApp sample you would enter the following at the command line:

    cmake ^
     -G "Ninja" ^
    -DCMAKE_TOOLCHAIN_FILE="C:\Program Files (x86)\Microsoft Azure Sphere SDK\CMakeFiles\AzureSphereToolchain.cmake" ^
    -DAZURE_SPHERE_TARGET_API_SET="latest-lts" ^
    -DCMAKE_BUILD_TYPE="Debug" ^
       <path to cloned samples>\azure-sphere-samples\Samples\HelloWorld\HelloWorld_HighLevelApp

      The location of the compiler tool chain file. In the example it is set to the default location of the toolchain file that is installed with the Azure Sphere SDK.


      The main definition of the target API set is in the application's CMakeLists.txt file. This can variable can typically be set to "latest-lts" or "latest-beta".


      The build type. Possible values are Debug and Release.

    CMake places the resulting build files in the current directory.

  5. Build the application and create the .imagepackage file by running ninja on the command line:


    Ninja places the resulting application and .imagepackage files in the current directory.

Deploy the application

Make sure your device has the appDevelopment capability so you can sideload the application and ensure that the debugging server is present. Use the azsphere device enable-development command if necessary.

  1. If your device is already running one or more applications, delete them.

    azsphere device sideload delete

    Note that this command deletes all the applications on the device. If you've already deployed an RTApp that is a partner to the high-level app, use the --componentid parameter to specify which application to delete. You can find the component ID of the application in its app_manifest.json file.

  2. Run the azsphere device sideload deploy command to sideload the application onto the device and start it:

    azsphere device sideload deploy --imagepackage manual.imagepackage

    Your application should start running.

You can later stop and restart the application by using the azsphere device app stop -i <component ID> and azsphere device app start -i <component ID> commands.

Debug the application

To debug the application, stop it and then restart it with the --debug option:

azsphere device app stop --componentid <ComponentID>

azsphere device app start --debug --componentid <ComponentID>

You should see:

App state   : debugging
GDB port    : 2345
Output port : 2342
Core        : High-level

Command completed successfully in 00:00:00.9121174.
  1. Open a command prompt and use any Windows terminal client to read the output stream from the process. Specify as the IP address and 2342 as the port.

    Windows terminal clients include PuTTY, Tera Term and many others. Windows includes the Windows Telnet client as an optional feature. To enable the Windows Telnet client, open Control Panel and click Programs. In Programs and Features, click Turn Windows features on or off. Scroll down to Telnet client, click the check box, and then click OK.

  2. In the Azure Sphere Developer Command Prompt window, start the gdb command-line debugger:

    arm-poky-linux-musleabi-gdb HelloWorld_HighLevelApp.out

    Issue whatever gdb commands you choose. For example:

    target remote break main c

    The target command specifies remote debugging to IP address on port 2345. The break and c commands set a breakpoint upon entry to main() and then continue execution after the breakpoint, respectively. Numerous sources of documentation are available for gdb.