From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mails.dpdk.org (mails.dpdk.org [217.70.189.124]) by inbox.dpdk.org (Postfix) with ESMTP id E4ADA42C36 for ; Mon, 5 Jun 2023 22:09:17 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id E01F64113F; Mon, 5 Jun 2023 22:09:17 +0200 (CEST) Received: from mail-yw1-f172.google.com (mail-yw1-f172.google.com [209.85.128.172]) by mails.dpdk.org (Postfix) with ESMTP id 48A604003C for ; Mon, 5 Jun 2023 22:09:16 +0200 (CEST) Received: by mail-yw1-f172.google.com with SMTP id 00721157ae682-566586b180fso57750357b3.0 for ; Mon, 05 Jun 2023 13:09:16 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=iol.unh.edu; s=unh-iol; t=1685995755; x=1688587755; h=cc:to:subject:message-id:date:from:in-reply-to:references :mime-version:from:to:cc:subject:date:message-id:reply-to; bh=za+5J4QXQitdswonUj1oc4om88tw353r/Zkqx/GNYX8=; b=OI00wee7Zv6AcsQH3uL3NzvgFwDs8051wbdmcea7fpRXHdJOS05+zzblgT4PcdQmof xZ1EkFWiK2Ww+h/LyPQgRrllovvuSQmFj0ueZbyK7/6QGVBacJSNgEBD48X84Sl97wYP UNeLvZKqIFN83id7YpypvE0cd57x+A9V6eocE= X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20221208; t=1685995755; x=1688587755; h=cc:to:subject:message-id:date:from:in-reply-to:references :mime-version:x-gm-message-state:from:to:cc:subject:date:message-id :reply-to; bh=za+5J4QXQitdswonUj1oc4om88tw353r/Zkqx/GNYX8=; b=JnUH8Z+5M9EUhRPj7cdAwa6LlwEa1MWfvghe43lV6rXuCIbCcyS88JnbqbIOlePyBl YpXU0HlGDW9jwxJwGyGsCBnTKuX5Sdg1WIb7aHn+XoMCLHYz0Yto9g3COR5HtITj4aXq YLD2GFZ1CdqO3YmIKGSdev4bsF0x71KYAPYYGyZTI3o4rgxjb7tp2Ur3Dh4kEBu23ba3 ZQ7EeKATbXNZzh6L/TJI6qNe0vvlHjV9kCvGM0RqOJhK1tzQbQcPvdKfDtMmQJvE+S/p sLRc47pd0odR59+2SgOphVwgcBjaEhRkiSrlDOVCTjdJqcHuEPHFrCXqHgBtcKLFqDCr Er7w== X-Gm-Message-State: AC+VfDwt2fafc/4AEP4XcA55eeiraw5hZUaVpAzDgNXZdpgsy58nsuC2 lkaS0tU7X0Kc7nkKcETye4oWChwqTK9IeZI11ItecbdDLQiBQzmN+FU= X-Google-Smtp-Source: ACHHUZ4thhokymGNdkgxQeHW20LBIOb5G86vJ4GX/zQ97Y9K+eJZFEmO2gRmm0Fq2x6B3KwvhiDfDwRqH7tnMxJnOQE= X-Received: by 2002:a81:7546:0:b0:561:8602:1a40 with SMTP id q67-20020a817546000000b0056186021a40mr9150510ywc.46.1685995755543; Mon, 05 Jun 2023 13:09:15 -0700 (PDT) MIME-Version: 1.0 References: <20230523170413.812922-1-ahassick@iol.unh.edu> <20230523170413.812922-12-ahassick@iol.unh.edu> In-Reply-To: From: Adam Hassick Date: Mon, 5 Jun 2023 16:09:04 -0400 Message-ID: Subject: Re: [PATCH v5 11/11] containers/docs: Update README To: Aaron Conole Cc: ci@dpdk.org, alialnu@nvidia.com Content-Type: multipart/alternative; boundary="0000000000001a334005fd677a2b" X-BeenThere: ci@dpdk.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: DPDK CI discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: ci-bounces@dpdk.org --0000000000001a334005fd677a2b Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable Those changes were not intentional. I mistakenly updated an internally kept copy of this README that was a draft, and added to that. I apologize for not proofreading the changes, lesson learned. I've used a linter to check for trailing whitespaces and spelling errors in the v6 patch. On Thu, May 25, 2023 at 9:45=E2=80=AFAM Aaron Conole w= rote: > Adam Hassick writes: > > > Updates the README with information on the added arguments > > and support for building OCI manifests. > > > > Signed-off-by: Adam Hassick > > --- > > I stopped reviewing. The changes here introduce spelling mistakes and > spaces at the end of lines. Please proofread it before making changes. > > > containers/README.md | 123 +++++++++++++++++++++++++++---------------- > > 1 file changed, 77 insertions(+), 46 deletions(-) > > > > diff --git a/containers/README.md b/containers/README.md > > index 5d01caf..59edfcc 100644 > > --- a/containers/README.md > > +++ b/containers/README.md > > @@ -14,73 +14,80 @@ nearly mandatory for this task. > > > > 1. Licensed RHEL containers need podman > > > > -The build system MUST be able to handle creating properly licensed RHE= L > > -containers, so that the RHEL CI testing is as accurate as possible. > > +The build system MUST be able to handle creating properly licensed RHE= L > > +containers, so that the RHEL CI testing is as accurate as possbile. > > Why these lines changed? Rather, I see that a space was added at the > end, and a spelling mistake was introduced s/possbile/possible/. That > can't be intentional - please undo this change. > > > 2. "Developer Laptop Friendliness" > > > > -Another goal of the build system was to enable anyone to easily build > the > > +Another goal of the build system was to enable anyone to easily build > the > > containers. Not all developers are able to use Linux as the main OS on > their > > main development machine. Podman runs on MacOS via podman-machine and > Windows > > -either by podman-machine or WSL. > > +either by podman-machine or WSL. > > Why were spaces added at the end in this section? Please don't do that. > > > 3. OCI Containers > > > > -OCI containers are more portable than some other container solutions. > Much of > > +OCI containers are more portable than some other container solutions. > Much of > > the progress on getting containers running on top of FreeBSD jails > targets OCI > > -containers specifically. The tracking issue for this is > > +containers specifically. The tracking issue for this is > > [ > https://reviews.freebsd.org/D21570](https://reviews.freebsd.org/D21570). > > -Once upstream support happens, there should be a relatively simple pat= h > to > > +Once upstream support happens, there should be a relatively simple pat= h > to > > supporting containers in FreeBSD once podman/docker APIs are better > supported. > > -At the moment, lack up upstream support means no support in this > project for > > -FreeBSD. > > +At the moment, lack up upstream support means no support in this > project for > > +FreeBSD. > > > > ### Python and Makefiles instead of Buildah as a library > > > > -The next question someone might have is why a combination of Python an= d > > +The next question someone might have is why a combination of Python an= d > > makefiles were used instead of using buildah as a library. The largest > > reason is that every DPDK developer is going to need to have some > > -level of familiarity with Python due to DTS. Buildah is only available > > -as a library via Go, and would tie DPDK to a particular container > > +level of familarity with Python due to DTS. Buildah is only avaliable > > familiarity was correct. available was correct. > > > +as a library via Go, and would tie DPDK to a particular container > > implementation. Go, while not difficult to learn, is a compiled > language, > > meaning that the build system would require a build system. > > > > -The other reason is that most of the logic that needs to be performed > is very > > -simple, and python has a few libraries that do most of the work. If it > weren't > > -for the desire to have an inventory file (inventory.yaml) with a schem= a > > -(inventory_schema.json), this probably could have been an AWK script. > After the > > -container images are produced, it is very easy to use the same templat= e > > -engine to produce a makefile that can be used to both build and push t= he > > -containers. This makefile can be run with multiple jobs for parallel > building > > -of containers, something not supported by all compose implementations. > > - > > -Meson was considered instead of Makefiles, however, Meson does not > handle new > > -Meson being generated during the build very well, and Meson wants most > commands > > -to have an output file, which is not true of many of the commands. > Meson is > > -also more difficult to generate using a templating library than Makefi= le > > -targets. > > +The other reason is that most of the logic that needs to be performed > is very > > +simple, and python has a few libraries that do most of the work. If it > weren't > > +for the desire to have an inventory file (inventory.yaml) with a schem= a > > +(inventory_schema.json), this probably could have been an AWK script. > After the > > +container images are produced, it is very easy to use the same > templating > > +engine to produce a makefile that can be used to both build and push > the > > +containers. This makefile can be run with multiple jobs for parallel > building > > +of containers, something not supported by all compose implementations. > > + > > +Meson was considered instead of Makefiles, however, Meson does not > handle new > > +Meson being generated during the build very well, and Meson wants most > commands > > +to have an output file, which is not true of many of the commands. > Meson is > > +also more difficult to generate using a templating library than > Makefile > > +targets. > > > > ## Building > > > > ### Environment Variables > > > > -All environment variables are namespaced to DPDK_CI_CONTAINERS to avoi= d > any > > -issues. > > +All environment variables are namespaced to DPDK_CI_CONTAINERS to avoi= d > any > > +issues. > > > > | Variable | Description > | Default | Valid Values | > > | -------------------------- | > ----------------------------------------------- | ------- | ------------ = | > > -DPDK_CI_CONTAINERS_ON_RHEL | Whether you are building on licensed RHEL= . > RHEL containers must be built on licensed RHEL, this can be used to > forcibly enable/disable RHEL containers if automatic detection fails. | > (grep -q 'Red Hat Enterprise Linux' /etc/redhat-release && echo 'Y') \|\| > echo 'N' | 'Y' or 'N' > > +| DPDK_CI_CONTAINERS_ON_RHEL | Whether you are building on licensed > RHEL. RHEL containers must be built on licensed RHEL, this can be used to > forcibly enable/disable RHEL containers if automatic detection fails. | > (grep -q 'Red Hat Enterprise Linux' /etc/redhat-release && echo 'Y') \|\| > echo 'N' | 'Y' or 'N' > > DPDK_CI_CONTAINERS_FAIL_ON_UNBUILDABLE | Fail during dockerfile > generation if any container in the inventory is not buildable. Currently > will cause a failure if you are not on RHEL and try to build RHEL > containers. | 'N' | 'Y' or 'N' > > +DPDK_CI_CONTAINERS_ONLY_HOST_ARCH | If set to 'Y', only images for the > local system architecture will be built. | 'N' | 'Y' or 'N' > > +DPDK_CI_CONTAINERS_IS_BUILDER | If set to 'Y', disables the manifest > features, and only builds images for the local system architecture. > Intended to be set when used inside another orchestration sofware. | 'N' = | > 'Y' or 'N' > > +DPDK_CI_CONTAINERS_NINJA_WORKERS | The number of Ninja workers to use > to build ABI images. Variable setting is benign if ABI is disabled. | uns= et > | Any positive integer greater than zero. > > DPDK_CI_CONTAINERS_BUILD_ABI | Whether to bake ABI images into the > containers. | 'N' | 'Y' or 'N' > > -DPDK_CI_CONTAINERS_BUILD_LIBABIGAIL | Whether to build libabigail from > source on distros that do not package it. DPDK_CI_CONTAINERS_BUILD_ABI=3D= Y > overrides this to 'Y' | 'N' | 'Y' or 'N' > > +DPDK_CI_CONTAINERS_NO_LATEST_TAG | Disables tagging the final manifest= s > as "latest" in the local store and remote registry. | 'N' | 'Y' or 'N' > > +DPDK_CI_CONTAINERS_COVERITY | Enable building Coverity images. Setting > this flag will make the Coverity binaries required. | 'N' | 'Y' or 'N' > > DPDK_CI_CONTAINER_BUILDER_PROGRAM | What container builder program to > use. | 'podman' | Any container builder that exposes the same interface a= nd > provides the same behavior as podman. > > -DPDK_CI_CONTAINERS_LIBABIGAIL_CLONE_URL | What URL to clone libabigail > from, since some distros need to compile it from source. | 'git:// > sourceware.org/git/libabigail.git' | A repository containing libabigail > which shares history with the main repository. > > +DPDK_CI_CONTAINERS_LIBABIGAIL_CLONE_URL | What URL to clone libabigail > from, since some distros need to compile it from source. | 'git:// > sourceware.org/git/libabigail.git' | A repository containing libabigail > which shares history with the main repository. > > DPDK_CI_CONTAINERS_DPDK_CLONE_URL | What URL to clone DPDK from. | ' > https://dpdk.org/git/dpdk' | Any DPDK mirror. > > +DPDK_CI_CONTAINERS_DPDK_STABLE_CLONE_URL | What URL to clone DPDK > stable form. | http://dpdk.org/git/dpdk-stable | Any DPDK stable mirror. > > DPDK_CI_CONTAINERS_CONTAINER_BUILDER_TAG | What tag to give to the > container which creates the dockerfiles. The default should be fine unles= s > you have issues with collisions. | 'dpdk_ci_container_builder' | Any vali= d > OCI container tag (A valid C function name will work) > > DPDK_CI_CONTAINERS_EXTRA_PUSH_ARGS | Extra arguments to add to the pus= h > command, can be used for credentials if 'podman login' won't work. | '' |= [ > https://docs.podman.io/en/latest/markdown/podman-push.1.html#options](htt= ps://docs.podman.io/en/latest/markdown/podman-push.1.html#options) > > DPDK_CI_CONTAINERS_REGISTRY_HOSTNAME | The hostname of the registry to > push to. | 'localhost' | The hostname of any system exposing an OCI > container registry or localhost to push to local storage. > > DPDK_CI_CONTAINERS_EXTRA_SCRIPTS_PATH | The path to a directory to cop= y > into all of the containers at /scripts | unset | The path to any local fi= le > directory. > > +DPDK_CI_CONTAINERS_COVERITY_PATH | The path to Coverity Scan binaries. > Only required of the Coverity flag is set. | unset | The path to any loca= l > file directory. > > DPDK_CI_CONTAINERS_CONTEXT_DIRECTORY | Set the directory to build the > containers in. All generated files will be placed in this directory or on= e > of it's children | '$(CURDIR)/container_context' | Any absolute directory > path > > +DPDK_CI_CONTAINERS_DATE_TAG_OVERRIDE | Uses a provided string instead > of generating a new date tag. Intended for development use. | unset | Any > string that is a valid OCI manifest tag. > > > > ### Builder System Requirements > > > > @@ -91,16 +98,15 @@ DPDK_CI_CONTAINERS_CONTEXT_DIRECTORY | Set the > directory to build the containers > > * find > > * posix utilities (GNU coreutils will work) > > * bash > > -* podman >=3D 4.0.0 (docker or other container builder programs may wo= rk, > but are > > -unsupported) > > - * podman 4.0.0 allows run mounts, which allow mounting a directory > into the build context of a container. This is used to persist ccache > directories for each container. > > -* qemu-$ARCH-static for any non-native architecture/revision you want > to build for. > > +* podman (docker is unsupported, and will NOT work for making manifest= s) > > +* qemu-$ARCH-static for any non-native architecture/revision you want > to build > > +for. > > > > #### Hardware > > > > -| Hardware Type | Requirement | Reason | > > -| ------------- | ---------------------------- | > ----------------------------------- | > > -| Disk space | 5 GB of disk space per image | Some images are 4 GB > at the moment, and as DPDK's API grows, so will the ABI references. > > +| Hardware Type | Requirement | Reason | > > +| ------------- | ----------------------------- | > ----------------------------------- | > > +| Disk space | 10 GB of disk space per image | Many of the final > images are 4 GB at the moment, and as DPDK's API grows, so will the ABI > references. Intermediate images generated by the builds will consume some > additional space that is recoverable after the build. > > Memory | Either 1.5x or 2x the memory needed to compile DPDK per > makefile job | 1.5x is enough for the container overhead and caching when > compiling natively, 2x is for builds under emulation (ARM container on x8= 6, > etc). > > > > > > @@ -111,28 +117,53 @@ RHEL container images must be built on RHEL. > > ### Build containers locally > > > > ```bash > > +# Build using the default arguments > > make build > > ``` > > > > +The resulting images will be tagged based on the date tag and platform= . > > +Image generated tags follow this format: `image-{{ platform }}-{{ > date_tag }}` > > +Where `platform` denotes the platform of the image, and `date_tag` is > the generated date tag or the override string provided > > +through the environment variable. > > + > > +They should appear in the local image store on your system. > > + > > ### Push containers to registry > > > > -This will probably involve following prompts in your terminal, but if > you have > > -other authentication set up, (LDAP, Kerberos, etc), it may not prompt > you. > > +This will probably involve following prompts in your terminal, but if > you have > > +other authentication set up, (LDAP, Kerberos, etc), it may not prompt > you. > > Logging into a registry is what allows you to upload containers to a > remote > > -system for others to pull down. > > +system for others to pull down. > > > > If you are working alone, you probably can ignore this and keep the > containers > > -locally. If you are in an enterprise setting, ask your DevOps or Syste= ms > > -Administration team where the preferred location for hosting container= s > is. > > +locally. If you are in an enterprise setting, ask your DevOps or > Systems > > +Administration team where the preferred location for hosting container= s > is. > > > > -Since these images take so long to build, it is recommended to use a > container > > +Since these images take so long to build, it is recommended to use a > container > > registry and have any CI systems pull from that registry. > > > > -Redhat guide to setting up a podman container registry: > > +Redhat guide to setting up a podman container registry: > > [ > https://www.redhat.com/sysadmin/simple-container-registry](https://www.re= dhat.com/sysadmin/simple-container-registry) > > > > ```bash > > $DPDK_CI_CONTAINER_BUILDER_PROGRAM login > $DPDK_CI_CONTAINERS_REGISTRY_HOSTNAME > > # < Complete login process > > > make push > > -``` > > \ No newline at end of file > > +``` > > + > > +#### Manifests > > + > > +OCI manifests allow the grouping of images for different platforms > under the same tag in a repository on a registry. > > +The use of OCI manifests over tagged images reduces the amount of > system platform related branching in CI scripting. > > + > > +The Makefile provides the option to push only the images, only the > manifests, or push the images and make manifests. > > +The default "push" target will perform the last case. > > +If you choose to create the manifests, then these will be created with > the "final" tags like "latest" and the date timestamp. > > + > > +Manifest creation is known to not be compatible with Docker. > > +This feature is known to work when using Podman to post content to a > Docker v2 registry. > > + > > +The manifests may be created on the registry independently of the imag= e > builds using the `push_manifests` target in place of the `push` target. > > +In contrast, the `push_images` target will only push the images and no= t > create the manifests. > > + > > +If the `DPDK_CI_CONTAINERS_IS_BUILDER` variable is set to 'Y', then th= e > `push_manifests` target will be disabled. > > \ No newline at end of file > > --=20 *Adam Hassick* Senior Developer UNH InterOperability Lab ahassick@iol.unh.edu iol.unh.edu +1 (603) 475-8248 --0000000000001a334005fd677a2b Content-Type: text/html; charset="UTF-8" Content-Transfer-Encoding: quoted-printable
Those changes were not intentional. I mistakenly upda= ted an=20 internally kept copy of this README that was a draft, and added to that.I apologize for not proofreading the changes, lesson learned. I've use= d a linter to check for=20 trailing whitespaces and spelling errors in the v6 patch.

