From b43e4ce008fc1beb3adadcb623e66d54f10615f3 Mon Sep 17 00:00:00 2001 From: Ahmed Karic Date: Tue, 14 Nov 2023 10:01:54 +0100 Subject: [PATCH] doc: added instructions for package override using local.mk --- doc/developers-guide.md | 2 +- doc/override-package.md | 50 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 51 insertions(+), 1 deletion(-) create mode 100644 doc/override-package.md diff --git a/doc/developers-guide.md b/doc/developers-guide.md index 2541f923..3d518e03 100644 --- a/doc/developers-guide.md +++ b/doc/developers-guide.md @@ -75,7 +75,7 @@ To see available defconfigs for supported targets, use: Development ----------- -When changing a package, locally kept sources, or when using `local.mk`, +When changing a package, locally kept sources, or when using [`local.mk`](override-package.md), you only want to rebuild the parts you have modified: make foo-rebuild diff --git a/doc/override-package.md b/doc/override-package.md new file mode 100644 index 00000000..8455f57d --- /dev/null +++ b/doc/override-package.md @@ -0,0 +1,50 @@ +Package override +================ + +This guide demonstrates how the `local.mk` file is utilized to override +a Linux Buildroot package. The example of `tcpdump` serves to illustrate +this process. + +In an instance such as `Infix` using tcpdump, the `local.mk` file is modified +as shown below: + +``` +TCPDUMP_OVERRIDE_SRCDIR = /path/to/tcpdump/repo +``` + +and stored in the `output/` folder, alongside the `.config` file: +``` +user@PC:~/infix$ll output/ | grep -e 'local.mk' -e '.config' +-rw-r--r-- 1 group user 119936 Nov 10 18:04 .config +-rw-r--r-- 1 group user 43 Nov 10 18:25 local.mk +``` + +The execution of `make tcpdump-rebuild all` triggers a process where +Buildroot synchronizes the tcpdump source code from the specified override directory +to `output/build/tcpdump-custom`, followed by the rebuilding of the entire project. + +``` +user@PC:~/infix$ make tcpdump-rebuild all +``` + + +``` +user@PC:~/infix$ ll /output/build/ | grep tcpdump +drwxr-xr-x 7 group user 20480 Nov 10 18:26 tcpdump-4.99.4/ +drwxr-xr-x 7 group user 12288 Nov 10 18:28 tcpdump-custom/ +``` + +Buildroot follows a process of downloading and processing tarballs +(extraction, configuration, compilation, and installation). +The source code is stored in a temporary directory: +`output/build/-` (i.e. `tcpdump-4.99.4/`), +which is removed and recreated with each `make` command. That is why +the direct modifications in the `output/build` directory are generally +**not recommended**. + +To manage the development changes more effectively, where the package source code +remains untouched, Buildroot incorporates the `_OVERRIDE_SRCDIR` feature. + +For a comprehensive understanding of utilizing Buildroot during development, +including detailed elaboration on the `_OVERRIDE_SRCDIR` feature, +refer to section 8.13.6 in [Using Buildroot during development](https://nightly.buildroot.org/). \ No newline at end of file