Building Components From Source

By default, a BitBake recipe fetches the source artifact named in its SRC_URI (typically a tarball or a pinned git revision hosted by AMD). Override that source without editing the EDF recipe when you track an upstream branch, prototype a fix, or iterate on a working copy on your local filesystem.

This page describes the two supported overrides and the Yocto plumbing they need, using u-boot-xlnx as the worked example:

• Building from a Remote Source Repository – point the recipe at a different git repository, branch, or commit.

• Building from a Local External Repository – build directly from a checkout on your build host using externalsrc.

Both overrides take effect through a .bbappend file in a user layer. If you edit recipes inside the AMD-provided layers directly, the next layer update overwrites those edits, and rebasing onto a newer EDF release turns into a manual merge instead of a clean repo sync.

Prerequisites

Before you can add a .bbappend, your build environment must contain a writable user layer that BitBake parses. The following steps create meta-user next to the AMD layers in the sources/ directory. Skip them if your project already has a user layer.

1. Source the Yocto build environment (see Setting Up the Yocto Environment) so that bitbake-layers is on your PATH and BBPATH has a value.

2. Create the layer:

   $ bitbake-layers create-layer ../sources/meta-user
   

3. Add the layer to bblayers.conf so BitBake parses it:

   $ bitbake-layers add-layer ../sources/meta-user
   

4. Confirm BitBake sees the layer:

   $ bitbake-layers show-layers
   

Note

The .bbappend filename must match the recipe it extends. Use <recipe>_<version>.bbappend to target a specific version, or <recipe>_%.bbappend to match every version of the recipe. The directory under recipes-*/ should mirror the layout used by the original recipe. For u-boot-xlnx that path is meta-user/recipes-bsp/u-boot/u-boot-xlnx_%.bbappend.

Building from a Remote Source Repository

Use this override when you want a recipe to fetch from a different git repository, branch, or commit than the one AMD ships. This is the typical workflow for tracking an upstream fix on github.com/Xilinx before it lands in the next EDF release.

Generic Pattern

For any recipe whose SRC_URI is a plain git source with a SRCREV pin, create meta-user/recipes-<class>/<recipe>/<recipe>_%.bbappend and reassign the relevant variables:

# Generic remote-source override
SRC_URI = "git://<host>/<org>/<repo>.git;protocol=https;branch=<branch>"
SRCREV  = "<full 40-char commit hash>"

Key variables:

• SRC_URI – the fetch address. Use the git:// scheme with protocol=https (or protocol=ssh for private repos) and select the upstream branch with ;branch=<branch>.

• SRCREV – the exact commit BitBake checks out from that branch. Must be a full 40-character SHA.

• An optional UBRANCH (or similarly named) variable keeps the branch name in one place when both SRC_URI and another recipe variable need it.

These assignments use = (not :append or :prepend, and not the legacy _append / _prepend forms that older recipes still use), so they fully replace the values the upstream recipe inherits. BitBake then fetches from your fork or branch instead of the AMD default.

Example: u-boot-xlnx

The UBRANCH and SRC_URI values shown match the EDF v26.06 release. The example pins SRCREV to a commit other than the recipe default, so the bitbake -e u-boot-xlnx | grep ^SRCREV= step that follows shows a different SHA and confirms the override. In your own bbappend, set SRCREV to whichever commit on UBRANCH you want to build.

1. Create the bbappend directory in your user layer:

   $ mkdir -p ../sources/meta-user/recipes-bsp/u-boot
   

2. Create ../sources/meta-user/recipes-bsp/u-boot/u-boot-xlnx_%.bbappend with the following content:

   # Build u-boot-xlnx from a remote source repository
   # (custom fork or branch).
   UBRANCH = "xlnx_rebase_v2026.01"
   SRCREV  = "980da51527e0a9a7a79ac218347ade2bfd5bb330"
   SRC_URI = "git://github.com/Xilinx/u-boot-xlnx.git;protocol=https;branch=${UBRANCH}"
   

   The upstream u-boot-xlnx-common.inc already builds SRC_URI from UBOOTURI and UBRANCH (SRC_URI = "${UBOOTURI};${UBRANCHARG}"), so when you stay on the same github.com/Xilinx/u-boot-xlnx fork you only need to override UBRANCH and SRCREV - the inherited SRC_URI recomputes. Reassign SRC_URI only when the override fetches from a different repository (a fork, a mirror, or an internal git host).

