Merge pull request #1912 from actonlang/guide-pkg

Guide: describe pkg dependencies

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)

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)
+```

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**.

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.
+```

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
+```

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`