From a1e3304da6f7f5026c32bf589b8e3effd5b3f177 Mon Sep 17 00:00:00 2001
From: Kristian Larsson <kristian@spritelink.net>
Date: Tue, 10 Sep 2024 23:11:22 +0200
Subject: [PATCH] Guide: describe pkg dependencies

---
 docs/acton-by-example/src/SUMMARY.md          |  3 +-
 .../src/pkg/add_dependency.md                 | 34 +++++++++++++++++++
 .../src/pkg/fetch_dependencies.md             |  6 +++-
 .../src/pkg/local_dependencies.md             | 23 +++++++++++++
 .../src/pkg/remove_dependency.md              |  6 ++++
 docs/acton-by-example/src/zig_dependencies.md |  6 ++++
 6 files changed, 76 insertions(+), 2 deletions(-)
 create mode 100644 docs/acton-by-example/src/pkg/local_dependencies.md

diff --git a/docs/acton-by-example/src/SUMMARY.md b/docs/acton-by-example/src/SUMMARY.md
index d741d01d5..54414de8e 100644
--- a/docs/acton-by-example/src/SUMMARY.md
+++ b/docs/acton-by-example/src/SUMMARY.md
@@ -64,7 +64,8 @@
 - [Package Management](package_management.md)
   - [Dependencies](pkg/dependencies.md)
     - [Add Dependency](pkg/add_dependency.md)
+    - [Local Dependencies](pkg/local_dependencies.md)
     - [Remove Dependency](pkg/remove_dependency.md)
-    - [Fetch Dependencies](pkg/fetch_dependencies.md)
+    - [Fetch Deps / Airplane mode](pkg/fetch_dependencies.md)
   - [C / C++ / Zig dependencies](zig_dependencies.md)
 - [Run Time System](rts.md)
diff --git a/docs/acton-by-example/src/pkg/add_dependency.md b/docs/acton-by-example/src/pkg/add_dependency.md
index 3a5415a9c..fd143b123 100644
--- a/docs/acton-by-example/src/pkg/add_dependency.md
+++ b/docs/acton-by-example/src/pkg/add_dependency.md
@@ -1 +1,35 @@
 # Add Dependency
+
+Add a dependency to your project by using `acton pkg add` and providing the URL to the project and a local reference name.
+
+In this case we add the example `foo` package as a dependency.
+```console
+acton pkg add https://github.com/actonlang/foo/archive/refs/heads/main.zip foo
+```
+
+This will fetch the dependency and add it to the `build.act.json` file of your local project, resulting in something like:
+```json
+{
+    "dependencies": {
+        "foo": {
+            "url": "https://github.com/actonlang/foo/archive/refs/heads/main.zip",
+            "hash": "1220cd47344f8a1e7fe86741c7b0257a63567b4c17ad583bddf690eedd672032abdd"
+        }
+    },
+    "zig_dependencies": {}
+}
+```
+
+```admonish
+It is possible to edit `build.act.json` by hand, but adding dependencies, which requires filling in the 'hash' field requires computing the hash which is somewhat tricky.
+```
+
+The `foo` package provides a single `foo` module with a `foo` function (that appropriately returns `foo`). We can now access it from our main actor:
+
+```python
+import foo
+
+actor main(env):
+    print(foo.foo())
+    env.exit(0)
+```
diff --git a/docs/acton-by-example/src/pkg/fetch_dependencies.md b/docs/acton-by-example/src/pkg/fetch_dependencies.md
index 648bdb290..fac813ea7 100644
--- a/docs/acton-by-example/src/pkg/fetch_dependencies.md
+++ b/docs/acton-by-example/src/pkg/fetch_dependencies.md
@@ -1 +1,5 @@
-# Fetch Dependencies
+# Fetch Dependencies / Enable Airplane Mode
+
+You can fetch all the dependencies of a project by using `acton fetch`. It will download the dependencies specified in `build.act.json` to the cache.
+
+`acton fetch` enables you to work offline or in **airplane mode**.
diff --git a/docs/acton-by-example/src/pkg/local_dependencies.md b/docs/acton-by-example/src/pkg/local_dependencies.md
new file mode 100644
index 000000000..87d518d94
--- /dev/null
+++ b/docs/acton-by-example/src/pkg/local_dependencies.md
@@ -0,0 +1,23 @@
+# Local Dependencies
+
+It is possible to use dependencies available via a local file system path by setting the `path` attribute. Edit `build.act.json` and add or modify an existing dependency. Set the `path` attribute to a relative path on the local file system, e.g.:
+
+```json
+{
+    "dependencies": {
+        "foo": {
+            "url": "https://github.com/actonlang/foo/archive/refs/heads/main.zip",
+            "hash": "1220cd47344f8a1e7fe86741c7b0257a63567b4c17ad583bddf690eedd672032abdd",
+            "path": "../foo"
+        },
+        "local_lib": {
+            "path": "deps/local_lib"
+        }
+    },
+    "zig_dependencies": {}
+}
+```
+
+```admonish
+Setting a local `path` will take priority over a remote `url`. This can be useful to fork a library and make local modifications to it before submitting them back upstream.
+```
diff --git a/docs/acton-by-example/src/pkg/remove_dependency.md b/docs/acton-by-example/src/pkg/remove_dependency.md
index 7ce566629..c4079319a 100644
--- a/docs/acton-by-example/src/pkg/remove_dependency.md
+++ b/docs/acton-by-example/src/pkg/remove_dependency.md
@@ -1 +1,7 @@
 # Remove Dependency
+
+You can remove a dependency from your project with `acton pkg remove`:
+
+```console
+acton pkg remove foo
+```
diff --git a/docs/acton-by-example/src/zig_dependencies.md b/docs/acton-by-example/src/zig_dependencies.md
index 3234c391c..78fdfb11b 100644
--- a/docs/acton-by-example/src/zig_dependencies.md
+++ b/docs/acton-by-example/src/zig_dependencies.md
@@ -1 +1,7 @@
 # C / C++ / Zig dependencies
+
+Much like dependencies on other Acton packages, an Acton project can depend on a Zig package which could be a C / C++ or Zig library, as long as it has a `build.zig` file.
+
+- `acton zig-pkg add URL NAME --artifact X --artifact`
+  - list the libraries you want to link with as artifacts
+- `acton zig-pkg remove NAME`