3. Verify BitBake picks up the bbappend:

   $ bitbake-layers show-appends | grep u-boot-xlnx
   u-boot-xlnx_2026.01-xilinx-v2026.1.bb:
     .../meta-amd-edf/recipes-bsp/u-boot/u-boot-xlnx_%.bbappend
     .../meta-kria/recipes-bsp/u-boot/u-boot-xlnx_%.bbappend
     .../meta-embedded-plus/recipes-bsp/u-boot/u-boot-xlnx_%.bbappend
     .../meta-amd-adaptive-socs/meta-amd-adaptive-socs-bsp/recipes-bsp/u-boot/u-boot-xlnx_%.bbappend
     .../meta-user/recipes-bsp/u-boot/u-boot-xlnx_%.bbappend
   

4. Confirm BitBake applies the override values by inspecting the recipe’s parsed environment:

   $ bitbake -e u-boot-xlnx | grep ^SRC_URI=
   SRC_URI="git://github.com/Xilinx/u-boot-xlnx.git;protocol=https;branch=xlnx_rebase_v2026.01 "
   
   $ bitbake -e u-boot-xlnx | grep ^SRCREV=
   SRCREV="980da51527e0a9a7a79ac218347ade2bfd5bb330"
   

5. Build U-Boot for your target board:

   $ MACHINE=versal-vek280-sdt-seg bitbake -c cleansstate u-boot-xlnx
   $ MACHINE=versal-vek280-sdt-seg bitbake u-boot-xlnx
   

   The output binaries land in tmp/deploy/images/<machine>/u-boot*.

Tip

SRCREV must be a full 40-character commit hash. Using a branch name or short hash causes BitBake to fail with Fetcher failure for URL errors. To always track the tip of a branch (not recommended for reproducible builds), set SRCREV = "${AUTOREV}".

Building from a Local External Repository

Use this override when you have a working copy on the build host and want BitBake to compile it directly, skipping do_fetch and do_unpack. This is the fastest iteration loop for local patches. Edits in your working copy take effect on the next bitbake invocation.

Generic Pattern

For any recipe, create the bbappend at the matching path in your user layer and inherit the externalsrc class:

# Generic externalsrc override
inherit externalsrc

EXTERNALSRC       = "/abs/path/to/source"
EXTERNALSRC_BUILD = "/abs/path/to/source/build"

Key variables:

• inherit externalsrc – swaps the recipe’s do_fetch and do_unpack for a no-op that points at a directory on disk, so edits in your working copy take effect on the next build.

• EXTERNALSRC – absolute path to the source tree BitBake compiles.

• EXTERNALSRC_BUILD – absolute path to a writable directory for object files and intermediates. It can be the same as EXTERNALSRC or a subdirectory of it.

Note

The unqualified EXTERNALSRC and EXTERNALSRC_BUILD assignments in the preceding code block work because the bbappend is already scoped to a single recipe. If you ever drive externalsrc from local.conf (or another non-recipe context), switch to the global form: add INHERIT += "externalsrc" to the configuration and use EXTERNALSRC:pn-<recipe> / EXTERNALSRC_BUILD:pn-<recipe> so the override binds to a specific recipe instead of every recipe BitBake parses.

Example: u-boot-xlnx

1. Clone (or otherwise place) the U-Boot source at a stable location on the build host, outside the Yocto build/ directory:

   $ git clone https://github.com/Xilinx/u-boot-xlnx.git \
         /path/to/local/directory
   

2. Create the bbappend directory in your user layer:

   $ mkdir -p ../sources/meta-user/recipes-bsp/u-boot
   

3. Create ../sources/meta-user/recipes-bsp/u-boot/u-boot-xlnx_%.bbappend with the following content:

   # Build u-boot-xlnx from a local external source repo.
   inherit externalsrc
   
   EXTERNALSRC       = "/path/to/u-boot-xlnx"
   EXTERNALSRC_BUILD = "/path/to/u-boot-xlnx/build"
   

   EXTERNALSRC_BUILD must point at a writable directory. BitBake writes object files and intermediates there instead of under ${WORKDIR}. The directory must exist (or the recipe’s build step must create it), and the user running BitBake must have write permission.

4. Build U-Boot. externalsrc bypasses do_fetch/do_unpack, so every rebuild compiles the current contents of EXTERNALSRC in place:

   $ MACHINE=versal-vek280-sdt-seg bitbake u-boot-xlnx
   

   Confirm the recipe is compiling from your tree (not the shipped tarball) by checking the build log header:

   $ head -5 tmp/work/*/u-boot-xlnx/*/temp/log.do_compile \
         | grep "compiling from external source tree"
   NOTE: u-boot-xlnx: compiling from external source tree /path/to/u-boot-xlnx
   

Warning

externalsrc weakens Yocto’s reproducibility guarantees. The recipe signature no longer reflects the source contents, so sstate does not automatically detect changes in the external tree. Use bitbake -c cleansstate <recipe> if a rebuild does not pick up your local edits.

Remove the externalsrc override from your bbappend before you produce a release build. Rebuild release artifacts from the recipe’s pinned SRC_URI / SRCREV so the signatures sstate records match the shipped sources.