Buildroot OVERRIDE_SRCDIR: Explain Why a Local Source Edit Did Not Reach the Build

When a local source edit does not affect a Buildroot package, compare the checkout file, synchronized build-tree file and generated output as three separate artifacts. OVERRIDE_SRCDIR does not compile directly in the original checkout. Its synchronization rules can preserve a newer destination file or exclude an input before the package build even starts.

This guide pins Buildroot 2025.02 and uses rsync 3.4.1 documentation to interpret the command’s transfer semantics. The exact Buildroot make rules were inspected. No Buildroot package build or rsync transfer was executed; the edit experiments below are a proposed diagnostic procedure.

Confirm which override file is active

The 2025.02 development guide places the default local.mk beside the active .config, through BR2_PACKAGE_OVERRIDE_FILE and CONFIG_DIR. An out-of-tree O= build therefore normally uses the output directory’s override file, not a similarly named file beside another checkout.

Record the Buildroot tree, output directory, active override file and resolved package source path. Use the package’s uppercase variable prefix, for example a hypothetical SENSORAPP_OVERRIDE_SRCDIR pointing to an owned development checkout. Do not assume editing a local.mk in the current shell directory changes the selected output.

With an override, Buildroot bypasses the normal download, extraction and patch sequence and synchronizes into a package-custom build directory. Any release patches the development checkout needs must be accounted for explicitly. A working override build does not demonstrate that the normal release preparation path still applies those patches.

Read the actual synchronization command

The tagged generic-package implementation runs rsync with -au, a permission policy, package-specific exclusions, VCS exclusions, a trailing slash on the source and the package build directory as destination. Pre- and post-rsync hooks can add behavior and belong in the investigation.

The -u option is especially important. Under the rsync 3.4.1 manual, a regular destination file newer than its source can be skipped. The normal quick check also uses size and modification time rather than computing a full content hash for every ordinary decision.

Therefore compare hashes and timestamps independently. A generated header written recently in the build directory can remain different from an older checkout copy. A content edit that deliberately preserves size and time can also defeat a naive “the timestamp proves it copied” explanation.

Distinguish VCS artifacts from ignored files

The 2025.02 top-level makefile explicitly excludes .svn, .git, .hg, .bzr and CVS names. These are VCS-artifact filters. They are not an instruction to interpret every project’s .gitignore as a source-selection manifest.

Inspect the expanded package-specific OVERRIDE_SRCDIR_RSYNC_EXCLUSIONS as well. A generated directory may be excluded by the recipe, copied because it is merely Git-ignored, or recreated later by the package build. Those three cases require different fixes.

If version generation requires .git metadata, the development guide documents a selective include override. Evaluate the cost and reproducibility implications before adding it. A better upstream version-input mechanism may avoid copying repository internals, but it must be supported by the actual package.

Run a proposed three-file experiment

Choose a disposable output and a small owned package. Prepare one ordinary source file, one file explicitly excluded by the package rule and one generated header. Give each a unique harmless marker and record its hash, size and timestamp in the checkout.

Run the package’s rebuild through the selected Buildroot output, then inspect the custom build directory before interpreting the final executable. The ordinary source should follow the documented transfer conditions. The explicitly excluded input should not be assumed to appear. The generated header needs observations both after synchronization and after its generator runs.

Next create a controlled newer destination copy of the generated header in that disposable tree, leaving the checkout copy older. Repeat synchronization and check whether -u preserves the destination. This is an expected test of update semantics, not an executed result reported by this article.

Trace the first point where provenance diverges

Observation	Next evidence to collect
Checkout changed; synchronized file did not	Active override path, exclusions, timestamps, transfer log and hooks.
Synchronized file changed; generated header did not	Generator inputs, invocation and regeneration dependency.
Generated header changed; object did not	Actual include path and upstream compilation dependency.
Object changed; final image did not	Install path, selected binary and normal image-generation step.

This keeps the investigation focused on the local-source transport boundary before escalating into a general clean-build discussion. Do not add a package dependency merely because a file failed to synchronize; first prove which stage owns it.

Select the appropriate development entry point

In the inspected override rules, rebuild cleanup clears the rsync and build-related stamps, while reconfigure also clears configuration state. The documented package-rebuild all sequence synchronizes and rebuilds the package, then proceeds through the normal all target needed for resulting images.

Use reconfigure when the changed input is consumed during configuration. Rebuild alone cannot guarantee that an upstream configure cache is regenerated. Conversely, repeatedly reconfiguring cannot repair an exclusion that prevents the new input from reaching the custom tree.

The synchronization command contains no –delete option. Files removed from the checkout are therefore not automatically a reliable deletion signal for the destination tree. Preserve evidence and use a fresh disposable package/output comparison when stale generated files matter, rather than blindly deleting the development checkout.

Keep development and release acceptance distinct

Once the local edit is understood, retain the checkout revision plus uncommitted diff, active override configuration, synchronized-file evidence and final artifact hash. Document any generated source or VCS metadata that the development path requires.

Then qualify the maintained release acquisition and patch path separately, without the override, using the project’s controlled inputs. The useful outcome is an explained chain from edited byte to synchronized byte to generated output, with the first divergence identified. A repeated successful make invocation alone does not establish that the intended source change reached the image.