From nobody Fri Dec 19 19:16:10 2025 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of groups.io designates 66.175.222.108 as permitted sender) client-ip=66.175.222.108; envelope-from=bounce+27952+97095+1787277+3901457@groups.io; helo=mail02.groups.io; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of groups.io designates 66.175.222.108 as permitted sender) smtp.mailfrom=bounce+27952+97095+1787277+3901457@groups.io; dmarc=fail(p=none dis=none) header.from=linux.microsoft.com ARC-Seal: i=1; a=rsa-sha256; t=1670430269; cv=none; d=zohomail.com; s=zohoarc; b=Gw/1YEXgFVzYOuMcobIIouDifkp/i7Rqgu0wr3wviXYPg+XdoZbW0a14C425H02LQa5gwfgK1XqWnGYm5KXhsGVf821miunaq6KSIQWs6kf3lZe02/XB4fssv12mVTW4qmMvOjZr3DlkAP6sn3REjKBwfY/5Zu9sDPvItxXhqOU= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1670430269; h=Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Id:List-Help:List-Unsubscribe:MIME-Version:Message-ID:Reply-To:References:Sender:Subject:To; bh=RQf/ODO5JHNHh/qBnI+4/UdRPCGfm7eQcXWTjjVb4AE=; b=mMzT15zsnIxXNqARXtGgEM1Ted5xxo3kLKEnlDqq0TJWVsvb36uMsXF00FSEIXu3kW7TtsSj+xs9il1+XHJl25Hm+Q8QlYUrm4nqZjXq4wFAcdD3sTQGTkCLjzI8hpd+me5Tn9+kVHxvm5mZPT7len18J6FAoMgpwbahCyXAzG8= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of groups.io designates 66.175.222.108 as permitted sender) smtp.mailfrom=bounce+27952+97095+1787277+3901457@groups.io; dmarc=fail header.from= (p=none dis=none) Received: from mail02.groups.io (mail02.groups.io [66.175.222.108]) by mx.zohomail.com with SMTPS id 1670430269672517.9283799263272; Wed, 7 Dec 2022 08:24:29 -0800 (PST) Return-Path: X-Received: by 127.0.0.2 with SMTP id GQ4ZYY1788612x22tPP8PKSw; Wed, 07 Dec 2022 08:24:29 -0800 X-Received: from linux.microsoft.com (linux.microsoft.com [13.77.154.182]) by mx.groups.io with SMTP id smtpd.web10.20068.1670430268736573081 for ; Wed, 07 Dec 2022 08:24:28 -0800 X-Received: from localhost.localdomain (unknown [47.201.8.94]) by linux.microsoft.com (Postfix) with ESMTPSA id 997DC20B83E2; Wed, 7 Dec 2022 08:24:27 -0800 (PST) DKIM-Filter: OpenDKIM Filter v2.11.0 linux.microsoft.com 997DC20B83E2 From: "Michael Kubacki" To: devel@edk2.groups.io Cc: Sean Brogan , Michael D Kinney , Liming Gao , Michael Kubacki Subject: [edk2-devel] [edk2-wiki][PATCH v3 2/4] Add initial container usage instructions Date: Wed, 7 Dec 2022 11:24:01 -0500 Message-Id: <20221207162403.337-3-mikuback@linux.microsoft.com> In-Reply-To: <20221207162403.337-1-mikuback@linux.microsoft.com> References: <20221207162403.337-1-mikuback@linux.microsoft.com> MIME-Version: 1.0 Precedence: Bulk List-Unsubscribe: List-Subscribe: List-Help: Sender: devel@edk2.groups.io List-Id: Mailing-List: list devel@edk2.groups.io; contact devel+owner@edk2.groups.io Reply-To: devel@edk2.groups.io,mikuback@linux.microsoft.com X-Gm-Message-State: wVBi9fAc4h19n831kh0DduPKx1787277AA= Content-Transfer-Encoding: quoted-printable DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=groups.io; q=dns/txt; s=20140610; t=1670430269; bh=zFLR4OMX9HIA41Lncij1Twk7o9np9UMA1xfzA8aAVtM=; h=Cc:Date:From:Reply-To:Subject:To; b=UhEJlx120L32hQnCJlKZFvoMCJ0YYlA7n9i0WXAipXg+w2RTyyPrDZTLM4yATnVCTLW Pg87toOLAxzaRpdWWj+ABIYSdj1r8FjADnLw4MBglE/0+mIZWPvtna1hQ72Zt9YIM/xpk h6wPSZwDF2gE+0AMlcenQ2rcdmop3sDrjXk= X-ZohoMail-DKIM: pass (identity @groups.io) X-ZM-MESSAGEID: 1670430270055100009 Content-Type: text/plain; charset="utf-8" From: Chris Fernald Covers: - Container background - Docker background and installation - Local development with containers - How to manually configure a container - Integration with VS Code - Containers in pipelines Cc: Sean Brogan Cc: Michael D Kinney Cc: Liming Gao Cc: Michael Kubacki Signed-off-by: Chris Fernald --- How-to-Develop-With-Containers.md | 120 ++++++++++++++++++++ 1 file changed, 120 insertions(+) diff --git a/How-to-Develop-With-Containers.md b/How-to-Develop-With-Contai= ners.md new file mode 100644 index 000000000000..aa9ff802f158 --- /dev/null +++ b/How-to-Develop-With-Containers.md @@ -0,0 +1,120 @@ +# How to Develop With Containers + +Because various EDKII project can have specific build tools and environmen= t requirements +it can be beneficial to use a container build environment for local develo= pment. +TianoCore maintains container images for various Operating Systems and too= l chains in the +[TianoCore Containers repository](https://github.com/tianocore/containers)= . These +images contain the build tools and environment configurations to ensure a = consistent +and reproducible build between local development, CI, and pipeline platfor= m builds. + +If you are new to the concept of containers, more information can be found +[on the Docker website](https://www.docker.com/resources/what-container/). + +## Setting up Docker + +> NOTE: +> Some Docker software is not free and some uses of Docker may require a p= ersonal or +> Business subscription. Users should verify their use is licensed for the= ir organization +> if necessary. + +The existing TianoCore container images are created for use with Docker. O= n Linux, +docker can be installed through the distributions package management appli= cation. +For specific builds and for other operating systems, see the [Docker insta= ll page](https://docs.docker.com/engine/install/). + +### Windows Docker Setup + +It is strongly recommended to use the WSL 2 based engine when running Dock= er on +Windows. This can be configured in the General settings in Docker Desktop.= Generally, +this provides better performance and overall design over the legacy. Detai= ls on +this framework can be found in the [Docker documentation](https://docs.doc= ker.com/desktop/windows/wsl/). + +## Local Development + +To use the build container images to develop locally, there are several co= nfigurations +depending the developers preferences. This section details some tools and = tips that +make using containers for local development easier. This section is not co= mprehensive +however and it is encouraged users experiment and consider contributing ba= ck any +new useful configurations or tools to this documentation. + +> NOTE: +> If the code base is cloned in Windows, it is not advised to directly open +> this repository in a Linux dev container as the file system share betwee= n Windows +> and WSL 2 causes a very significant performance reduction. Instead, clon= e the +> repo in the WSL file system and map into the container or directly clone= into +> the container. + +### Manually configuring the container + +Some developers may wish to manually maintain their containers. This is us= eful +for using editors that do not have native support for containers or the sp= ecific +type of containers used. + +First, select the image most appropriate from the [TianoCore containers li= st](https://github.com/tianocore/containers#current-status) +or a custom image for a specific platform or project. This image can be pu= lled down +from the docker command line. + +```bash +docker pull ghcr.io/tianocore/containers/: +``` + +After pulling the image, the image can be started. It is useful to map in = the workspace +from the host OS as this allows easy access to the code and build files fr= om the +host as well as the container. + +```bash +docker run -i -v : --workdir=3D= --name=3D ghcr.io/tianocore/containers/:= +``` + +After the container is existed, it can be resume by using the start comman= d. + +```bash +docker start -i +``` + +When running in the container, the build instructions should be used as th= ey normally +would using the stuart commands. + +### Visual Studio Code + +The Visual Studio Code [Dev Container extension](https://code.visualstudio= .com/docs/devcontainers/containers) +provides an easy and consistent way to use containers for local developmen= t. At +the time of writing, this extension only supports Linux based containers. = This +extension provides a number of useful additions to the specified docker im= age on +creation. + +- Configures git credential manager to pipe in git credentials. +- Makes extensions available on code inside the container. +- Abstracts management of the container for seamless use in the editor. + +For a shared docker image configuration, this can be configured by creatin= g a +.devcontainer file in the repository. Some useful configurations are detai= ls below. + +| Configuration | Purpose | +| :------------ | :------ | +| "privileged": true | This may be needed for access to KVM for QEMU a= cceleration. | +| "forwardPorts": [####] | Can be used to forward debug or serial ports to= the host OS. | + +It may also be desireable to run initialization commands using the "postCr= eateCommand" +option. Specifically running `git config --global --add safe.directory ${c= ontainerWorkspaceFolder}` +may be required if mapping the repository into the container is expected. + +And example of a devcontainer used for a QEMU platform repo is included be= low. + +```json +{ + "image": "ghcr.io/tianocore/containers/fedora-35-dev:latest", + "postCreateCommand": "git config --global --add safe.directory ${contain= erWorkspaceFolder} && pip install --upgrade -r pip-requirements.txt", + "forwardPorts": [5000], + "privileged": true +} +``` + +## Pipeline Builds + +Both Azure pipelines and github workflows have native support for containe= rs. Information +on this can be found in the [Azure Pipeline Documentation](https://learn.m= icrosoft.com/en-us/azure/devops/pipelines/process/container-phases?view=3Da= zure-devops) +and the [Github Workflow Documentation](https://docs.github.com/en/actions= /using-workflows/workflow-syntax-for-github-actions). + +One important detail to note is that Azure pipelines will create a new use= r in the +docker image during the pipeline. This user is used for all tasks and oper= ations +and so certain local user install locations may not be by default on the p= ath. --=20 2.28.0.windows.1 -=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D- Groups.io Links: You receive all messages sent to this group. View/Reply Online (#97095): https://edk2.groups.io/g/devel/message/97095 Mute This Topic: https://groups.io/mt/95518591/1787277 Group Owner: devel+owner@edk2.groups.io Unsubscribe: https://edk2.groups.io/g/devel/unsub [importer@patchew.org] -=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-