Preview of using CMake Presets for Azure Sphere development

Marc Goodner

We are happy to announce that CMake Presets preview support is available in the Visual Studio 16.10 release as well as CMake Tools version 1.7 for Visual Studio Code.

Erika introduced CMake Presets and why you should use them, this post will focus on how they can be used for Azure Sphere development across Visual Studio, VS Code, and GitHub Actions for consistent build settings across your development team and CI system.

Azure Sphere is a comprehensive IoT security solution that is beyond the scope of this article. Azure Sphere projects are CMake based, and application development is in C (get started here).

As CMake Presets are still in preview in VS and VS Code they are not yet part of the Azure Sphere projects created by Visual Studio or VS Code. In the future they will be, as well as part of the official Azure Sphere samples. To collect early feedback on using CMake Presets for Azure Sphere I have prepared a GitHub template repository of the Azure Sphere blink project configured with CMake Presets you can use to follow this post.

Example from a GitHub Template

GitHub template repositories are a way you can create a new project from an existing repo as opposed to starting a fork. This is great for providing samples to start a new project from where there is no intention in cloning to send changes upstream. You can create your own repo on GitHub directly by selecting “Use this template” and then clone it locally. Or you can use the GitHub cli to create your own repo from the template locally and on GitHub in one step.

gh repo create azblink --template https://github.com/robotdad/AzureSphereBlink

Follow the prompts from the above command and it will create a repo in your GitHub account named azblink and create a local copy of it.

CMake Presets file

The CMakePresets.json file in this project has presets for debug and release builds on Windows and Linux. Both of these presets inherit from a common base configuration.

"name": "Base",
"description": "Base configuration using Ninja generator",
"hidden": true,
"generator": "Ninja",
"binaryDir": "${sourceDir}/build/${presetName}",
"architecture": {
    "value": "arm",
    "strategy": "external"
},
"cacheVariables": {
    "AZURE_SPHERE_TARGET_API_SET": "latest-lts"
}

This configuration is tagged as hidden which means it is not available to use directly, it is only for use to provide common settings to other presets. We can see that it is set to use Ninja as the build tool, and the output directory is configured here to derive from the configuration that is used. We can also see that the variable set for which Azure Sphere API set the project is configured for.

There are two other hidden presets: Windows-Base and Linux-Base. These inherit from the above Base configuration and each respectively set the CMake cache variable for the Azure Sphere toolchain file. That variable uses an environment variable that is set in each of these respective sections for the default Azure Sphere SDK installation location. You will also notice a vendor section that specifies a host OS. This is used by Visual Studio and VS Code to only surface that configuration option when it is on that OS. That reduces the possibility of selecting an invalid configuration.

Visual Studio

If you open this project in Visual Studio it will automatically select the Windows debug configuration and is ready to build with the implicit default build configuration. The launch configuration for Visual Studio in launch.vs.json is checked in as an exception under the .vs folder so debugging is preconfigured. You should not need to modify this file.

See our documentation for more information on how to configure and build with CMake Presets with Visual Studio.

VS Code

If you open this project in VS Code you will be prompted for which configuration to use. Select Debug. This occurs as settings.json is preconfigured to use the CMake Tools extension. When you build the project, you will be prompted for a build configuration, select default which is implicit from the selected configuration. To debug you need to have an Azure Sphere board attached.

This project does contain a devcontainer definition so you may be prompted to open in a devcontainer. This is supported so feel free to try that, it will work exactly as above including debugging.

Since there is a devcontainer definition this project can also be opened in GitHub Codespaces. Navigate to the repo you created and select the drop down on the Code button and then Open in Codespaces. In the web interface you can build the project. If you connect to the Codespace from VS Code you can also debug to a locally attached device.

See our documentation for more information on how to configure and build with CMake Presets with VS Code.

GitHub Actions

This project is preconfigured to use GitHub Actions. You can learn more about how to use GitHub Actions with Azure Sphere projects here. As CMake Presets are new the thing that varies from other samples and current guidance is the invocation of CMake. If you look in the .devcontainer/Dockerfile you will see it is a multistage definition with three targets, dev, debug-build, and release-build. The dev stage is simply the official Azure Sphere container image.  This is used for the interactive devcontainer. The other two stages inherit the dev stage as a base. Each of these stages copies the repo into the container, then run CMake with either the debug or release preset, and then set the appropriate entry point to the generated cache to start the build.

Look in the .github\workflows\ci.yml file and you will see minor changes from the official guidance to use the paths created in the build output through using CMake Presets.

If you followed along from the beginning and created your own repo from the template repository you should already have a successful build. Go to your repo on GitHub and navigate to the Actions tab. You should see a completed workflow for the initial commit. If you select that there will be an artifact with the Azure Sphere image package that can be deployed to a device directly or as part of a deployment to a device group.

What’s next?

CMake Presets integration in Visual Studio and Visual Studio Code is still in preview. We’ll continue to add to our integration and address your feedback in future release of Visual Studio and the CMake Tools extension for VS Code.

In Visual Studio, the best way to file a bug or suggest a feature is with the Send Feedback button in the upper right-hand corner of the IDE. See Visual Studio feedback options for more information.

In VS Code, the best way to file a bug or suggest a feature is by creating (or upvoting) an issue in the extension’s GitHub repository.

We’d love to learn how your team is adopting CMake Presets, for Azure Sphere or otherwise. If you have feedback or a success story to share, you can contact us at cmake@microsoft.com. You can also reach us on Twitter (@VisualC).

Marc Goodner Program Manager, C++

Follow