On Thu, May 25, 20= 23 at 9:45=E2=80=AFAM Aaron Conole <aconole@redhat.com> wrote:
Adam Hassick <ahassick@iol.unh.edu> writes:

> Updates the README with information on the added arguments
> and support for building OCI manifests.
>
> Signed-off-by: Adam Hassick <ahassick@iol.unh.edu>
> ---

I stopped reviewing.=C2=A0 The changes here introduce spelling mistakes and=
spaces at the end of lines.=C2=A0 Please proofread it before making changes= .

>=C2=A0 containers/README.md | 123 +++++++++++++++++++++++++++----------= ------
>=C2=A0 1 file changed, 77 insertions(+), 46 deletions(-)
>
> diff --git a/containers/README.md b/containers/README.md
> index 5d01caf..59edfcc 100644
> --- a/containers/README.md
> +++ b/containers/README.md
> @@ -14,73 +14,80 @@ nearly mandatory for this task.
>=C2=A0
>=C2=A0 1. Licensed RHEL containers need podman
>=C2=A0
> -The build system MUST be able to handle creating properly licensed RH= EL
> -containers, so that the RHEL CI testing is as accurate as possible. > +The build system MUST be able to handle creating properly licensed RH= EL
> +containers, so that the RHEL CI testing is as accurate as possbile. <= br>
Why these lines changed?=C2=A0 Rather, I see that a space was added at the<= br> end, and a spelling mistake was introduced s/possbile/possible/.=C2=A0 That=
can't be intentional - please undo this change.

