From mboxrd@z Thu Jan 1 00:00:00 1970 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 Authentication-Results: mx.groups.io; dkim=fail reason="body hash did not verify" header.i=@linux.microsoft.com header.s=default header.b=UUTykHUC; spf=pass (domain: linux.microsoft.com, ip: 13.77.154.182, mailfrom: mikuback@linux.microsoft.com) 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 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linux.microsoft.com; s=default; t=1670430268; bh=kyKuLwr6CosKwL/6MzvVZPL32puu5mF7Hwir3AGlvAw=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=UUTykHUCmgXgbi6d9HijGRIpHxBfgzsVKQUHJooLLKM2lgU/nsBzvabD85afaJD2Q v/E4SgBeq+E2fvArPNRdavQuC/enljfQF2n5yeyI88ECfOKra7x/xD5Sgnar9QdaI0 YCHqvtueqGXHvGoBVx03BVYRPG094cikpS3CNHis= From: "Michael Kubacki" To: devel@edk2.groups.io Cc: Sean Brogan , Michael D Kinney , Liming Gao , Michael Kubacki Subject: [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> X-Mailer: git-send-email 2.28.0.windows.1 In-Reply-To: <20221207162403.337-1-mikuback@linux.microsoft.com> References: <20221207162403.337-1-mikuback@linux.microsoft.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable 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-Cont= ainers.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 environm= ent requirements +it can be beneficial to use a container build environment for local deve= lopment. +TianoCore maintains container images for various Operating Systems and t= ool chains in the +[TianoCore Containers repository](https://github.com/tianocore/container= s). These +images contain the build tools and environment configurations to ensure = a consistent +and reproducible build between local development, CI, and pipeline platf= orm builds. + +If you are new to the concept of containers, more information can be fou= nd +[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= personal or +> Business subscription. Users should verify their use is licensed for t= heir organization +> if necessary. + +The existing TianoCore container images are created for use with Docker.= On Linux, +docker can be installed through the distributions package management app= lication. +For specific builds and for other operating systems, see the [Docker ins= tall page](https://docs.docker.com/engine/install/). + +### Windows Docker Setup + +It is strongly recommended to use the WSL 2 based engine when running Do= cker on +Windows. This can be configured in the General settings in Docker Deskto= p. Generally, +this provides better performance and overall design over the legacy. Det= ails on +this framework can be found in the [Docker documentation](https://docs.d= ocker.com/desktop/windows/wsl/). + +## Local Development + +To use the build container images to develop locally, there are several = configurations +depending the developers preferences. This section details some tools an= d tips that +make using containers for local development easier. This section is not = comprehensive +however and it is encouraged users experiment and consider contributing = back any +new useful configurations or tools to this documentation. + +> NOTE: +> If the code base is cloned in Windows, it is not advised to directly o= pen +> this repository in a Linux dev container as the file system share betw= een Windows +> and WSL 2 causes a very significant performance reduction. Instead, cl= one the +> repo in the WSL file system and map into the container or directly clo= ne into +> the container. + +### Manually configuring the container + +Some developers may wish to manually maintain their containers. This is = useful +for using editors that do not have native support for containers or the = specific +type of containers used. + +First, select the image most appropriate from the [TianoCore containers = list](https://github.com/tianocore/containers#current-status) +or a custom image for a specific platform or project. This image can be = pulled 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 i= n the workspace +from the host OS as this allows easy access to the code and build files = from 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 comm= and. + +```bash +docker start -i +``` + +When running in the container, the build instructions should be used as = they normally +would using the stuart commands. + +### Visual Studio Code + +The Visual Studio Code [Dev Container extension](https://code.visualstud= io.com/docs/devcontainers/containers) +provides an easy and consistent way to use containers for local developm= ent. At +the time of writing, this extension only supports Linux based containers= . This +extension provides a number of useful additions to the specified docker = image 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 creat= ing a +.devcontainer file in the repository. Some useful configurations are det= ails below. + +| Configuration | Purpose | +| :------------ | :------ | +| "privileged": true | This may be needed for access to KVM for QEMU= acceleration. | +| "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 "post= CreateCommand" +option. Specifically running `git config --global --add safe.directory $= {containerWorkspaceFolder}` +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 = below. + +```json +{ + "image": "ghcr.io/tianocore/containers/fedora-35-dev:latest", + "postCreateCommand": "git config --global --add safe.directory ${conta= inerWorkspaceFolder} && pip install --upgrade -r pip-requirements.txt", + "forwardPorts": [5000], + "privileged": true +} +``` + +## Pipeline Builds + +Both Azure pipelines and github workflows have native support for contai= ners. Information +on this can be found in the [Azure Pipeline Documentation](https://learn= .microsoft.com/en-us/azure/devops/pipelines/process/container-phases?view= =3Dazure-devops) +and the [Github Workflow Documentation](https://docs.github.com/en/actio= ns/using-workflows/workflow-syntax-for-github-actions). + +One important detail to note is that Azure pipelines will create a new u= ser in the +docker image during the pipeline. This user is used for all tasks and op= erations +and so certain local user install locations may not be by default on the= path. --=20 2.28.0.windows.1