From f1e7fda9567b7a8436914aa6fdfa29bb4bf06d3d Mon Sep 17 00:00:00 2001 From: Joachim Wiberg Date: Mon, 20 May 2024 21:28:04 +0200 Subject: [PATCH] doc: revise developer's guide a bit wrt. packge overrides Signed-off-by: Joachim Wiberg --- doc/developers-guide.md | 9 +++-- doc/override-package.md | 81 +++++++++++++++++++++++++++-------------- 2 files changed, 59 insertions(+), 31 deletions(-) diff --git a/doc/developers-guide.md b/doc/developers-guide.md index 949ac97b..8644e518 100644 --- a/doc/developers-guide.md +++ b/doc/developers-guide.md @@ -97,8 +97,10 @@ To see available defconfigs for supported targets, use: Development ----------- -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: +Developing with Infix is the same as [developing with Buildroot][4]. +When working with a package, be it locally kept sources, or when using +[`local.mk`](override-package.md), you only want to rebuild the parts +you have modified: make foo-rebuild @@ -106,7 +108,7 @@ or make foo-reconfigure -or, when nothing seems to bite: +or, as a last resort when nothing seems to bite: make foo-dirclean foo-rebuild @@ -203,3 +205,4 @@ $ git submodule update --init [1]: https://buildroot.org/downloads/manual/manual.html [2]: https://github.com/wkz/qeneth [3]: https://netopeer.liberouter.org/doc/sysrepo/master/html/dev_guide.html +[4]: https://buildroot.org/downloads/manual/manual.html#_developer_guide diff --git a/doc/override-package.md b/doc/override-package.md index 8455f57d..262625b7 100644 --- a/doc/override-package.md +++ b/doc/override-package.md @@ -1,50 +1,75 @@ -Package override +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 guide demonstrates how the `local.mk` file is utilized to override +a Linux Buildroot package. As an example we use `tcpdump` to illustrate this process. -In an instance such as `Infix` using tcpdump, the `local.mk` file is modified -as shown below: +> For a comprehensive guide to utilizing Buildroot during development, +> including the `_OVERRIDE_SRCDIR` mechanism, shown below, please +> see [Using Buildroot during development][1] in the official docs. + + +Setup +----- + +Since the `output/` directory is often wiped for rebuilds, make sure you +keep the file `local.mk` in the top directory and only symlink it to your +build directory: + + ~$ cd infix/ + ~/infix(main)$ touch local.mk + ~/infix/output(main)$ ln -s ../local.mk . + ~/infix/output(main)$ cd .. + + +Override +-------- + +Now edit the file: + + ~/infix(main)$ editor local.mk + +Add an override for `tcpdump`. The file is a Makefile snippet so you +can add a lot of things. Comment out lines with the UNIX comment `#` +character if needed: ``` 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 -``` +Building +-------- -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. +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 +~/infix$(main)$ make tcpdump-rebuild all ``` +Buildroot follows a process of downloading and processing tarballs: +extraction, configuration, compilation, and installation. The source +for each package is extracted to a temporary build directory: + + output/build/- # e.g., tcpdump-4.99.4 + +Let's have a look at what we got: ``` -user@PC:~/infix$ ll /output/build/ | grep tcpdump +~/infix$(main)$ 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**. +As long as your local override is in place, Buildroot will use your +custom version. -To manage the development changes more effectively, where the package source code -remains untouched, Buildroot incorporates the `_OVERRIDE_SRCDIR` feature. +> **Remember:** the build directory is ephemeral, so be careful to +> change any of the files therein. It can be useful though during +> debugging, but just make sure to learn the difference between the +> various Buildroot commands to build, clean, reconfigure, etc. -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 +[1]: https://buildroot.org/downloads/manual/manual.html#_using_buildroot_during_development