Clean up documentation
This commit is contained in:
parent
55a1efa08f
commit
83d41ef778
16 changed files with 146 additions and 98 deletions
2
docs/README
Normal file
2
docs/README
Normal file
|
|
@ -0,0 +1,2 @@
|
|||
To generate the documentation, run:
|
||||
`docread; npx antora generate antora-playbook.yml`.
|
||||
|
|
@ -60,7 +60,7 @@
|
|||
|
||||
(define out-file (open-output-file out-path))
|
||||
; Print out the comments
|
||||
(fprintf out-file "= `~S`\n" (car contents))
|
||||
(fprintf out-file "= `~S`\n\n" (car contents))
|
||||
(for-each (lambda (l) (fprintf out-file "~A\n" l)) lib-comments)
|
||||
(fprintf out-file "\n:toc:\n\n")
|
||||
(for-each (lambda (i)
|
||||
|
|
|
|||
|
|
@ -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[]
|
||||
|
|
|
|||
|
|
@ -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
35
docs/modules/ROOT/pages/go.adoc
Normal 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.
|
||||
----
|
||||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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!") })
|
||||
----
|
||||
|
|
@ -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)))
|
||||
----
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue