Use GitHub Codespaces to build and debug

If you have a GitHub Team or GitHub Enterprise Cloud subscription, you can use GitHub Codespaces to set up your project so that it builds inside a container hosted by GitHub. Using Visual Studio Code's Remote feature, you can connect the Visual Studio Code on your desktop to the Codespace and edit, build, deploy, and debug directly from the Codespace.

This topic discusses using GitHub Codespaces to edit, build, deploy, and debug your Azure Sphere apps remotely; Use containers for build and debug with Visual Studio Code describes the use of Visual Studio Code to edit, build, deploy, and debug your Azure Sphere apps in a container locally.

To use Codespaces, your project must be configured as a GitHub repository and also configured for use in a container. In this topic, you will create a new Blink project with the appropriate configuration.

Create a GitHub repository for your project

Create an empty GitHub repository as follows:

1. Log in to github.com.

2. From your GitHub home page, select the New button beside the word Repositories.

3. Give your repository a name, such as Blink, and select Create repository.

4. Under Quick setup--if you've done this kind of thing before, copy the HTTPS url for your repository.

5. At a command prompt, clone your new repository to your local desktop as follows:

   git clone <repository-url>
   

   You should see a warning that you have cloned an empty repository.

Create a new Blink project in your clone

Open Visual Studio Code and create a new project as follows:

1. Select View > Command Palette > Azure Sphere: Generate New Project.
2. Under Select a Template, select Blink.
3. In the Select Folder dialog, specify a folder in which to create the new project. (This can be anywhere—you will copy the contents of this folder to the GitHub repository previously created.)
4. Specify a project name that matches the name of your GitHub repository, such as Blink, and press Enter.
5. Copy your Azure Sphere project files (including all subfolders such as .vscode and HardwareDefinitions ) into your local clone, commit, and push the changes. You can then delete the project folder created in this section, as everything will be in the GitHub repository.

Set up the .devcontainer folder

In your GitHub repository's top-level directory, create a folder named .devcontainer. In this folder, create a file named devcontainer.json with the following content:

{
    "name": "Azure Sphere Blink",
    "runArgs": [ "--cap-add=SYS_PTRACE", "--security-opt", "seccomp=unconfined"],
    "build": {
        "dockerfile": "Dockerfile",
        "target": "dev"
    },

    // Use 'settings' to set *default* container specific settings.json values on container create.
    // You can edit these settings after create using File > Preferences > Settings > Remote.
    "settings": {
        "terminal.integrated.shell.linux": "/bin/bash"
    },

    // Use 'appPort' to create a container with published ports. If the port isn't working, be sure
    // your server accepts connections from all interfaces (0.0.0.0 or '*'), not just localhost.
    // "appPort": [],

    // Uncomment the next line to run commands after the container is created.
    // "postCreateCommand": "gcc -v",

    // Comment out the next line if you want to run as root instead
    "remoteUser": "vscode",

    // Add the IDs of extensions you want installed when the container is created in the array below.
    "extensions": [
        "ms-vscode.azure-sphere-tools",
        "ms-vscode.azure-sphere-tools-ui"
    ]
}

Next, create a file named Dockerfile in the .devcontainer folder with the following contents:

FROM mcr.microsoft.com/azurespheresdk:latest AS dev

FROM dev AS build
COPY ./ /src/
WORKDIR /out
RUN cmake -G "Ninja" -DCMAKE_TOOLCHAIN_FILE="/opt/azurespheresdk/CMakeFiles/AzureSphereToolchain.cmake" \
    -DAZURE_SPHERE_TARGET_API_SET="latest-lts" -DCMAKE_BUILD_TYPE="Release" "/src"
ENTRYPOINT [ "ninja" ]

The initial FROM line specifies the standard Azure Sphere Docker image as the base development container, and the second says to use that base container as the build environment. The COPY line copies the contents of the repository into the container's /src/ directory. The WORKDIR specifies the build directory. The RUN command provides the CMake command to generate the build files. Finally, the ENTRYPOINT specifies that ninja should be invoked to actually build the application.

Commit the changes to your GitHub project and push the changes.

Install the GitHub Codespaces extension

To install the GitHub Codespaces extension:

1. Open the GitHub repository folder in Visual Studio Code, if it is not already.
2. Open Extensions from the Visual Studio Code Activity Bar.
3. Search for "GitHub Codespaces" and install the GitHub Codespaces extension.

Create a codespace

1. Select View > Command Palette > Codespaces: Create New Codespace.

2. From the dropdown list of repositories, select Blink. If your repository does not appear in the dropdown list, you can type its name in the text box above the list.

3. From the dropdown list of branches, select the appropriate one.

   The title bar in Visual Studio Code changes to show that you are editing in Codespaces. If you open the Extensions tab in the left nav bar, you see both the extensions installed locally and those installed in the remote container.

Build and debug the project

Press F5, or select Run > Start Debugging, to build your project and begin debugging. Your application builds and sideloads to your device as usual. If you have set a breakpoint in your code, the app runs until the breakpoint is reached. You can use the usual debugging commands to walk through your code. See the Debugging topic in the Visual Studio Code documentation for more details.

When you are finished debugging, press Shift+F5 or the Stop icon. To close the codespace, select View > Command Palette > Codespaces: Stop Current Codespace.