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.

info

These are the common files and folders used by the templates and extension architecture. Each template may have additional files and folders. Check the specific template documentation for more information.

📂 .conf

📄 .docok

A lock file that represents that the user has already opened the documentation. It's used by the extension to not open the documentation every time the user opens the project.

📜 check-ci-env.xsh

This script is used to verify the sanity of the CI environment. Is useful to show to the user the env that should be set and fail fast if something is missing. It's used by the validate-pipeline-settings task.

📜 check-deps.xsh

This script is used to check if the dependencies, Debian packages or/and scripts, are installed in the system. The list of deb dependencies are defined in the .conf/deps.json file. It's used by the check-deps task.

📄 create-docker-compose-production.xsh

This script is used to publish the container image to a registry and generate the final production docker-compose file. It's used by the create-production-image task.

📄 deps.json

This file is used to list the local, the host, dependencies that are required for the workloads of the workspace. It's used by the check-deps task. Check the Check Host Machine Dependencies Required by the Project article section for more information.

📄 metadata.json

This file is used to store the data from the source of the template:

{
    "projectName": "pytest",
    "templateName": "python3Console",
    "containerName": "python-test",
    "torizonOSMajor": "7"
}

• projectName: The name user input when creating the project.
• templateName: The name of the template source folder used to create the project.
• containerName: The container name user input when creating the project.
• torizonOSMajor: The major version of the Torizon OS that the project is targeting. Here for example, this project should be used on Torizon OS 7 and it's base template is a Torizon OS 7 base template.

This data is used by the .conf/project-updater.xsh script to have the source and the inputs to update the project.

📜 project-updater.xsh

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

📜 run-container-if-not-exists.xsh

This script 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.

📜 share-wsl-ports.xsh

This script 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.

info

Although this script runs always when the extension is activated, it only executes the actual code 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.

📜 torizon-io.xsh

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

📜 torizon-packages.xsh

This script is used to add the packages described in the .conf/torizonPackages.json file to the Dockerfile, Dockerfile.debug and Dockerfile.sdk files. Check the Check Host Machine Dependencies Required by the Project article section for more information.

📄 update.json

This file is used to store the updated match table of the files specific to the workload of the template that need to be updated. It's read by the project-updater.xsh script.

📜 validate-deps-running.xsh

This script is used to verify the sanity of development environment. It's check if the dependencies process are running. It's used by the validate-deps-running task.

📂 .doc

📄 README.md

This file is used to store the specific template documentation. It's used by the show-project-documentation task.

📂 .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.xsh

This script 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.