From 148d90a0ba702224501d6d7252607d37cb6c4f75 Mon Sep 17 00:00:00 2001
From: XeroOl <xerool@protonmail.com>
Date: Sat, 25 Oct 2025 14:56:16 -0500
Subject: [PATCH] update docs on packaging

the packaging situation has slightly changed since writing the
documentation, so it was out of date.
---
 Makefile           |  4 ++--
 docs/packaging.md  | 55 +++++++++++++++++++++++++++++-----------------
 tools/get-deps.fnl | 20 ++++++++++-------
 3 files changed, 49 insertions(+), 30 deletions(-)

diff --git a/Makefile b/Makefile
index 35163c2..ad18093 100644
--- a/Makefile
+++ b/Makefile
@@ -117,8 +117,8 @@ clean:
 
 # Steps to release a new fennel-ls version
 
-# 0. run `make test` and `make selflint`, and/or check builds.sr.ht to ensure things are working.
-# 1. Ensure fennel and dkjson are up to date with `make check-deps`
+# 0. run `make test`, and/or check builds.sr.ht to ensure things are working.
+# 1. Update versions in tools/get-deps.fnl and run `make check-deps`.
 # 2. Ensure lua documentation is up to date with `make check-docs`.
 #    (occasionally, lua devs fix typos or change wording of their reference)
 # 3. Remove "-dev" suffix in version src/fennel-ls/utils.fnl, and in :since fields in src/fennel-ls/lint.fnl
diff --git a/docs/packaging.md b/docs/packaging.md
index 3a63fa7..30d96b0 100644
--- a/docs/packaging.md
+++ b/docs/packaging.md
@@ -16,35 +16,37 @@ The content of these websites is available under the MIT license, so there isn't
 any licensing issue.
 
 I understand if you want to build from source instead of relying on the output.
-You can rebuild these by running `make rm-docs` to remove the docs, and
-`make docs` to regenerate these files. However, this requires internet access.
+You can rebuild these by removing the generated docs and regenerating them.
+However, this requires internet access.
 ```sh
-$ make rm-docs
+$ rm -rf src/fennel-ls/docs/generated/
 $ make docs
 ```
 
 ## Vendored Dependencies
-The vendored dependencies are very easy to solve. You delete the dependency
-files by running `make rm-deps`.
-```sh
-$ make rm-deps
-rm -rf fennel deps/
-$
-```
-Once these files are removed, you can safely use `make` to build the program.
-```sh
-# Not shown here: install fennel and lua and make and lua-dkjson
+The vendored dependencies are very easy to solve:
 
-# building
-make
+When the `VENDOR` flag is set to `false`, the build process will use
+system-installed versions of fennel to build, and the built program will
+search for its dependencies dynamically using lua's path system,
+instead of statically including the vendored dependencies.
 
-# testing (only works if faith and penlight and dkjson is installed)
-make test
+```sh
+# Install system dependencies first
+# You need: fennel, lua, lua-dkjson, make
+
+# Optional: remove the vendored code from the repo
+rm fennel deps/ -r
+
+# Build with system dependencies
+make VENDOR=false
+
+# Testing with system dependencies (also requires faith and penlight)
+make test VENDOR=false
 ```
 
 # Dependencies Overview
-Things marked with (vendored) are from the `deps/` folder, or from your
-environment if you've built a clean one.
+Things marked with (vendored) are vendored unless `VENDOR=false` is set.
 
 * Runtime Dependencies:
   * Lua
@@ -58,5 +60,18 @@ environment if you've built a clean one.
   * Faith (vendored)
   * Penlight (vendored)
 
-The specific versions of vendored packagens can be found in the
+The specific versions of vendored dependencies can be found in the
 [vendoring script](../tools/get-deps.fnl).
+
+## Verifying Reproducibility
+
+The Makefile provides targets to verify that the vendored dependencies and
+generated docs match what the build scripts produce:
+
+```sh
+# Check that deps are reproducible
+make check-deps
+
+# Check that generated docs are reproducible
+make check-docs
+```
diff --git a/tools/get-deps.fnl b/tools/get-deps.fnl
index c2bd7c1..e6a15a5 100644
--- a/tools/get-deps.fnl
+++ b/tools/get-deps.fnl
@@ -1,11 +1,11 @@
 (local {: sh} (require :tools.util))
 
-(fn git-clone [location url tag]
-  (if tag
-    (sh :git :clone :-c :advice.detachedHead=false :--depth=1 :--branch tag url location)
+(fn git-clone [location url ?tag]
+  (if ?tag
+    (sh :git :clone :-c :advice.detachedHead=false :--depth=1 :--branch ?tag url location)
     (sh :git :clone :-c :advice.detachedHead=false :--depth=1 url location)))
 
-;; TODO: currently you have to run make clean after changing any of these
+;; Vendored Dependency Versions
 (local fennel-version "1.5.3")
 (local faith-version "0.2.0")
 (local penlight-version "1.14.0")
@@ -16,6 +16,7 @@
 
 
 (fn get-fennel []
+  "downloads and builds fennel"
   (sh :mkdir :-p "build/")
   (when (not (io.open "build/fennel/fennel"))
     (git-clone "build/fennel"
@@ -24,23 +25,26 @@
     (sh :make :-C "build/fennel")))
 
 (fn get-faith []
+  "downloads faith"
   (when (not (io.open "build/faith/faith.fnl"))
     (git-clone "build/faith" "https://git.sr.ht/~technomancy/faith" faith-version)))
 
 ;; we clone all of penlight, but only stringio.lua will be installed
 (fn get-penlight-stringio []
+  "downloads penlight"
   (when (not (io.open "build/penlight/lua/pl/stringio.lua"))
     (git-clone "build/penlight" "https://github.com/lunarmodules/Penlight" penlight-version)))
 
 ;; get dkjson
 (fn get-dkjson []
+  "downloads and verifies dkjson"
   (when (not (io.open "build/dkjson.lua"))
     (sh :curl (.. "http://dkolf.de/dkjson-lua/dkjson-" dkjson-version ".lua") [:>] "build/dkjson.lua")
     (assert (sh :echo dkjson-md5sum [:|] :md5sum "--check" "--status"))
     (assert (sh :echo dkjson-sha1sum [:|] :sha1sum "--check" "--status"))))
 
-(fn install []
-  ;; installing just means copying to the "deps" folder
+(fn prepare-deps []
+  ;; "preparing" dependencies just means copying to the "deps" folder
   (sh :mkdir :-p "deps/")
   (sh :cp "build/fennel/fennel" ".")
   (sh :cp "build/fennel/fennel.lua" "deps/")
@@ -55,10 +59,10 @@
   (get-faith)
   (get-penlight-stringio)
   (get-dkjson)
-  (install))
+  (prepare-deps))
 
 {: get-fennel
  : get-faith
  : get-penlight-stringio
  : get-dkjson
- : install}
+ : prepare-deps}