From a236b90db9686b14fcc0246b86d1d1651610f887 Mon Sep 17 00:00:00 2001
From: Anders Ingemann <aim@orbit.online>
Date: Tue, 21 Nov 2023 15:30:55 +0100
Subject: [PATCH] README: Add additional tips for scripting

---
 README.md | 22 +++++++++++++++++++---
 1 file changed, 19 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index 4542fe1..b973eae 100644
--- a/README.md
+++ b/README.md
@@ -23,6 +23,7 @@ and global installation for user- or system-wide usage.
     - [Transactionality](#transactionality)
   - [Including dependencies](#including-dependencies)
   - [Checking dependencies](#checking-dependencies)
+  - [Additional tips for scripting](#additional-tips-for-scripting)
   - [upkg.json](#upkg-json)
     - [dependencies](#dependencies)
     - [files](#files)
@@ -209,9 +210,6 @@ my_fn() {
 my_fn "$@"
 ```
 
-Use `upkg root -g` to get the path to the global installation instead of
-hardcoding `$HOME/.local/lib/upkg` or `/usr/local/lib/upkg`.
-
 ### Checking dependencies
 
 For scripts that you don't install via μpkg, checking whether dependencies are
@@ -226,6 +224,24 @@ PKGROOT=$(upkg root "${BASH_SOURCE[0]}")
 })
 ```
 
+### Additional tips for scripting
+
+When creating scripts not installed via μpkg, use `upkg root -g` to get the path
+to the global installation instead of hardcoding `$HOME/.local/lib/upkg` or
+`/usr/local/lib/upkg`.
+
+Use `local pkgroot; pkgroot=$(upkg root "${BASH_SOURCE[0]}")` inside your function
+if you are building a library (as opposed to a command) to avoid `$PKGROOT`
+being overwritten by external code.
+
+You only need to specify `# shellcheck source-path=` if your script is not
+located in `$pkgroot` (`source-path` is `./` by default).
+
+If you are calling scripts from the same package consider using
+[path-tools](https://github.com/orbit-online/path-tools) to avoid prepending
+the same `.upkg/bin` PATH multiple times (i.e. use
+`PATH=$("$pkgroot/.upkg/.bin/path_prepend" "$pkgroot/.upkg/.bin")` instead).
+
 ### upkg.json
 
 `upkg.json` has no package name, version or description.