120 lines
3.7 KiB
Markdown
120 lines
3.7 KiB
Markdown
# typst-nix -- typst compilation in a nix derivation
|
|
|
|
Before you use this flake, please go check out [Typix](https://loqusion.github.io/typix/)
|
|
-- a more mature project that does basically the same thing. I am building this package,
|
|
because I believe Typix to be not abstract enough, while lacking the ability to
|
|
automatically resolve all the dependencies.
|
|
|
|
## How to use
|
|
|
|
1. *Add to your flake inputs*:
|
|
```nix
|
|
inputs.typst-nix.url = "https://git.dzuchun.ing/dzu/typst-nix.git";
|
|
```
|
|
|
|
2. *Run `typst-lock` against your typst document*.
|
|
|
|
This flake exposes it at `apps.<system>.default`, or you may do
|
|
```sh
|
|
cargo install --git https://git.dzuchun.ing/dzu/typst-nix.git
|
|
```
|
|
|
|
Help text:
|
|
```
|
|
Statically resolve and lock `@preview` packages for a Typst project
|
|
|
|
Usage: typst-lock [OPTIONS] [ENTRYPOINT]
|
|
|
|
Arguments:
|
|
[ENTRYPOINT]
|
|
`.typ` file to start with, relative to `<ROOT>`
|
|
|
|
Defaults to `main.typ`
|
|
|
|
Options:
|
|
--root <ROOT>
|
|
Project root
|
|
|
|
Defaults to CWD
|
|
|
|
--lockfile <LOCKFILE>
|
|
Path of the lockfile to write.
|
|
|
|
Defaults to `<ROOT>/typst.lock`
|
|
|
|
--force
|
|
Even if the lockfile is present at the output location, ignore it and resolve everything from scratch
|
|
|
|
--prefetch-url-path <PREFETCH_URL_PATH>
|
|
Path to the `nix-prefetch-url` binary
|
|
|
|
Defaults to whatever is first in `PATH`
|
|
|
|
-h, --help
|
|
Print help (see a summary with '-h')
|
|
|
|
-V, --version
|
|
Print version
|
|
```
|
|
|
|
This tool produces a special file at `typst.lock` (or whatever you pass into
|
|
`--lockfile`), that you can commit -- this is a direct Typst equivalent to `flake.lock`
|
|
and `Cargo.lock`.
|
|
|
|
3. *Call into the nix function*.
|
|
|
|
The main function is located at `.lib.compileTypst`. You may use aliases at
|
|
`.lib.<system>.compileTypst`, if you don't care where `pkgs` come from.
|
|
|
|
Signature:
|
|
```
|
|
compileTypst :: {
|
|
pkgs,
|
|
# package to take the typst binary from
|
|
typstPackage ? pkgs.typst,
|
|
# possible values: pdf, png, svg, html, bundle
|
|
format ? "pdf",
|
|
# root of the typst project
|
|
rootDir,
|
|
# main typst file
|
|
entrypoint ? "${rootDir}/main.typ",
|
|
# lockfile, representing the dependencies
|
|
lockfile ? "${rootDir}/typst.lock",
|
|
# exposed in Typst as `sys.inputs`. must be an attrset of strings
|
|
inputs ? { },
|
|
# exposed in Typst as `sys.inputs`. must be an attrset of paths
|
|
inputFiles ? { },
|
|
# paths to fonts
|
|
fontPaths ? [ ],
|
|
# if set, Typst's own embedded fonts will be ignored
|
|
ignoreEmbeddedFonts ? false,
|
|
# UNIX timestamp exposed by datetime functions
|
|
creationTimestamp ? 0,
|
|
# pretty-format the output
|
|
pretty ? false,
|
|
pages ? null,
|
|
# see typst c --help
|
|
noPdfTags ? false,
|
|
# see typst c --help
|
|
ppi ? 144,
|
|
features ? [ ],
|
|
...
|
|
} -> Derivation
|
|
```
|
|
|
|
Output of the produced derivation is your PDF or HTML respectively.
|
|
|
|
## Known limitations
|
|
|
|
- First version only supports packages from typst universe. There is a code in place to
|
|
support custom (incl. local) repositories, but this is deferred.
|
|
- Tool operates on the "fail open" strategy: non-existent or unresolvable packages are
|
|
skipped with a warning, while errors in your entrypoint are fatal.
|
|
- If the package traversal fails in any way, it will remain in the manifest, but without
|
|
its dependencies. You will also see an explicit message about this hard failure.
|
|
- Tool only understands `import`s and `include`s with literal string sources. This may or
|
|
may not be relaxed to "pure+local eval values" in the future.
|
|
- All the resolutions and downloads are naive and never retried. If one of the packages
|
|
you are sure to exist fails, please rerun.
|
|
- Power loss durability is not a goal. If you think that the lockfile is corrupted, just
|
|
regenerate it.
|