Is this page helpful?

Workspace - Structure

Introduction

This article presents you the files and folders created by the extension. They are used to manage the project.

📂 .conf

📄 .container

This file is used to store the container (docker-compose service) name. It's useful when the project needs to be updated and the updater needs to auto-complete the container name. It's read by the projectUpdater.ps1 script.

📄 .template

This file is used to store the template name. It's useful when the project needs to be updated and the updater needs to know which template to use.

📄 .doc

This file is used to store the documentation specific of the template. This documentation contains some explanation of how the code is being built and deployed to the application, how it is being debugged and where did its source code come from. Also, there should be present relevant information specific from that template, warnings, recommendations and tasks specific from that template and how to use them.

📜 checkDeps.ps1

This file is used to check if the dependencies are installed on the machine, based on the deps.json file. It's used by the check-deps task.

📜 createDockerComposeProduction.ps1

This file is used to create the production Docker images and merge them on the docker-compose.production.yml file. It's used by the create-production-image task.

📄 deps.json

This file is used to store the Debian packages dependencies that are required to run the project locally. It's read by the checkDeps.ps1 script.

🗝️ id_rsa / id_rsa.pub

This files are used to store the SSH key pair used to access the development container in the target board.

caution

These are not secure keys!! They are only used to access the development container in the target board. Do not use these keys for any other purpose.

📜 projectUpdater.ps1

This file is used to update the project to the latest version of the template. It's used by the try-update-template task.

📜 runContainerIfNotExists.ps1

This file is used to run the dependency containers if they are not running. It's used by the run-torizon-binfmt and run-docker-registry tasks.

📜 shareWSLPorts.ps1

This file is used to open the firewall from the Windows side and be possible to access the WSL ports from the target device. It's used by the run-share-wsl-ports task.

Although this script runs always when the extension is activated, it only executes the actual content if in a WSL 2 environment.

📜 tcb-env-setup.sh

This file is used to setup the TorizonCore Builder. It's used by the tcb-platform-publish task.

info

This script is not the same as the one in the TorizonCore Builder documentation. It's a modified version that is used by the extension.

📜 torizonIO.ps1

This file is used to manage the Torizon Cloud API. It's used by the platform-update-fleet task.

📜 torizonPackages.ps1

This file is used to add the packages described in the torizonPackages.json file to the Dockerfile and Dockerfile.debug files.

📄 update.json

This file is used to store the updated match table of the files that need to change the name. It's read by the projectUpdater.ps1 script.

📂 .github/workflows

📄 build-application.yaml

This file is used to configure the GitHub Actions workflow to build and deploy the application to the Torizon IO platform. Check the Github Actions Integration documentation for more information.

📂 .vscode

📄 extensions.json

This file is used to store the extensions that are recommended by the project to work correctly. For example, the extension that runs the debugger, the code syntax highlight, etc. It's used by the VS Code to ask the user to install the recommended extensions.

📄 launch.json

This file is used to store the configurations to launch the application with the debugger. It's used by the VS Code to list and launch the application debuggers.

📄 settings.json

This file is used to store the settings of the project. It's used by the VS Code and the extension to set the project settings. Check the Workspace Settings documentation for more information.

📄 tasks.json

This file is used to store the tasks that are available to run on the project. It's used by the VS Code to list and run the project tasks. These tasks are also used by the launch.json in a dependency chain of tasks to build and deploy the application on the target before the launch of the debugger. Check the Workspace Tasks documentation for more information.

📜 tasks.ps1

This file is used to run the tasks described in the tasks.json file on the CLI and CI/CD environments.

📄 .dockerignore

This file is used to list files and folders to be ignored when building the Docker image.

📄 .gitignore

This file is used to list files and folders to ignore when committing the project to a Git repository.

This is a starting point for your project. The list of files and folders to ignore may change depending on your project. So, pay attention when adding files and folders to the repository and add them to .gitignore if necessary.

Make sure to maintain the credentials.zip and the *.lock.yml files on the .gitignore. credentials.zip should not be publicly shared for security reasons and the *.lock.yml files are generated by TorizonCore Builder.

📄 .gitlab-ci.yml

This file is used to configure the GitLab CI pipeline. Check the GitLab CI Integration documentation for more information.

📄 docker-compose.yml

This file is used to configure the Docker Compose services, build parameters, port forwarding, devices, capabilities for the production and debug containers. Check the Compose file reference documentation for more information.

📄 Dockerfile.sdk

Some projects use a container with the SDK toolchain to cross-compile your code for SoM architectures. The generated build files are stored in the project workspace and used by the debug container.

Since containers run in an isolated environment, the SDK container requires mounting (bind mount) the workspace directory into it. This container is defined by Dockerfile.sdk and executed on the host machine.

For example, the task below is part of the C++ CMake template and runs the cmake --build build-arm command inside the SDK container. That task compiles the code for the ARM64 architecture and stores build files in the build-arm64 workspace directory.

task.json

{
    "label": "build-debug-arm64",
    "detail": "Build a debug version of the application for arm64 using\nthe toolchain from the SDK container.",
    "command": "DOCKER_HOST=",
    "type": "shell",
    "args": [
        "docker",
        "run",
        "--rm",
        "-it",
        "-v",
        "${workspaceFolder}:${config:torizon_app_root}",
        "cross-toolchain-arm64-__container__",
        "cmake",
        "--build",
        "build-arm64"
    ],
    "problemMatcher": [
        "$gcc"
    ],
    "icon": {
        "id": "flame",
        "color": "terminal.ansiYellow"
    },
    "dependsOrder": "sequence",
    "dependsOn": [
        "build-configure-arm64"
    ]
},

The flag that performs the bind-mount is -v ${workspaceFolder}:${config:torizon_app_root}. Since the directory is shared between the workspace and the SDK container, build files generated inside the SDK container automatically appear in the workspace.

As a result of bind-mounting, the SDK can access previous builds in the workspace and does not need to build everything from scratch every time.

📄 Dockerfile.debug

The debug container is deployed and executed on the target device when debugging applications. This container is defined by Dockerfile.debug.

Since this container is built on the host machine and executed on the SoM, it is not possible to bind-mount the workspace directory. Instead, build files (generated by the SDK container) are copied to the debug container during build time through a COPY command in Dockerfile.debug, as follows:

COPY --chown=$SSHUSERNAME:$SSHUSERNAME ./build-${IMAGE_ARCH}/bin ${APP_ROOT}

The APP_ROOT variable, defined in .vscode/settings.json, sets the directory to which the build files are copied.

Since copying build files, such as CMakeFiles, is not needed, only the bin subdirectory is copied. The value for IMAGE-ARCH is automatically set according to the target's architecture. For ARM64, as in the example above, the value will be IMAGE-ARCH=arm64.

📄 Dockerfile

The release container is the one that should be deployed and executed during production on SoMs. This container is defined by Dockerfile.

When the code is compiled, Dockerfile uses a multi-stage build. That means there is a build and a runtime container:

• The build container runs in the host machine and compiles the code. It can be identified by the as Build alias.
• The runtime container, like the debug container, is executed on the SoM. It can be identified by the as Deploy alias.

The compiled code is copied from the build to the runtime container through a COPY command as follows:

COPY --from=Build ${APP_ROOT}/build-${IMAGE_ARCH}/bin ${APP_ROOT}

The multi-stage build guarantees the same environment every time the code is compiled and optimizes the container image.

📄 torizonPackages.json

This file is used to list the Debian packages that will be installed on the production and debug containers. Check the Add Packages Packages documentation section for more information.