.. _vscode: VS Code + DevContainer ====================== Here's a guide for using Visual Studio Code (VS Code) to develop with Yocto in a containerized environment. .. admonition:: Linux distribution :class: tip When using a containerized environment for building yocto, the host does not have to be a Yocto-supported distro. Requirements ------------ Before you start, make sure you have: - Linux system (**Ubuntu-based** distribution recommended, see :ref:`host-setup`) - Docker Engine installed and running (see `Docker Engine Installation Guide`_) - VS Code installed (see `VS Code Setup Guide`_) - VS Code Dev Containers extension The following instructions assume that you are working in a Linux environment. Get the repo tool ----------------- Download and activate the ``repo`` tool: .. prompt:: :prompts: $ mkdir ~/bin curl https://storage.googleapis.com/git-repo-downloads/repo > ~/bin/repo chmod a+x ~/bin/repo export PATH=~/bin:$PATH Get the BSP ----------- First get the BSP for your STM, Renesas module (Mainline BSP) or NXP module (NXP BSP). The ``repo`` tool is used to initialize the BSP folder locally. +----------+----------------------------------------------------------------------------------+ | BSP | Command | +==========+==================================================================================+ | | | | Mainline | .. code-block:: text | | | | | | repo init -u https://github.com/karo-electronics/karo-bsp.git -b | | | | +----------+----------------------------------------------------------------------------------+ | | | | NXP | .. code-block:: text | | | | | | repo init -u https://github.com/karo-electronics/karo-nxp-bsp.git -b | | | | +----------+----------------------------------------------------------------------------------+ Next synchronize the sources with: .. code-block:: bash repo sync After this step, the Yocto BSP sources are ready on your machine. Dev Container setup ------------------- 1. Open the BSP root folder with VS Code. - Starting from the ``scarthgap`` branch, VS Code should directly prompt you to reopen the current directory in a Container. If that is the case, skip to step 4. 2. Create the folder:: .devcontainer 3. Add these files inside ``.devcontainer``: - :download:`devcontainer.json `: In ``devcontainer.json`` replace the ```` placeholder with the codename of the Yocto version used. - :download:`Dockerfile `: In ``Dockerfile`` replace the ```` placeholder with a supported Ubuntu Version of the used Yocto version. .. admonition:: Shared Yocto files :class: tip This setups uses shared docker volumes for Yocto cache files. For each Yocto release (e.g. mickledore, scarthgap) a different volume needs to be used to avoid cache corruption between versions. 4. In VS Code reopen the folder in a Container. If not prompted, search for ``Dev Container: Reopen in Container`` command using ``strg + shift + P``. Inside the Dev Container ------------------------ The container is setup automatically to be able to build Yocto. Furthermore it configures VS Code and the Environment to develop with Yocto more easily. Key aspects include: - Supported Linux distribution for building with Yocto - Shared Yocto downloads and sstate-cache in docker volume. - Yocto Project BitBake VS Code Extension - Pre-configured VS Code for Yocto Development The build directory can be setup using the ``karo-setup-release.sh`` script, e.g.: .. code-block:: bash DISTRO= MACHINE= source karo-setup-release.sh This creates the folder ``build-karo`` and instantiates the configuration for the selected ``DISTRO`` and ``MACHINE``. Furthermore it activates the build environment, which makes the ``bitbake`` tool available. Now to build a Yocto image, you can use the following command: .. code-block:: bash bitbake karo-image-minimal This example requires the ``karo-minimal`` ``DISTRO``. For more info on how to use the ``karo-setup-release.sh``, see the quickguides at :ref:`getting_started` and/or further chapters in the :ref:`yocto-guide-index`. Yocto Project BitBake Extension ------------------------------- The Dev Container comes with the Yocto Project BitBake VS Code Extension preinstalled. It is configured to automatically detect the build folder by the name ``build-karo``. The extension provides a GUI to manage, build and develop recipes. A devtool workspace can be created to directly edit a recipe's source and also create patches automatically. For more information on how to use the Yocto Project Extension see `Yocto Project BitBake`_. - The Yocto Project extension is configured to use ``build-karo`` as the build directory. If needed change it in the extension settings. It is also possible to define multiple build-directories, see official documentation. - When creating a new devtool workspace via the Yocto Project extension, skip SDK toolkit configuration for now, as it may cause errors in this setup. - If a build fails while using a devtool workspace, try adding the following in the ``local.conf``: .. code-block:: PACKAGE_DEBUG_SPLIT_STYLE = "debug-without-src" .. _`Docker Engine Installation Guide`: https://docs.docker.com/engine/install/ .. _`VS Code Setup Guide`: https://code.visualstudio.com/docs/setup/setup-overview .. _`Yocto Project BitBake`: https://marketplace.visualstudio.com/items?itemName=yocto-project.yocto-bitbake