<div dir="ltr"><div>Those changes were not intentional. I mistakenly updated an 
internally kept copy of this README that was a draft, and added to that.<br>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.</div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Thu, May 25, 2023 at 9:45 AM Aaron Conole <<a href="mailto:aconole@redhat.com">aconole@redhat.com</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">Adam Hassick <<a href="mailto:ahassick@iol.unh.edu" target="_blank">ahassick@iol.unh.edu</a>> writes:<br>
<br>
> Updates the README with information on the added arguments<br>
> and support for building OCI manifests.<br>
><br>
> Signed-off-by: Adam Hassick <<a href="mailto:ahassick@iol.unh.edu" target="_blank">ahassick@iol.unh.edu</a>><br>
> ---<br>
<br>
I stopped reviewing.  The changes here introduce spelling mistakes and<br>
spaces at the end of lines.  Please proofread it before making changes.<br>
<br>
>  containers/README.md | 123 +++++++++++++++++++++++++++----------------<br>
>  1 file changed, 77 insertions(+), 46 deletions(-)<br>
><br>
> diff --git a/containers/README.md b/containers/README.md<br>
> index 5d01caf..59edfcc 100644<br>
> --- a/containers/README.md<br>
> +++ b/containers/README.md<br>
> @@ -14,73 +14,80 @@ nearly mandatory for this task.<br>
>  <br>
>  1. Licensed RHEL containers need podman<br>
>  <br>
> -The build system MUST be able to handle creating properly licensed RHEL<br>
> -containers, so that the RHEL CI testing is as accurate as possible.<br>
> +The build system MUST be able to handle creating properly licensed RHEL <br>
> +containers, so that the RHEL CI testing is as accurate as possbile. <br>
<br>
Why these lines changed?  Rather, I see that a space was added at the<br>
end, and a spelling mistake was introduced s/possbile/possible/.  That<br>
can't be intentional - please undo this change.<br>
<br>
>  2. "Developer Laptop Friendliness"<br>
>  <br>
> -Another goal of the build system was to enable anyone to easily build the<br>
> +Another goal of the build system was to enable anyone to easily build the <br>
>  containers. Not all developers are able to use Linux as the main OS on their<br>
>  main development machine. Podman runs on MacOS via podman-machine and Windows<br>
> -either by podman-machine or WSL.<br>
> +either by podman-machine or WSL. <br>
<br>
Why were spaces added at the end in this section?  Please don't do that.<br>
<br>
>  3. OCI Containers<br>
>  <br>
> -OCI containers are more portable than some other container solutions. Much of<br>
> +OCI containers are more portable than some other container solutions. Much of <br>
>  the progress on getting containers running on top of FreeBSD jails targets OCI<br>
> -containers specifically. The tracking issue for this is<br>
> +containers specifically. The tracking issue for this is <br>
>  [<a href="https://reviews.freebsd.org/D21570%5D(https://reviews.freebsd.org/D21570)" rel="noreferrer" target="_blank">https://reviews.freebsd.org/D21570](https://reviews.freebsd.org/D21570)</a>.<br>
> -Once upstream support happens, there should be a relatively simple path to<br>
> +Once upstream support happens, there should be a relatively simple path to <br>
>  supporting containers in FreeBSD once podman/docker APIs are better supported.<br>
> -At the moment, lack up upstream support means no support in this project for<br>
> -FreeBSD.<br>
> +At the moment, lack up upstream support means no support in this project for <br>
> +FreeBSD.  <br>
>  <br>
>  ### Python and Makefiles instead of Buildah as a library<br>
>  <br>
> -The next question someone might have is why a combination of Python and<br>
> +The next question someone might have is why a combination of Python and <br>
>  makefiles were used instead of using buildah as a library. The largest<br>
>  reason is that every DPDK developer is going to need to have some<br>
> -level of familiarity with Python due to DTS. Buildah is only available<br>
> -as a library via Go, and would tie DPDK to a particular container<br>
> +level of familarity with Python due to DTS. Buildah is only avaliable<br>
<br>
familiarity was correct.  available was correct.<br>
<br>
> +as a library via Go, and would tie DPDK to a particular container <br>
>  implementation. Go, while not difficult to learn, is a compiled language,<br>
>  meaning that the build system would require a build system.<br>
>  <br>
> -The other reason is that most of the logic that needs to be performed is very<br>
> -simple, and python has a few libraries that do most of the work. If it weren't<br>
> -for the desire to have an inventory file (inventory.yaml) with a schema<br>
> -(inventory_schema.json), this probably could have been an AWK script. After the<br>
> -container images are produced, it is very easy to use the same template<br>
> -engine to produce a makefile that can be used to both build and push the<br>
> -containers. This makefile can be run with multiple jobs for parallel building<br>
> -of containers, something not supported by all compose implementations.<br>
> -<br>
> -Meson was considered instead of Makefiles, however, Meson does not handle new<br>
> -Meson being generated during the build very well, and Meson wants most commands<br>
> -to have an output file, which is not true of many of the commands. Meson is<br>
> -also more difficult to generate using a templating library than Makefile<br>
> -targets.<br>
> +The other reason is that most of the logic that needs to be performed is very <br>
> +simple, and python has a few libraries that do most of the work. If it weren't <br>
> +for the desire to have an inventory file (inventory.yaml) with a schema <br>
> +(inventory_schema.json), this probably could have been an AWK script. After the <br>
> +container images are produced, it is very easy to use the same templating <br>
> +engine to produce a makefile that can be used to both build and push the <br>
> +containers. This makefile can be run with multiple jobs for parallel building <br>
> +of containers, something not supported by all compose implementations. <br>
> +<br>
> +Meson was considered instead of Makefiles, however, Meson does not handle new <br>
> +Meson being generated during the build very well, and Meson wants most commands <br>
> +to have an output file, which is not true of many of the commands. Meson is <br>
> +also more difficult to generate using a templating library than Makefile <br>
> +targets. <br>
>  <br>
>  ## Building<br>
>  <br>
>  ### Environment Variables<br>
>  <br>
> -All environment variables are namespaced to DPDK_CI_CONTAINERS to avoid any<br>
> -issues.<br>
> +All environment variables are namespaced to DPDK_CI_CONTAINERS to avoid any <br>
> +issues. <br>
>  <br>
>  | Variable                   | Description                                     | Default | Valid Values |<br>
>  | -------------------------- | ----------------------------------------------- | ------- | ------------ |<br>
> -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'<br>
> +| 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'<br>
>  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'<br>
> +DPDK_CI_CONTAINERS_ONLY_HOST_ARCH | If set to 'Y', only images for the local system architecture will be built. | 'N' | 'Y' or 'N'<br>
> +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'<br>
> +DPDK_CI_CONTAINERS_NINJA_WORKERS | The number of Ninja workers to use to build ABI images. Variable setting is benign if ABI is disabled. | unset | Any positive integer greater than zero.<br>
>  DPDK_CI_CONTAINERS_BUILD_ABI | Whether to bake ABI images into the containers. | 'N' | 'Y' or 'N'<br>
> -DPDK_CI_CONTAINERS_BUILD_LIBABIGAIL | Whether to build libabigail from source on distros that do not package it. DPDK_CI_CONTAINERS_BUILD_ABI=Y overrides this to 'Y' | 'N' | 'Y' or 'N'<br>
> +DPDK_CI_CONTAINERS_NO_LATEST_TAG | Disables tagging the final manifests as "latest" in the local store and remote registry. | 'N' | 'Y' or 'N'<br>
> +DPDK_CI_CONTAINERS_COVERITY | Enable building Coverity images. Setting this flag will make the Coverity binaries required. | 'N' | 'Y' or 'N'<br>
>  DPDK_CI_CONTAINER_BUILDER_PROGRAM | What container builder program to use. | 'podman' | Any container builder that exposes the same interface and provides the same behavior as podman.<br>
> -DPDK_CI_CONTAINERS_LIBABIGAIL_CLONE_URL | What URL to clone libabigail from, since some distros need to compile it from source. | 'git://<a href="http://sourceware.org/git/libabigail.git" rel="noreferrer" target="_blank">sourceware.org/git/libabigail.git</a>' | A repository containing libabigail which shares history with the main repository.<br>
> +DPDK_CI_CONTAINERS_LIBABIGAIL_CLONE_URL | What URL to clone libabigail from, since some distros need to compile it from source. | 'git://<a href="http://sourceware.org/git/libabigail.git" rel="noreferrer" target="_blank">sourceware.org/git/libabigail.git</a>' | A repository containing libabigail which shares history with the main repository. <br>
>  DPDK_CI_CONTAINERS_DPDK_CLONE_URL | What URL to clone DPDK from. | '<a href="https://dpdk.org/git/dpdk" rel="noreferrer" target="_blank">https://dpdk.org/git/dpdk</a>' | Any DPDK mirror.<br>
> +DPDK_CI_CONTAINERS_DPDK_STABLE_CLONE_URL | What URL to clone DPDK stable form. | <a href="http://dpdk.org/git/dpdk-stable" rel="noreferrer" target="_blank">http://dpdk.org/git/dpdk-stable</a> | Any DPDK stable mirror.<br>
>  DPDK_CI_CONTAINERS_CONTAINER_BUILDER_TAG | What tag to give to the container which creates the dockerfiles. The default should be fine unless you have issues with collisions. | 'dpdk_ci_container_builder' | Any valid OCI container tag (A valid C function name will work)<br>
>  DPDK_CI_CONTAINERS_EXTRA_PUSH_ARGS | Extra arguments to add to the push command, can be used for credentials if 'podman login' won't work. | '' | [<a href="https://docs.podman.io/en/latest/markdown/podman-push.1.html#options](https://docs.podman.io/en/latest/markdown/podman-push.1.html%23options)" rel="noreferrer" target="_blank">https://docs.podman.io/en/latest/markdown/podman-push.1.html#options](https://docs.podman.io/en/latest/markdown/podman-push.1.html#options)</a><br>
>  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.<br>
>  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 local file directory.<br>
> +DPDK_CI_CONTAINERS_COVERITY_PATH | The path to Coverity Scan binaries. Only required of the Coverity flag is set. | unset | The path to any local file directory.<br>
>  DPDK_CI_CONTAINERS_CONTEXT_DIRECTORY | Set the directory to build the containers in. All generated files will be placed in this directory or one of it's children | '$(CURDIR)/container_context' | Any absolute directory path<br>
> +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.<br>
>  <br>
>  ### Builder System Requirements<br>
>  <br>
> @@ -91,16 +98,15 @@ DPDK_CI_CONTAINERS_CONTEXT_DIRECTORY | Set the directory to build the containers<br>
>  * find<br>
>  * posix utilities (GNU coreutils will work)<br>
>  * bash<br>
> -* podman >= 4.0.0 (docker or other container builder programs may work, but are<br>
> -unsupported)<br>
> -    * 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.<br>
> -* qemu-$ARCH-static for any non-native architecture/revision you want to build for.<br>
> +* podman (docker is unsupported, and will NOT work for making manifests)<br>
> +* qemu-$ARCH-static for any non-native architecture/revision you want to build <br>
> +for.<br>
>  <br>
>  #### Hardware<br>
>  <br>
> -| Hardware Type | Requirement                  | Reason |<br>
> -| ------------- | ---------------------------- | ----------------------------------- |<br>
> -| 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.<br>
> +| Hardware Type | Requirement                   | Reason |<br>
> +| ------------- | ----------------------------- | ----------------------------------- |<br>
> +| 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.<br>
>  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).<br>
>  <br>
>  <br>
> @@ -111,28 +117,53 @@ RHEL container images must be built on RHEL.<br>
>  ### Build containers locally<br>
>  <br>
>  ```bash<br>
> +# Build using the default arguments<br>
>  make build<br>
>  ```<br>
>  <br>
> +The resulting images will be tagged based on the date tag and platform.<br>
> +Image generated tags follow this format: `image-{{ platform }}-{{ date_tag }}`<br>
> +Where `platform` denotes the platform of the image, and `date_tag` is the generated date tag or the override string provided<br>
> +through the environment variable.<br>
> +<br>
> +They should appear in the local image store on your system.<br>
> +<br>
>  ### Push containers to registry<br>
>  <br>
> -This will probably involve following prompts in your terminal, but if you have<br>
> -other authentication set up, (LDAP, Kerberos, etc), it may not prompt you.<br>
> +This will probably involve following prompts in your terminal, but if you have <br>
> +other authentication set up, (LDAP, Kerberos, etc), it may not prompt you. <br>
>  Logging into a registry is what allows you to upload containers to a remote<br>
> -system for others to pull down.<br>
> +system for others to pull down. <br>
>  <br>
>  If you are working alone, you probably can ignore this and keep the containers<br>
> -locally. If you are in an enterprise setting, ask your DevOps or Systems<br>
> -Administration team where the preferred location for hosting containers is.<br>
> +locally. If you are in an enterprise setting, ask your DevOps or Systems <br>
> +Administration team where the preferred location for hosting containers is. <br>
>  <br>
> -Since these images take so long to build, it is recommended to use a container<br>
> +Since these images take so long to build, it is recommended to use a container <br>
>  registry and have any CI systems pull from that registry.<br>
>  <br>
> -Redhat guide to setting up a podman container registry:<br>
> +Redhat guide to setting up a podman container registry: <br>
>  [<a href="https://www.redhat.com/sysadmin/simple-container-registry%5D(https://www.redhat.com/sysadmin/simple-container-registry)" rel="noreferrer" target="_blank">https://www.redhat.com/sysadmin/simple-container-registry](https://www.redhat.com/sysadmin/simple-container-registry)</a><br>
>  <br>
>  ```bash<br>
>  $DPDK_CI_CONTAINER_BUILDER_PROGRAM login $DPDK_CI_CONTAINERS_REGISTRY_HOSTNAME<br>
>  # < Complete login process ><br>
>  make push<br>
> -```<br>
> \ No newline at end of file<br>
> +```<br>
> +<br>
> +#### Manifests<br>
> +<br>
> +OCI manifests allow the grouping of images for different platforms under the same tag in a repository on a registry.<br>
> +The use of OCI manifests over tagged images reduces the amount of system platform related branching in CI scripting.<br>
> +<br>
> +The Makefile provides the option to push only the images, only the manifests, or push the images and make manifests.<br>
> +The default "push" target will perform the last case.<br>
> +If you choose to create the manifests, then these will be created with the "final" tags like "latest" and the date timestamp.<br>
> +<br>
> +Manifest creation is known to not be compatible with Docker.<br>
> +This feature is known to work when using Podman to post content to a Docker v2 registry.<br>
> +<br>
> +The manifests may be created on the registry independently of the image 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 not create the manifests.<br>
> +<br>
> +If the `DPDK_CI_CONTAINERS_IS_BUILDER` variable is set to 'Y', then the `push_manifests` target will be disabled.<br>
> \ No newline at end of file<br>
<br>
</blockquote></div><br clear="all"><br><span class="gmail_signature_prefix">-- </span><br><div dir="ltr" class="gmail_signature"><div dir="ltr"><div><div><b><span style="background-color:rgb(255,255,255)"><span style="color:rgb(102,102,102)">Adam Hassick</span></span></b><br></div><span style="color:rgb(102,102,102)"></span></div><div><span style="color:rgb(102,102,102)">Senior Developer</span></div><div><span style="color:rgb(102,102,102)"><span style="color:rgb(11,83,148)"><span style="background-color:rgb(255,255,255)">UNH InterOperability Lab</span></span></span><span style="color:rgb(102,102,102)"></span></div><div><span style="color:rgb(102,102,102)"><a href="mailto:ahassick@iol.unh.edu" target="_blank">ahassick@iol.unh.edu</a><br></span></div><div><span style="color:rgb(102,102,102)"><a href="https://www.iol.unh.edu/" target="_blank">iol.unh.edu</a><br></span></div>+1 (603) 475-8248<br></div></div></div>