To migrate from an older Buildroot version, take the following steps.

Before Buildroot 2016.11, it was possible to use only one br2-external tree at once. With Buildroot 2016.11 came the possibility to use more than one simultaneously (for details, see Section 9.2, “Keeping customizations outside of Buildroot”).

This however means that older br2-external trees are not usable as-is. A minor change has to be made: adding a name to your br2-external tree.

This can be done very easily in just a few steps:

Now, your br2-external tree can be used with Buildroot 2016.11 onward.

Note: This change makes your br2-external tree incompatible with Buildroot before 2016.11.

Before Buildroot 2017.08, host packages were installed in $(HOST_DIR)/usr (with e.g. the autotools' --prefix=$(HOST_DIR)/usr). With Buildroot 2017.08, they are now installed directly in $(HOST_DIR).

Whenever a package installs an executable that is linked with a library in $(HOST_DIR)/lib, it must have an RPATH pointing to that directory.

An RPATH pointing to $(HOST_DIR)/usr/lib is no longer accepted.

Before Buildroot 2023.11, the subversion download backend unconditionally retrieved the external references (objects with an svn:externals property). Starting with 2023.11, externals are no longer retrieved by default; if you need them, set LIBFOO_SVN_EXTERNALS to YES. This change implies that:

Before Buildroot 2023.11, it was possible (but undocumented and unused) to apply architecture-specific patches, by prefixing the patch filename with the architecture, e.g. 0001-some-changes.patch.arm and such a patch would only be applied for that architecture. With Buildroot 2023.11, this is no longer supported, and such patches are no longer applied at all.

If you still need per-architecture patches, then you may provide a pre-patch hook that copies the patches applicable to the configured architecture, e.g.:

define LIBFOO_ARCH_PATCHES
    $(foreach p,$(wildcard $(LIBFOO_PKGDIR)/*.patch.$(ARCH)), \
        cp -f $(p) $(patsubst %.$(ARCH),%,$(p))
    )
endef
LIBFOO_PRE_PATCH_HOOKS += LIBFOO_ARCH_PATCHES

Note that no package in Buildroot has architecture-specific patches, and that such patches will most probably not be accepted.

The download backends have been extended in various ways.

To accommodate those changes, the archive suffix has been updated or added:

Note that, if two such prefixes would apply to a generated archive, like for a cargo package downloaded from git, both suffixes need to be added, first the one for the download mechanism, then the one for the vendoring, e.g.: libfoo-1.2.3-git4-cargo2.tar.gz.

Because of this, the hash file of any custom packages or custom versions for kernel and bootloaders must be updated. The following sed scripts can automate the rename in the hash file (assuming such files are kept under git):

# For git and svn packages, which originally had -br2 resp. -br3 suffix
sed -r -i -e 's/-br2/-git4/; s/-br3/-svn5/' $(
    git grep -l -E -- '-br2|-br3' -- '*.hash'
)

# For go packages, which originally had no suffix
sed -r -i -e 's/(\.tar\.gz)$/-go2\1/' $(
    git grep -l -E '\$\(eval \$\((host-)?golang-package\)\)' -- '*.mk' \
    |sed -r -e 's/\.mk$/.hash/' \
    |sort -u
)

# For cargo packages, which originally had no suffix
sed -r -i -e 's/(\.tar\.gz)$/-cargo2\1/' $(
    git grep -l -E '\$\(eval \$\((host-)?cargo-package\)\)' -- '*.mk' \
    |sed -r -e 's/\.mk$/.hash/' \
    |sort -u
)

Note that the hash will have changed, so that needs to be updated (manually) as well.