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
- Connect your Azure Sphere device to your computer
- Install Azure Sphere
Compile and build the application
Create or navigate to the directory that will contain the files to be generated during the build process.
If your application depends on another application, mark the applications as partners in their app_manifest.md files.
Add or update the CMakeLists.txt file for your application to call the Azure Sphere CMake functions as necessary.
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.
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.
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
--componentidparameter to specify which application to delete. You can find the component ID of the application in its app_manifest.json file.
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:
<ComponentID> App state : debugging GDB port : 2345 Output port : 2342 Core : High-level Command completed successfully in 00:00:00.9121174.
Open a command prompt and use any Windows terminal client to read the output stream from the process. Specify 192.168.35.2 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.
In the Azure Sphere Developer Command Prompt window, start the gdb command-line debugger:
Issue whatever gdb commands you choose. For example:
target remote 192.168.35.2:2345
targetcommand specifies remote debugging to IP address 192.168.35.2 on port 2345. The
ccommands set a breakpoint upon entry to main() and then continue execution after the breakpoint, respectively. Numerous sources of documentation are available for gdb.