[Buildroot] [PATCH v2 23/23] docs/manual: document out-of-tree package builds and the new srcdir variables

[Florian Fainelli via buildroot <buildroot@buildroot.org>]

Signed-off-by: Florian Fainelli <florian.fainelli@broadcom.com>
---
 docs/manual/adding-packages-generic.adoc     | 12 +++++++
 docs/manual/using-buildroot-development.adoc | 38 ++++++++++++++++++++
 2 files changed, 50 insertions(+)

diff --git a/docs/manual/adding-packages-generic.adoc b/docs/manual/adding-packages-generic.adoc
index e7547460fd50..5b020d78a214 100644
--- a/docs/manual/adding-packages-generic.adoc
+++ b/docs/manual/adding-packages-generic.adoc
@@ -666,6 +666,18 @@ In the action definitions, you can use the following variables:
 * +$(@D)+, which contains the directory in which the package source
   code has been uncompressed.
 
+* +$(LIBFOO_SRCDIR)+ is the directory containing the package sources,
+  +$(LIBFOO_SRCSUBDIR)+ is the same directory with +LIBFOO_SUBDIR+
+  appended, and +$(LIBFOO_BUILDDIR)+ is the directory in which the package
+  is built. By default, these all point to +$(@D)+, but they can differ:
+  build systems that build out of source set +$(LIBFOO_BUILDDIR)+ to a
+  sub-directory, and a package that supports being built out of tree has
+  its sources in +output/source/+, or in the directory given by
+  +LIBFOO_OVERRIDE_SRCDIR+ when it is set. A
+  recipe that only reads the package sources (for example to copy a header)
+  should use +$(LIBFOO_SRCDIR)+ rather than +$(@D)+, which is the build
+  directory. See xref:outoftree-build[] for more details.
+
 * +$(LIBFOO_DL_DIR)+ contains the path to the directory where all the downloads
   made by Buildroot for +libfoo+ are stored in.
 
diff --git a/docs/manual/using-buildroot-development.adoc b/docs/manual/using-buildroot-development.adoc
index 72628e0a6f99..de62c0a89ed4 100644
--- a/docs/manual/using-buildroot-development.adoc
+++ b/docs/manual/using-buildroot-development.adoc
@@ -119,3 +119,41 @@ cost of a slower speed, add these directories back:
 ----
 LINUX_OVERRIDE_SRCDIR_RSYNC_EXCLUSIONS = --include .git
 ----
+
+[[outoftree-build]]
+===== Building out of tree
+
+A package can opt in to being built out of tree by setting
++LIBFOO_SUPPORTS_OUT_OF_TREE = YES+. Such a package is always built out of
+tree: its sources are extracted and patched in
++output/source/<package>-<version>+, and only the generated files, including
+the stamp files of the configure, build and install steps, are stored in
++output/build/<package>-<version>+. Other packages are not affected: their
+sources and generated files are both in +output/build/<package>-<version>+.
+
+When +LIBFOO_OVERRIDE_SRCDIR+ is set for such a package, Buildroot does not
+_rsync_ the sources to +output/build/<package>-custom/+. Instead, the
+package is built from the overridden directory, with all the generated
+files, including the stamp files, stored in
++output/build/<package>-custom/+. The overridden directory is therefore not
+modified by the build. The +<pkg>_PRE_RSYNC_HOOKS+ and
++<pkg>_POST_RSYNC_HOOKS+ hooks are still run, but +$(@D)+ then does not
+contain the sources: hooks should use +$(LIBFOO_SRCDIR)+ to access them.
+
+Currently the +linux+ package supports this. When the sources are overridden,
+the kernel source tree must be clean (no +.config+, +include/config+ or
++arch/*/include/generated+, as required by the kernel when using +O=+); run
++make mrproper+ in it if needed. The kernel is configured and built with
++O=+ pointing to +output/build/linux-<version>/+ (or
++output/build/linux-custom/+ when the sources are overridden).
+
+When a custom logo (+BR2_LINUX_KERNEL_CUSTOM_LOGO_PATH+) or custom device
+tree files (+BR2_LINUX_KERNEL_CUSTOM_DTS_PATH+) are used, or when
++linux-tools+ are enabled, Buildroot has to add files to, or build inside,
+the kernel sources. To avoid modifying the overridden directory, it then
+builds from a _shadow_ copy: a tree of real directories containing
+symbolic links to the files of the original tree, created by
++support/scripts/symlink-tree+.
+
+Packages that read files from the kernel sources, such as headers, must use
++$(LINUX_SRCDIR)+ and not +$(LINUX_DIR)+.
-- 
2.34.1

_______________________________________________
buildroot mailing list
buildroot@buildroot.org
https://lists.buildroot.org/mailman/listinfo/buildroot