puck/zilch
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Clean up documentation

Browse source
This commit is contained in:
puck 2024-10-04 01:21:07 +00:00
parent 55a1efa08f
commit 83d41ef778
16 changed files with 146 additions and 98 deletions
Download patch file Download diff file Expand all files Collapse all files

5
docs/modules/ROOT/nav.adoc
View file

@ -1,5 +1,5 @@
* xref:index.adoc[]
* xref:nixexpr.adoc[]
* xref:go.adoc[]
* xref:zexp.adoc[]
* ++(zilch)++
@ -27,6 +27,3 @@
*** xref:generated:zilch.nix.drv.adoc[++(zilch nix drv)++]
*** xref:generated:zilch.nix.hash.adoc[++(zilch nix hash)++]
*** xref:generated:zilch.nix.path.adoc[++(zilch nix path)++]
* xref:architecture.adoc[]

11
docs/modules/ROOT/pages/architecture.adoc
View file

@ -1,11 +0,0 @@
= Architecture
`(zilch nix binproto)` contains an implementation of the binary protocol used both
to talk to the daemon and to build NAR files.
On top of that is `(zilch nix daemon)`, which implements a version (which?) of
the Nix worker protocol.
`(zilch nix drv)` allows reading and writing .drv objects.
`(zilch nix path)` contains the helpers for building store paths of various types.

35
docs/modules/ROOT/pages/go.adoc Normal file
View file

@ -0,0 +1,35 @@
= Go
Currently, the primary binary produced by the `zilch` repository is a tool to
generate content-addressed derivations from a Go project, called `zilch-cli-go`.
It requires the `ca-derivations` and `impure-derivations` experimental features
to be enabled on the Nix daemon, and a Nix daemon to be available at the
default store path. It also requires the daemon to be able to run
`x86_64-linux` derivations, right now.
Once run, it will use Zilch to build a series of derivations, and output a
`.drv` for each executable package in the module.
The help page:
[source]
----
Usage: zilch-cli-go [OPTION] [PACKAGE...]
Process the given module (or the current directory, if unspecified) and
output derivations for each package given on the command line (or all
executables in the module, if unspecified)
-h, --help Print this help message.
-b, --build Build the store paths, rather than show their
derivations.
-L, --print-build-logs Print derivation logs as they come in.
-m, --module-dir DIR The directory to use as root module.
-r, --replace DIR Replace the module specified by the go.mod
with this source directory, rather than using
the upstream module. Can be specified more
than once.
--debug Crash on the first error, rather than
continuing with the next package.
----

2
docs/modules/ROOT/pages/index.adoc
View file

@ -15,7 +15,7 @@ Features:
== Current work
Current effort in Zilch is working on making "incremental", bitesize,
derivations to work. This is currently being implemented for Go.
derivations to work. This is xref:go.adoc[currently being implemented for Go].
== Contributing

41
docs/modules/ROOT/pages/nixexpr.adoc
View file

@ -1,41 +0,0 @@
= Nix expression support
When `(nix reader)` is imported, it is possible to execute Nix code inline with
Scheme code. Simply wrap your Nix code in curly brackets:
[,scheme]
----
(write
(string-append
"Hello, Nix version"
{ builtins.nixVersion }))
----
The following values can be translated:
|===
| Nix | Scheme | Notes
| string | string | (Loses string context.)
| integer | number |
| float | number |
| boolean | boolean |
| lambda | procedure | (with single argument)
| list | vector or list | Depends on the status of `\*translate-list-as-vector*`
| attrset | alist |
| builtin | procedure |
| external value | symbol, other unknown objects |
|===
If a value in Nix is preceded with a comma, it is unquoted, similar to
`(unquote)` in a Scheme quasiquotation. If prefixed with a single quote, it is
`(quote)`-d.
[,scheme]
----
(define
(test-append foo)
(string-append "Hello, " foo))
(write
{ ,test-append "world!") })
----

25
docs/modules/ROOT/pages/zexp.adoc
View file

@ -1,11 +1,15 @@
= zexps
zexps, similar to g-expressions in Guix, are a way to generate
S-expressions that are taggged with store paths. But that's where
the similarity ends.
S-expressions that are tagged with store paths. The syntax in Zilch is inspired
by it, but has been developed separately.
A zexp is used similarly to a ``quasiquote``d value in Scheme, but has an extra type
of unquoting, called `zexp-unquote`, which unquotes a value such as a `++<store-path>++`
or another `zexp`.
To create a zexp, you can use either the full syntax, or the reader macro:
Each `zexp` keeps track of the derivation outputs and store files it depends on,
similarly to how string context works in Nix:
[,scheme]
----
@ -14,15 +18,14 @@ To create a zexp, you can use either the full syntax, or the reader macro:
(zexp (foo bar (zexp-unquote baz)))
----
`(zexp-unquote VAL)` returns the value that the zexp (or any compatible record)
contains, while gathering the `zexp-unquote`d values used.
Like quasiquotation, zexps can use `unquote`, including ``zexp-unquote``d values
inside the ``unquote``d code. ``unquote``d code is evaluated when the `zexp` is evaluated.
When a `zexp-unquote` (or its reader syntax, `#$`) is encountered, the value
contained in the `zexp` (or compatible object) is used as-is, with no
evaluation. It is possible to mix and match `zexp-unquote` with `unquote`,
allowing building e.g. dynamic strings from zexps. `zexp-unquote` is always
evaluated before `unquote` is.
[,scheme]
----
(define world #~,(begin (write "hello") "world"))
(define hello #~("hello" ,(string-append "very " "cute") #$world))
; When hello is used as zexp, it will also write "hello" to the output port.
(define world ...)
(define hello #~("hello" ,(string-append "very " "cute" #$world)))
----