Update project documentation for Package.juvix (#86)

This PR updates the Juvix project setup documentation to describe support for Package.juvix. As part of anoma/juvix#2487 --------- Co-authored-by: Jonathan Cubides <[email protected]>
anoma · Nov 17, 2023 · 7e684c5 · 7e684c5
1 parent 5729fce
commit 7e684c5
Show file tree

Hide file tree

Showing 30 changed files with 195 additions and 145 deletions.
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -28,7 +28,7 @@ repos:
     hooks:
       - id: prettier
         types_or: [css, javascript, yaml, toml]
-        exclude: docs/juvix-packages.md|docs/juvix.lock.yaml
+        exclude: .*/juvix-packages.md|.*/juvix.lock.yaml
 
   - repo: local
     hooks:

diff --git a/VERSION b/VERSION
@@ -1 +1 @@
-0.5.3
+0.5.4
diff --git a/docs/Package.juvix b/docs/Package.juvix
@@ -0,0 +1,5 @@
+module Package;
+
+import PackageDescription.V1 open;
+
+package : Package := defaultPackage {name := "juvix-docs"};
diff --git a/docs/blog/posts/geb-backend/Package.juvix b/docs/blog/posts/geb-backend/Package.juvix
@@ -0,0 +1,10 @@
+module Package;
+
+import PackageDescription.V1 open;
+
+package : Package := defaultPackage
+  { dependencies := [
+  github "anoma" "juvix-stdlib" "f68b0614ad695eaa13ead42f3466e0a78219f826"
+  ]
+  }
+;
diff --git a/docs/blog/posts/geb-backend/juvix.lock.yaml b/docs/blog/posts/geb-backend/juvix.lock.yaml
@@ -0,0 +1,9 @@
+# This file was autogenerated by Juvix version 0.5.3.
+# Do not edit this file manually.
+
+dependencies:
+  - git:
+      name: anoma_juvix-stdlib
+      ref: f68b0614ad695eaa13ead42f3466e0a78219f826
+      url: https://github.com/anoma/juvix-stdlib
+    dependencies: []
diff --git a/docs/blog/posts/geb-backend/juvix.yaml b/docs/blog/posts/geb-backend/juvix.yaml
diff --git a/docs/blog/posts/strictly-positive-data-types/Package.juvix b/docs/blog/posts/strictly-positive-data-types/Package.juvix
@@ -0,0 +1,10 @@
+module Package;
+
+import PackageDescription.V1 open;
+
+package : Package := defaultPackage
+  { dependencies := [
+  github "anoma" "juvix-stdlib" "f68b0614ad695eaa13ead42f3466e0a78219f826"
+  ]
+  }
+;
diff --git a/docs/blog/posts/strictly-positive-data-types/juvix.lock.yaml b/docs/blog/posts/strictly-positive-data-types/juvix.lock.yaml
@@ -0,0 +1,9 @@
+# This file was autogenerated by Juvix version 0.5.3.
+# Do not edit this file manually.
+
+dependencies:
+  - git:
+      name: anoma_juvix-stdlib
+      ref: f68b0614ad695eaa13ead42f3466e0a78219f826
+      url: https://github.com/anoma/juvix-stdlib
+    dependencies: []
diff --git a/docs/blog/posts/strictly-positive-data-types/juvix.yaml b/docs/blog/posts/strictly-positive-data-types/juvix.yaml
diff --git a/docs/blog/posts/vampir-circuits/Package.juvix b/docs/blog/posts/vampir-circuits/Package.juvix
@@ -0,0 +1,5 @@
+module Package;
+
+import PackageDescription.V1 open;
+
+package : Package := defaultPackage;
diff --git a/docs/blog/posts/vampir-circuits/juvix.yaml b/docs/blog/posts/vampir-circuits/juvix.yaml
diff --git a/docs/howto/compilation/CLI.yaml b/docs/howto/compilation/CLI.yaml
diff --git a/docs/howto/compilation/Package.juvix b/docs/howto/compilation/Package.juvix
@@ -0,0 +1,11 @@
+module Package;
+
+import Stdlib.Prelude open;
+import PackageDescription.V1 open;
+
+package : Package :=
+  defaultPackage
+    {name := "HelloWorld";
+     version := mkVersion 0 1 0;
+     dependencies := [path ".juvix-build/stdlib"];
+     main := just "HelloWorld.juvix"};
diff --git a/docs/howto/compilation/juvix.yaml b/docs/howto/compilation/juvix.yaml
diff --git a/docs/howto/project.md b/docs/howto/project.md
@@ -7,36 +7,41 @@ search:
 
 # How to setup a Juvix project
 
-A _juvix project_ is a collection of juvix modules plus some extra metadata
-gathered in a `juvix.yaml` file. The most convenient way to create a juvix
+A _Juvix project_ is a collection of Juvix modules plus some extra metadata
+gathered in a `Package.juvix` file. The most convenient way to create a Juvix
 project is to run the command:
 
 ```shell
 --8<------ "docs/howto/project/CLI.yaml:init"
 ```
 
-## Juvix YAML file
+## Package.juvix file
 
-A project is rooted in a directory. The root is set by creating a `juvix.yaml`,
-which contains the following fields, no order is required:
+A project is rooted in a directory. The root is set by creating a `Package.juvix`. The simplest `Package.juvix` file, which uses the default configuration, is:
 
-- `name`
-- `version`
-- `dependencies`
-- `main`
+```juvix
+--8<------ "docs/howto/project/Package.juvix:Package"
+```
+
+You can override the default options by passing arguments to `defaultPackage`:
+
+```juvix
+--8<------ "docs/howto/project/ex1/Package.juvix:Example"
+```
+
+You can check the documentation of the `Package` type or the `defaultPackage` function by using the go-to-definition feature in your IDE.
 
-The fields are explained below.
+The arguments are explained below.
 
 - **name**: This is the name assigned to the project. The name must not be empty
   and cannot exceed 100 characters. Lower case letters, digits and hyphen `-`
   are acceptable characters. The first letter must not be a hyphen.
   Summarizing, it must match the following regexp: `[a-z0-9][a-z0-9-]{0,99}`.
 - **version** (_optional_): The version of the project. It must follow the
-  [SemVer](https://semver.org/) specification. If the version is missed then it
-  will be assumed to be _0.0.0_.
+  [SemVer](https://semver.org/) specification. If unspecified, the default version is "0.0.0".
 - **main** (_optional_): The main module of the project used as entry point.
 - **dependencies** (_optional_): The dependencies of the project is given as a
-  list. See below for more information.
+  list. See below for more information. If unspecified, the default is `defaultStdlib`.
 
 !!! info "Note"
 
@@ -47,71 +52,61 @@ The fields are explained below.
       1. Modules in a hidden (or hanging from a hidden) directory are not part of the
          project. E.g., if the root of a project is `dir`, then the module
          `dir/.d/Lib.juvix` does not belong to the project rooted in `dir`.
-      1. A `juvix.yaml` file shadows other `juvix.yaml` files in parent
+      1. A `Package.juvix` file shadows other `Package.juvix` files in parent
          directories. E.g. if the root of a project is `dir` and the files
-         `dir/juvix.yaml` and `dir/nested/juvix.yaml` exist, then the module
+         `dir/Package.juvix` and `dir/nested/Package.juvix` exist, then the module
          `dir/nested/Lib.juvix` would belong to the project in `dir/nested`.
 
 !!! info "Note"
 
-      Any Juvix module outside of a project is considered a _standalone module_ and lives in its own (global) project. In other words, there is no need to create a `juvix.yaml` file for a standalone module.
+      Any Juvix module outside of a project is considered a _standalone module_ and lives in its own (global) project. In other words, there is no need to create a `Package.juvix` file for a standalone module.
 
 ## Package dependencies
 
-In order to specify the list of dependencies for a package, the field
-`dependencies` has been added to the `juvix.yaml`. The `dependencies` field is a
-list of directories (relative or absolute) or git dependencies. If the
-dependency is a directory then its location must contain a `juvix.yaml` file. As
-expected, if we add a package to the list of dependencies, we will be able to
-access its modules through import statements. External dependencies are
-supported through git dependencies.
-
-By default, the compiler include the standard library as a dependency, and
-therefore a user can use it including the following line in the `juvix.yaml`
-
-```yaml
-# -- juvix.yaml
-dependencies:
-  - .juvix-build/stdlib/
-name: juvix-docs
-version: 0.0.0
-```
+In `Package.juvix`, the `Package` type includes a dependencies field, which lists the other Juvix packages required by the project, with each dependency represented as an element of the `Dependency` type.
+
+Your project's code can use modules from dependent packages via standard Juvix `import` statements.
 
-### External dependencies
-
-To use external dependencies, it is required to have `git` installed. You can
-add a git block to the dependencies list:
-
-```yaml
-name: HelloWorld
-main: HelloWorld.juvix
-dependencies:
-  - .juvix-build/stdlib
-  - git:
-      url: https://my.git.repo
-      name: myGitRepo
-      ref: main
-version: 0.1.0
+There are three types of dependencies, all illustrated in the following snippet:
+
+```juvix
+--8<------ "docs/howto/project/ex2/Package.juvix:Dependencies"
 ```
 
-Git block required fields:
+### Git Dependencies
+
+A `git` dependency is a Juvix package located at the root of an external git
+repository. You can specify such a dependency in two ways:
 
-- `url`: The URL of the git repository
+1. By using the `git` constructor of the `Dependency` type, you can declare the dependency by providing its name (used to name the directory where the repository is cloned), the git repository URL, and the specific reference (like a version tag or branch). For example:
 
-- `ref`: The git reference that should be checked out
+   ```
+   git "juvix-containers" "https://github.com/anoma/juvix-containers" "v0.7.1"
+   ```
+
+2. By using the `github` function, which is a convenient method for packages hosted on GitHub. This function requires the GitHub organization name, the repository name, and the reference you're targeting. For example:
+
+   ```
+   github "anoma" "juvix-containers" "v0.7.1"
+   ```
 
 !!! info Inline end "Note"
 
       The values of the `name` fields must be unique among the git blocks in the dependencies list.
 
-- `name`: The name for the dependency. This is used to name the
-  directory of the
-  clone, it is required. Perhaps we could come up with a way to automatically
-  name the clone directory. Current ideas are to somehow encode the URL / ref
-  combination or use a UUID. However, there's some value in having the clone
-  directory named in a friendly way.
+### Path Dependencies
+
+A `path` dependency is a Juvix package located on your local filesystem. You can refer to such dependencies using absolute or relative paths. For example:
+
+```
+path ".deps/a/juvix/package"
+```
+
+### The built-in Juvix standard library - `defaultStdlib`
+
+The Juvix standard library is included with the Juvix compiler, and you can depend on it by using the `defaultStdlib` constructor.
 
-#### Behaviour
+## Behaviour of Git dependencies
 
 When dependencies for a package are registered, at the beginning of the compiler
 pipeline, all remote dependencies are processed:
@@ -128,15 +123,15 @@ pipeline, all remote dependencies are processed:
 
 !!! info "Lock file"
 
-      * A lock file is generated in the same directory as for `juvix.yaml`. This file is used to
+      * A lock file, juvix.lock.yaml is generated in the same directory as `Package.juvix`. This file is used to
         determine if any dependency needs to be updated. If the `ref` in the
         lock file does not match the `ref` in the package file, it is considered out of date.
 
 <!-- Add more about the new `juvix dependencies` -->
 
 #### Fixing errors
 
-- Missing fields in the Git dependency block are YAML parse errors
+- Juvix parse or typechecker errors will be reported by the Juvix compiler.
 - Duplicate `name` values in the dependencies list is an error thrown when the package file is processed
 - The `ref` does not exist in the clone or the clone directory is otherwise
   corrupt. An error with a suggestion to `juvix clean` is given. The package

diff --git a/docs/howto/project/Package.juvix b/docs/howto/project/Package.juvix
@@ -0,0 +1,7 @@
+--8<-- [start:Package]
+module Package;
+
+import PackageDescription.V1 open;
+
+package : Package := defaultPackage;
+--8<-- [end:Package]
diff --git a/docs/howto/project/ex1/Package.juvix b/docs/howto/project/ex1/Package.juvix
@@ -0,0 +1,16 @@
+module Package;
+
+import Stdlib.Prelude open;
+import PackageDescription.V1 open;
+
+--8<-- [start:Example]
+package : Package :=
+  defaultPackage
+    {name := "my-package";
+     version := mkVersion 0 1 0;
+     dependencies := [ defaultStdlib
+                     ; github "anoma" "juvix-containers" "v0.7.1"
+                     ];
+     main := just "Main.juvix"
+    };
+--8<-- [end:Example]
diff --git a/docs/howto/project/ex2/Package.juvix b/docs/howto/project/ex2/Package.juvix
@@ -0,0 +1,17 @@
+module Package;
+
+import Stdlib.Prelude open;
+import PackageDescription.V1 open;
+
+--8<-- [start:Dependencies]
+package : Package :=
+  defaultPackage
+    {name := "my-package";
+     version := mkVersion 0 1 0;
+     dependencies := [ defaultStdlib
+                     ; github "anoma" "juvix-containers" "v0.7.1"
+                     ; git "my-dependency" "https://my-git-repo-url" "my-git-ref"
+                     ; path "a/path/to/a/juvix/package"
+                     ]
+    };
+--8<-- [end:Dependencies]
diff --git a/docs/index/IntentExample.juvix b/docs/index/IntentExample.juvix
@@ -1,5 +1,6 @@
 module IntentExample;
 
+{-
 import Simulator open;
 import Simulator.Resource open using {mkResource as mkResource'};
 import Apps.TwoPartyExchange.Asset open;
@@ -70,3 +71,4 @@ logicFunctions : Map LogicHash LogicFunction :=
   mkLogicFunctionMap
     ((AliceIntent.logicHash, AliceIntent.logicFunction) :: nil);
 --8<-- [end:logics]
+-}
diff --git a/docs/index/Package.juvix b/docs/index/Package.juvix
@@ -0,0 +1,11 @@
+module Package;
+
+import PackageDescription.V1 open;
+
+package : Package :=
+  defaultPackage
+    {name := "docs";
+     version := mkVersion 0 0 1;
+     dependencies := [ git "stdlib" "https://github.com/anoma/juvix-stdlib" "f68b0614ad695eaa13ead42f3466e0a78219f826"
+                     ; git "taiga-simulator" "https://github.com/anoma/taiga-simulator" "bcb9971b32aed93bdb1121182f41057d9625e0a9"
+                     ]};
diff --git a/docs/index/juvix.lock.yaml b/docs/index/juvix.lock.yaml
@@ -1,10 +1,10 @@
-# This file was autogenerated by Juvix version 0.5.2.
+# This file was autogenerated by Juvix version 0.5.3.
 # Do not edit this file manually.
 
 dependencies:
   - git:
       name: stdlib
-      ref: 8493ff47a0c2fad4542c8e75f5736060ae7da0a4
+      ref: f68b0614ad695eaa13ead42f3466e0a78219f826
       url: https://github.com/anoma/juvix-stdlib
     dependencies: []
   - git:

diff --git a/docs/index/juvix.yaml b/docs/index/juvix.yaml
diff --git a/docs/juvix-packages/Package.juvix b/docs/juvix-packages/Package.juvix
@@ -0,0 +1,12 @@
+module Package;
+
+import PackageDescription.V1 open;
+
+package : Package :=
+  defaultPackage
+    {dependencies := [ git "juvix-containers" "https://github.com/anoma/juvix-containers" "v0.7.1"
+                     ; git "test" "https://github.com/anoma/juvix-test" "v0.6.1"
+                     ; git "quickcheck" "https://github.com/anoma/juvix-quickcheck" "v0.8.0"
+                     ; git "stdlib" "https://github.com/anoma/juvix-stdlib" "86f9e82c34395f3e0447c58566bc92347603ebd3"
+                     ; git "taiga-simulator" "https://github.com/anoma/taiga-simulator" "fd0ac317735bb2752e40f1fa0dd06b2de432bfd5"
+                     ]};