From 73c61f270345bc4d97963b0ed9549be9747a3fe5 Mon Sep 17 00:00:00 2001 From: Adam Stolcenburg Date: Fri, 12 Jun 2026 13:08:25 +0200 Subject: [PATCH] Extend local package store documentation Ref: #RDKEAPPRT-835 --- bolt/docs/local-package-store.md | 75 +++++++++++++++++++++++++++++++- 1 file changed, 74 insertions(+), 1 deletion(-) diff --git a/bolt/docs/local-package-store.md b/bolt/docs/local-package-store.md index 3074d1e..6425d79 100644 --- a/bolt/docs/local-package-store.md +++ b/bolt/docs/local-package-store.md @@ -1,6 +1,10 @@ # Local Package Store The local package store is a directory on the developer's machine where bolt packages are stored. +It is a plain directory named `bolts` containing `+.bolt` files — there is no index +or any other metadata. The bolt tool never creates the store by itself; it has to be created +manually. + It is used by: - `bolt make` — to resolve [package dependencies](make.md#dependency-handling) and to install @@ -9,7 +13,7 @@ It is used by: - `bolt push` — to [locate packages by name](push.md#locating-the-package) when no file path is provided. -## Location +## Location and Discovery - Directory name: `bolts` - Recommended location: your home directory @@ -20,3 +24,72 @@ mkdir ${HOME}/bolts - Located by traversing upward from: - The directory defined by [`BUILDDIR`](https://docs.yoctoproject.org/ref-manual/variables.html#term-BUILDDIR), or - The current directory (if `BUILDDIR` is undefined). + +For example, when bolt runs in `~/work/myapp/build` (with `BUILDDIR` undefined), it checks the +following directories in order and uses the first one that exists: + +``` +~/work/myapp/build/bolts +~/work/myapp/bolts +~/work/bolts +~/bolts +/home/bolts +/bolts +``` + +Two consequences of this discovery scheme are worth noting: + +- **The nearest store wins.** A `bolts` directory created inside a project shadows `~/bolts`, + so independent projects can deliberately keep isolated package stores. +- **`BUILDDIR` takes precedence over the current directory.** Inside a sourced Yocto build + environment the search starts from the build directory, so a different store may be found + than when running the same command from the same shell location without the environment. + +## Contents + +The store holds bolt packages as files named `+.bolt`, in a single flat directory. +Because there is no additional metadata, the store can be managed with ordinary file operations: +copying a package file into the directory makes it available to dependency resolution and name +lookup, and deleting the file removes it. + +## Example + +The following session builds the base layer package from the `meta-bolt-distro` repository, +installs it into the store, and then builds an application package whose dependency on +`com.rdkcentral.base` is resolved from the store: + +``` +$ mkdir ~/bolts + +$ cd ~/work/meta-bolt-distro +$ bolt make base --install +(...) +Installed com.rdkcentral.base+0.2.0.bolt in /home/user/bolts + +$ cd ~/work/meta-bolt-myapp +$ bolt make myapp --install +(...) +Installed com.rdkcentral.myapp+1.0.0.bolt in /home/user/bolts + +$ ls ~/bolts +com.rdkcentral.base+0.2.0.bolt +com.rdkcentral.myapp+1.0.0.bolt + +$ bolt push stb com.rdkcentral.myapp+1.0.0 +``` + +The final `bolt push` locates the package by name in the store, so it works from any directory +from which the store can be discovered. + +Note that the example relies on the build directories being located below the home directory — +that is what makes `~/bolts` discoverable by the upward search. Running the same commands from a +directory outside the home directory would not find the store. + +## When No Store Is Found + +- `bolt make --install` aborts with an error. +- `bolt make` cannot resolve package dependencies, so building a package that declares + dependencies fails. +- `bolt push ` cannot locate packages by name; only file paths and file names + in the current directory keep working. +- `bolt fetch` aborts with an error, as there is nowhere to store the downloaded package.