>=C2=A0 2. "Developer Laptop Friendliness"
>=C2=A0
> -Another goal of the build system was to enable anyone to easily build= the
> +Another goal of the build system was to enable anyone to easily build= the
>=C2=A0 containers. Not all developers are able to use Linux as the main= OS on their
>=C2=A0 main development machine. Podman runs on MacOS via podman-machin= e and Windows
> -either by podman-machine or WSL.
> +either by podman-machine or WSL.

Why were spaces added at the end in this section?=C2=A0 Please don't do= that.

>=C2=A0 3. OCI Containers
>=C2=A0
> -OCI containers are more portable than some other container solutions.= Much of
> +OCI containers are more portable than some other container solutions.= Much of
>=C2=A0 the progress on getting containers running on top of FreeBSD jai= ls targets OCI
> -containers specifically. The tracking issue for this is
> +containers specifically. The tracking issue for this is
>=C2=A0 [https://reviews= .freebsd.org/D21570](https://reviews.freebsd.org/D21570).
> -Once upstream support happens, there should be a relatively simple pa= th to
> +Once upstream support happens, there should be a relatively simple pa= th to
>=C2=A0 supporting containers in FreeBSD once podman/docker APIs are bet= ter supported.
> -At the moment, lack up upstream support means no support in this proj= ect for
> -FreeBSD.
> +At the moment, lack up upstream support means no support in this proj= ect for
> +FreeBSD.=C2=A0
>=C2=A0
>=C2=A0 ### Python and Makefiles instead of Buildah as a library
>=C2=A0
> -The next question someone might have is why a combination of Python a= nd
> +The next question someone might have is why a combination of Python a= nd
>=C2=A0 makefiles were used instead of using buildah as a library. The l= argest
>=C2=A0 reason is that every DPDK developer is going to need to have som= e
> -level of familiarity with Python due to DTS. Buildah is only availabl= e
> -as a library via Go, and would tie DPDK to a particular container
> +level of familarity with Python due to DTS. Buildah is only avaliable=

familiarity was correct.=C2=A0 available was correct.

> +as a library via Go, and would tie DPDK to a particular container >=C2=A0 implementation. Go, while not difficult to learn, is a compiled = language,
>=C2=A0 meaning that the build system would require a build system.
>=C2=A0
> -The other reason is that most of the logic that needs to be performed= is very
> -simple, and python has a few libraries that do most of the work. If i= t weren't
> -for the desire to have an inventory file (inventory.yaml) with a sche= ma
> -(inventory_schema.json), this probably could have been an AWK script.= After the
> -container images are produced, it is very easy to use the same templa= te
> -engine to produce a makefile that can be used to both build and push = the
> -containers. This makefile can be run with multiple jobs for parallel = building
> -of containers, something not supported by all compose implementations= .
> -
> -Meson was considered instead of Makefiles, however, Meson does not ha= ndle new
> -Meson being generated during the build very well, and Meson wants mos= t commands
> -to have an output file, which is not true of many of the commands. Me= son is
> -also more difficult to generate using a templating library than Makef= ile
> -targets.
> +The other reason is that most of the logic that needs to be performed= is very
> +simple, and python has a few libraries that do most of the work. If i= t weren't
> +for the desire to have an inventory file (inventory.yaml) with a sche= ma
> +(inventory_schema.json), this probably could have been an AWK script.= After the
> +container images are produced, it is very easy to use the same templa= ting
> +engine to produce a makefile that can be used to both build and push = the
> +containers. This makefile can be run with multiple jobs for parallel = building
> +of containers, something not supported by all compose implementations= .
> +
> +Meson was considered instead of Makefiles, however, Meson does not ha= ndle new
> +Meson being generated during the build very well, and Meson wants mos= t commands
> +to have an output file, which is not true of many of the commands. Me= son is
> +also more difficult to generate using a templating library than Makef= ile
> +targets.
>=C2=A0
>=C2=A0 ## Building
>=C2=A0
>=C2=A0 ### Environment Variables
>=C2=A0
> -All environment variables are namespaced to DPDK_CI_CONTAINERS to avo= id any
> -issues.
> +All environment variables are namespaced to DPDK_CI_CONTAINERS to avo= id any
> +issues.
>=C2=A0
>=C2=A0 | Variable=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2= =A0 =C2=A0 =C2=A0| Description=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2= =A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 = =C2=A0 =C2=A0| Default | Valid Values |
>=C2=A0 | -------------------------- | ---------------------------------= -------------- | ------- | ------------ |
> -DPDK_CI_CONTAINERS_ON_RHEL | Whether you are building on licensed RHE= L. RHEL containers must be built on licensed RHEL, this can be used to forc= ibly enable/disable RHEL containers if automatic detection fails. | (grep -= q 'Red Hat Enterprise Linux' /etc/redhat-release && echo &#= 39;Y') \|\| echo 'N' | 'Y' or 'N'
> +| DPDK_CI_CONTAINERS_ON_RHEL | Whether you are building on licensed R= HEL. RHEL containers must be built on licensed RHEL, this can be used to fo= rcibly enable/disable RHEL containers if automatic detection fails. | (grep= -q 'Red Hat Enterprise Linux' /etc/redhat-release && echo = 'Y') \|\| echo 'N' | 'Y' or 'N'
>=C2=A0 DPDK_CI_CONTAINERS_FAIL_ON_UNBUILDABLE | Fail during dockerfile = generation if any container in the inventory is not buildable. Currently wi= ll cause a failure if you are not on RHEL and try to build RHEL containers.= | 'N' | 'Y' or 'N'
> +DPDK_CI_CONTAINERS_ONLY_HOST_ARCH | If set to 'Y', only image= s for the local system architecture will be built. | 'N' | 'Y&#= 39; or 'N'
> +DPDK_CI_CONTAINERS_IS_BUILDER | If set to 'Y', disables the m= anifest features, and only builds images for the local system architecture.= Intended to be set when used inside another orchestration sofware. | '= N' | 'Y' or 'N'
> +DPDK_CI_CONTAINERS_NINJA_WORKERS | The number of Ninja workers to use= to build ABI images. Variable setting is benign if ABI is disabled. | unse= t | Any positive integer greater than zero.
>=C2=A0 DPDK_CI_CONTAINERS_BUILD_ABI | Whether to bake ABI images into t= he containers. | 'N' | 'Y' or 'N'
> -DPDK_CI_CONTAINERS_BUILD_LIBABIGAIL | Whether to build libabigail fro= m source on distros that do not package it. DPDK_CI_CONTAINERS_BUILD_ABI=3D= Y overrides this to 'Y' | 'N' | 'Y' or 'N'<= br> > +DPDK_CI_CONTAINERS_NO_LATEST_TAG | Disables tagging the final manifes= ts as "latest" in the local store and remote registry. | 'N&#= 39; | 'Y' or 'N'
> +DPDK_CI_CONTAINERS_COVERITY | Enable building Coverity images. Settin= g this flag will make the Coverity binaries required. | 'N' | '= Y' or 'N'
>=C2=A0 DPDK_CI_CONTAINER_BUILDER_PROGRAM | What container builder progr= am to use. | 'podman' | Any container builder that exposes the same= interface and provides the same behavior as podman.
> -DPDK_CI_CONTAINERS_LIBABIGAIL_CLONE_URL | What URL to clone libabigai= l from, since some distros need to compile it from source. | 'git://sourceware.org/git/libabigail.git' | A repository conta= ining libabigail which shares history with the main repository.
> +DPDK_CI_CONTAINERS_LIBABIGAIL_CLONE_URL | What URL to clone libabigai= l from, since some distros need to compile it from source. | 'git://sourceware.org/git/libabigail.git' | A repository conta= ining libabigail which shares history with the main repository.
>=C2=A0 DPDK_CI_CONTAINERS_DPDK_CLONE_URL | What URL to clone DPDK from.= | 'https://dpdk.org/git/dpdk' | Any DPDK mirror.
> +DPDK_CI_CONTAINERS_DPDK_STABLE_CLONE_URL | What URL to clone DPDK sta= ble form. | http://dpdk.org/git/dpdk-stable | Any DPDK stable mir= ror.
>=C2=A0 DPDK_CI_CONTAINERS_CONTAINER_BUILDER_TAG | What tag to give to t= he container which creates the dockerfiles. The default should be fine unle= ss you have issues with collisions. | 'dpdk_ci_container_builder' |= Any valid OCI container tag (A valid C function name will work)
>=C2=A0 DPDK_CI_CONTAINERS_EXTRA_PUSH_ARGS | Extra arguments to add to t= he push command, can be used for credentials if 'podman login' won&= #39;t work. | '' | [https:= //docs.podman.io/en/latest/markdown/podman-push.1.html#options](https://doc= s.podman.io/en/latest/markdown/podman-push.1.html#options)
>=C2=A0 DPDK_CI_CONTAINERS_REGISTRY_HOSTNAME | The hostname of the regis= try to push to. | 'localhost' | The hostname of any system exposing= an OCI container registry or localhost to push to local storage.
>=C2=A0 DPDK_CI_CONTAINERS_EXTRA_SCRIPTS_PATH | The path to a directory = to copy into all of the containers at /scripts | unset | The path to any lo= cal file directory.
> +DPDK_CI_CONTAINERS_COVERITY_PATH | The path to Coverity Scan binaries= . Only required of the Coverity flag is set. | unset | The path to any loca= l file directory.
>=C2=A0 DPDK_CI_CONTAINERS_CONTEXT_DIRECTORY | Set the directory to buil= d the containers in. All generated files will be placed in this directory o= r one of it's children | '$(CURDIR)/container_context' | Any ab= solute directory path
> +DPDK_CI_CONTAINERS_DATE_TAG_OVERRIDE | Uses a provided string instead= of generating a new date tag. Intended for development use. | unset | Any = string that is a valid OCI manifest tag.
>=C2=A0
>=C2=A0 ### Builder System Requirements
>=C2=A0
> @@ -91,16 +98,15 @@ DPDK_CI_CONTAINERS_CONTEXT_DIRECTORY | Set the dir= ectory to build the containers
>=C2=A0 * find
>=C2=A0 * posix utilities (GNU coreutils will work)
>=C2=A0 * bash
> -* podman >=3D 4.0.0 (docker or other container builder programs ma= y work, but are
> -unsupported)
> -=C2=A0 =C2=A0 * podman 4.0.0 allows run mounts, which allow mounting = a directory into the build context of a container. This is used to=C2=A0 pe= rsist ccache directories for each container.
> -* qemu-$ARCH-static for any non-native architecture/revision you want= to build for.
> +* podman (docker is unsupported, and will NOT work for making manifes= ts)
> +* qemu-$ARCH-static for any non-native architecture/revision you want= to build
> +for.
>=C2=A0
>=C2=A0 #### Hardware
>=C2=A0
> -| Hardware Type | Requirement=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2= =A0 =C2=A0 =C2=A0 =C2=A0 | Reason |
> -| ------------- | ---------------------------- | --------------------= --------------- |
> -| Disk space=C2=A0 =C2=A0 | 5 GB of disk space per image | Some image= s are 4 GB at the moment, and as DPDK's API grows, so will the ABI refe= rences.
> +| Hardware Type | Requirement=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2= =A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0| Reason |
> +| ------------- | ----------------------------- | -------------------= ---------------- |
> +| Disk space=C2=A0 =C2=A0 | 10 GB of disk space per image | Many of t= he final images are 4 GB at the moment, and as DPDK's API grows, so wil= l the ABI references. Intermediate images generated by the builds will cons= ume some additional space that is recoverable after the build.
>=C2=A0 Memory | Either 1.5x or 2x the memory needed to compile DPDK per= makefile job | 1.5x is enough for the container overhead and caching when = compiling natively, 2x is for builds under emulation (ARM container on x86,= etc).
>=C2=A0
>=C2=A0
> @@ -111,28 +117,53 @@ RHEL container images must be built on RHEL.
>=C2=A0 ### Build containers locally
>=C2=A0
>=C2=A0 ```bash
> +# Build using the default arguments
>=C2=A0 make build
>=C2=A0 ```
>=C2=A0
> +The resulting images will be tagged based on the date tag and platfor= m.
> +Image generated tags follow this format: `image-{{ platform }}-{{ dat= e_tag }}`
> +Where `platform` denotes the platform of the image, and `date_tag` is= the generated date tag or the override string provided
> +through the environment variable.
> +
> +They should appear in the local image store on your system.
> +
>=C2=A0 ### Push containers to registry
>=C2=A0
> -This will probably involve following prompts in your terminal, but if= you have
> -other authentication set up, (LDAP, Kerberos, etc), it may not prompt= you.
> +This will probably involve following prompts in your terminal, but if= you have
> +other authentication set up, (LDAP, Kerberos, etc), it may not prompt= you.
>=C2=A0 Logging into a registry is what allows you to upload containers = to a remote
> -system for others to pull down.
> +system for others to pull down.
>=C2=A0
>=C2=A0 If you are working alone, you probably can ignore this and keep = the containers
> -locally. If you are in an enterprise setting, ask your DevOps or Syst= ems
> -Administration team where the preferred location for hosting containe= rs is.
> +locally. If you are in an enterprise setting, ask your DevOps or Syst= ems
> +Administration team where the preferred location for hosting containe= rs is.
>=C2=A0
> -Since these images take so long to build, it is recommended to use a = container
> +Since these images take so long to build, it is recommended to use a = container
>=C2=A0 registry and have any CI systems pull from that registry.
>=C2=A0
> -Redhat guide to setting up a podman container registry:
> +Redhat guide to setting up a podman container registry:
>=C2=A0 [https://www.redhat.com/sysadmin/simple-conta= iner-registry](https://www.redhat.com/sysadmin/simple-container-registry)
>=C2=A0
>=C2=A0 ```bash
>=C2=A0 $DPDK_CI_CONTAINER_BUILDER_PROGRAM login $DPDK_CI_CONTAINERS_REG= ISTRY_HOSTNAME
>=C2=A0 # < Complete login process >
>=C2=A0 make push
> -```
> \ No newline at end of file
> +```
> +
> +#### Manifests
> +
> +OCI manifests allow the grouping of images for different platforms un= der the same tag in a repository on a registry.
> +The use of OCI manifests over tagged images reduces the amount of sys= tem platform related branching in CI scripting.
> +
> +The Makefile provides the option to push only the images, only the ma= nifests, or push the images and make manifests.
> +The default "push" target will perform the last case.
> +If you choose to create the manifests, then these will be created wit= h the "final" tags like "latest" and the date timestamp= .
> +
> +Manifest creation is known to not be compatible with Docker.
> +This feature is known to work when using Podman to post content to a = Docker v2 registry.
> +
> +The manifests may be created on the registry independently of the ima= ge builds using the `push_manifests` target in place of the `push` target.<= br> > +In contrast, the `push_images` target will only push the images and n= ot create the manifests.
> +
> +If the `DPDK_CI_CONTAINERS_IS_BUILDER` variable is set to 'Y'= , then the `push_manifests` target will be disabled.
> \ No newline at end of file



--
--0000000000001a334005fd677a2b--