Build EDF Yocto with the xilinx/edf build container

AMD publishes a Docker container image that has every package the EDF Yocto build needs preinstalled. Pull the image from Docker Hub and run BitBake inside it to build EDF without modifying the host operating system.

The image is published as xilinx/edf on Docker Hub. The build host images live under the ubuntu2204- tag series, for example xilinx/edf:ubuntu2204-26.06. Other tags under the same repository, such as hello-world- and vek280-aie-gmio-, are target-side container payloads, not host build environments, and are covered in Building and publishing container images with EDF.

When to use the build container

The build container is useful when any of the following apply:

  • The host operating system is not on the supported Yocto build host list, or installing the required packages on the host is not acceptable.

  • Multiple developers must share an identical, reproducible build environment that does not depend on the host OS.

  • A continuous integration job needs a clean, prebuilt environment for every run, with no host-side setup.

If the build host already meets the EDF prerequisites described in Operating System Integration and Development, the native build flow works without the container.

What the container provides

The ubuntu2204-26.06 tag is built from the upstream ubuntu:22.04 image and installs the package set required by the Yocto Project and the EDF build:

  • Build essentials: build-essential, gcc, g++, gcc-multilib, g++-multilib, libc6-dev-i386, make, autoconf, automake, bison, and patch.

  • Yocto and BitBake host requirements: gawk, wget, gperf, git-core, subversion, diffstat, unzip, sysstat, texinfo, chrpath, socat, cpio, xz-utils, locales, lz4, zstd, and bmap-tools.

  • Python toolchain: python3, python3-pip, python3-pexpect, python3-virtualenv, python3-git, python3-jinja2, and pylint, plus pyyaml from pip.

  • Tooling: repo, screen, tmux, sudo, net-tools, iproute2, iputils-ping, openssh-server, graphviz, gitk, and xterm.

  • Graphics or VNC support for tools that expect a display: libegl1-mesa, libsdl1.2-dev, xvfb, fluxbox, and tightvncserver.

The image runs as the unprivileged user amd-edf (UID and GID 1000) in the home directory /home/amd-edf and starts an interactive bash shell as the default command.

Pull the build container

Pull the ubuntu2204-26.06 image for this EDF release:

$ docker pull xilinx/edf:ubuntu2204-26.06

Confirm the image is available locally:

$ docker image ls xilinx/edf
REPOSITORY   TAG                IMAGE ID       CREATED        SIZE
xilinx/edf   ubuntu2204-26.06   e4a967c561b8   6 months ago   1.45GB

The full list of published tags is at https://hub.docker.com/r/xilinx/edf/tags.

Run an EDF Yocto build inside the container

The container has no EDF source tree of its own. Run BitBake against a workspace on the host that is bind-mounted into the container, so that source, downloads, sstate cache, and build outputs persist across container runs and survive docker run --rm.

Prepare a workspace on the host

Create a directory on the host for the EDF source and the BitBake caches. Keep downloads/ and sstate-cache/ outside the build directory so they are reused across machines and across container runs:

$ mkdir -p ~/yocto/edf/sources
$ mkdir -p ~/yocto/edf/downloads
$ mkdir -p ~/yocto/edf/sstate-cache

Initialize the EDF source tree the same way as a native build. Follow the Yocto Project build setup steps in Operating System Integration and Development. Run those steps on the host or inside the container; the container has repo and git preinstalled and is sufficient for the source fetch.

Start the container

Start an interactive shell with the workspace bind-mounted at the default home directory:

$ docker run --rm -it \
      --name edf-build \
      -v ~/yocto/edf:/home/amd-edf/edf \
      -w /home/amd-edf/edf \
      xilinx/edf:ubuntu2204-26.06

The mount path /home/amd-edf/edf is a convention; any path inside the container works as long as the workspace is writable by the amd-edf user. --rm removes the container on exit, but the workspace under ~/yocto/edf on the host is preserved.

Run the build

Inside the container, source the build environment and start BitBake. The following example builds the EDF disk image for a Versal target:

amd-edf@host:~/edf$ source sources/poky/oe-init-build-env build
amd-edf@host:~/edf/build$ MACHINE=versal-vek280-sdt-seg \
      bitbake edf-linux-disk-image

Outputs land under build/tmp/deploy/images/<MACHINE>/ on the host, exactly as for a native build.

Reuse downloads and sstate across runs

Point DL_DIR and SSTATE_DIR at the host-mounted directories so later container runs reuse fetched sources and cached build artifacts. Add the following to build/conf/local.conf:

DL_DIR     ?= "/home/amd-edf/edf/downloads"
SSTATE_DIR ?= "/home/amd-edf/edf/sstate-cache"

The directories live on the host, so removing the container or pulling a newer image does not invalidate the cache.

Common options

Build in the background

For a long build that must outlive the terminal session, replace -it with -d to detach, then reattach with docker logs:

$ docker run -d --name edf-build \
      -v ~/yocto/edf:/home/amd-edf/edf \
      -w /home/amd-edf/edf \
      xilinx/edf:ubuntu2204-26.06 \
      bash -lc "source sources/poky/oe-init-build-env build && \
                MACHINE=versal-vek280-sdt-seg bitbake edf-linux-disk-image"

$ docker logs -f edf-build

Match the host user and group

The container runs as amd-edf with UID and GID 1000. If the host account uses a different UID, files created by the build are owned by UID 1000 on the host and may be hard to manage from the host account. Two options:

  • Run the container as the host user with --user "$(id -u):$(id -g)". BitBake works as any non-root user that owns the workspace, but the home directory inside the container is not preconfigured for that UID.

  • Bind-mount the workspace at a path the amd-edf user owns and match its UID by recreating the host directory with chown 1000:1000.

Pin to a release tag

The ubuntu2204- tag stream is updated each release. Pin to the tag that matches the EDF source tree, for example xilinx/edf:ubuntu2204-26.06 for the EDF 26.06 release. Avoid floating tags such as latest; pin to an explicit release tag for reproducibility.

Build the container from source

The Dockerfile and build pipeline are maintained internally. After they publish to a public repository, this section links directly to that repository. Until then, treat xilinx/edf:ubuntu2204- as the canonical reference for the EDF Yocto build environment.

Troubleshooting

  • “denied: requested access is denied” on docker pull – the xilinx/edf repository is public; check that the host has network access to registry-1.docker.io and that no corporate proxy is rewriting the request.

  • BitBake fails with a Please use a 64 bit system message – the build container is amd64. Pull and run on an x86_64 host; ARM hosts must use a different image or run under emulation.

  • Files under the bind-mounted workspace are owned by an unexpected user on the host – examine the UID and GID mapping options described in the previous section and rerun the build with the --user flag.

  • BitBake cannot reach the network from inside the container – the container inherits the host network by default. If the host uses a corporate proxy, set http_proxy, https_proxy, and no_proxy in the container with -e flags on docker run, and add the matching proxy variables to build/conf/local.conf.

Next steps

References