Improve docs
This commit is contained in:
parent
b10ff57b1e
commit
2f6e7c3078
3 changed files with 158 additions and 6 deletions
|
|
@ -190,10 +190,10 @@
|
||||||
RUNTIME_ARGS+=(--bind /foo /foo)
|
RUNTIME_ARGS+=(--bind /foo /foo)
|
||||||
fi
|
fi
|
||||||
${"''"}
|
${"''"}
|
||||||
|
```
|
||||||
|
|
||||||
If you create any resources in add-runtime that you want to automatically
|
If you create any resources in add-runtime that you want to automatically
|
||||||
clean up when the jail exits use [add-cleanup](#add-cleanup).
|
clean up when the jail exits use [add-cleanup](#add-cleanup).
|
||||||
```
|
|
||||||
'';
|
'';
|
||||||
__functor = _:
|
__functor = _:
|
||||||
runtime: state: state // { runtime = "${state.runtime}\n${runtime}\n"; }
|
runtime: state: state // { runtime = "${state.runtime}\n${runtime}\n"; }
|
||||||
|
|
|
||||||
|
|
@ -7,6 +7,16 @@
|
||||||
pkgs = import nixpkgs { system = "x86_64-linux"; };
|
pkgs = import nixpkgs { system = "x86_64-linux"; };
|
||||||
lib = pkgs.lib;
|
lib = pkgs.lib;
|
||||||
|
|
||||||
|
repo = rec {
|
||||||
|
rev = if self ? rev then self.rev else lib.warn "Repo is dirty, links will not work!" "???";
|
||||||
|
shortRev = lib.substring 0 8 rev;
|
||||||
|
urls = {
|
||||||
|
base = "https://git.sr.ht/~alexdavid/jail.nix";
|
||||||
|
commit = "https://git.sr.ht/~alexdavid/jail.nix/commit/${rev}";
|
||||||
|
file = file: lineNr: "https://git.sr.ht/~alexdavid/jail.nix/tree/${rev}${file}#L${toString lineNr}";
|
||||||
|
};
|
||||||
|
};
|
||||||
|
|
||||||
formatCombinatorDoc = name: combinatorObj: let
|
formatCombinatorDoc = name: combinatorObj: let
|
||||||
attrPos = builtins.unsafeGetAttrPos "__functor" combinatorObj;
|
attrPos = builtins.unsafeGetAttrPos "__functor" combinatorObj;
|
||||||
file = lib.removePrefix (toString ./..) attrPos.file;
|
file = lib.removePrefix (toString ./..) attrPos.file;
|
||||||
|
|
@ -14,7 +24,7 @@
|
||||||
## ${name}
|
## ${name}
|
||||||
**${name} :: ${combinatorObj.sig}**
|
**${name} :: ${combinatorObj.sig}**
|
||||||
|
|
||||||
${if self ? rev then "[Source](https://git.sr.ht/~alexdavid/jail.nix/tree/${self.rev}${file}#L${toString attrPos.line})" else ""}
|
[Source](${repo.urls.file file attrPos.line})
|
||||||
|
|
||||||
${combinatorObj.doc}
|
${combinatorObj.doc}
|
||||||
|
|
||||||
|
|
@ -32,21 +42,38 @@
|
||||||
(lib.filterAttrs (_: v: !(v ? deprecated && v.deprecated)))
|
(lib.filterAttrs (_: v: !(v ? deprecated && v.deprecated)))
|
||||||
(lib.mapAttrsToList formatCombinatorDoc)
|
(lib.mapAttrsToList formatCombinatorDoc)
|
||||||
(lib.concatStringsSep "\n\n")
|
(lib.concatStringsSep "\n\n")
|
||||||
(docs: "# Combinators\n\n${docs}")
|
(docs: ''
|
||||||
|
# Combinators
|
||||||
|
|
||||||
|
${docs}
|
||||||
|
'')
|
||||||
];
|
];
|
||||||
|
|
||||||
mkdocsSettings = {
|
mkdocsSettings = {
|
||||||
site_name = "jail-nix";
|
site_name = "jail-nix";
|
||||||
repo_url = "https://git.sr.ht/~alexdavid/jail.nix";
|
repo_url = repo.urls.base;
|
||||||
theme = {
|
theme = {
|
||||||
name = "readthedocs";
|
name = "readthedocs";
|
||||||
hljs_languages = [ "nix" ];
|
hljs_languages = [ "nix" ];
|
||||||
};
|
};
|
||||||
|
# Copyright is placed directly into the page within a <p> tag.
|
||||||
|
# Concatenating with </p><p> here is super janky, but good enough for
|
||||||
|
# now.
|
||||||
|
copyright = lib.concatStringsSep "</p><p>" [
|
||||||
|
''
|
||||||
|
Copyright © 2025 Alex David ///
|
||||||
|
<a rel="license" href="https://creativecommons.org/licenses/by-nc-sa/4.0/">CC BY-NC-SA 4.0</a>.
|
||||||
|
''
|
||||||
|
''
|
||||||
|
This documentation was generated from the <a href="${repo.urls.base}">jail.nix repo</a>,
|
||||||
|
commit <a href="${repo.urls.commit}"><code>${repo.shortRev}</code></a>.
|
||||||
|
''
|
||||||
|
];
|
||||||
};
|
};
|
||||||
in {
|
in {
|
||||||
packages.x86_64-linux.default = pkgs.runCommand "website" { buildInputs = [ pkgs.mkdocs ]; } ''
|
packages.x86_64-linux.default = pkgs.runCommand "website" { buildInputs = [ pkgs.mkdocs ]; } ''
|
||||||
mkdir -p docs
|
cp -r ${./static-docs} docs
|
||||||
cp ${../README.md} docs/index.md
|
chmod -R +w docs
|
||||||
echo ${lib.escapeShellArg combinatorDocs} > docs/combinators.md
|
echo ${lib.escapeShellArg combinatorDocs} > docs/combinators.md
|
||||||
echo ${lib.escapeShellArg (builtins.toJSON mkdocsSettings)} > mkdocs.yml
|
echo ${lib.escapeShellArg (builtins.toJSON mkdocsSettings)} > mkdocs.yml
|
||||||
mkdocs build
|
mkdocs build
|
||||||
|
|
|
||||||
125
website/static-docs/index.md
Normal file
125
website/static-docs/index.md
Normal file
|
|
@ -0,0 +1,125 @@
|
||||||
|
# Getting Started
|
||||||
|
|
||||||
|
## Installation
|
||||||
|
|
||||||
|
It is currently recommended to install jail.nix as a flake input to your
|
||||||
|
configuration:
|
||||||
|
|
||||||
|
```nix
|
||||||
|
# flake.nix
|
||||||
|
{
|
||||||
|
inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixos-24.11";
|
||||||
|
inputs.jail-nix.url = "sourcehut:~alexdavid/jail.nix";
|
||||||
|
outputs = { nixpkgs, jail-nix, ... }: {
|
||||||
|
# ...
|
||||||
|
};
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Initializing
|
||||||
|
|
||||||
|
The core functionality of jail.nix is a `jail` function that wraps derivations
|
||||||
|
in a bubblewrap jail. To set it up, you need to initialize the library with a
|
||||||
|
version of nixpkgs.
|
||||||
|
|
||||||
|
This is done by either calling `jail-nix.lib.init` for a basic setup, or
|
||||||
|
`jail-nix.lib.extend` for advanced configuration.
|
||||||
|
|
||||||
|
### Basic configuration
|
||||||
|
|
||||||
|
For a simple working `jail` function, call `jail-nix.lib.init` with an instantiated nixpkgs:
|
||||||
|
```nix
|
||||||
|
pkgs = import nixpkgs { system = "x86_64-linux"; };
|
||||||
|
jail = jail-nix.lib.init pkgs;
|
||||||
|
```
|
||||||
|
|
||||||
|
### Advanced configuration
|
||||||
|
|
||||||
|
You can set more options in the initialization with `jail-nix.lib.extend`.
|
||||||
|
|
||||||
|
You must pass in an instantiated nixpkgs attribute `pkgs`.
|
||||||
|
|
||||||
|
For example, the below snippet creates a `jail` function where `my-combinator`
|
||||||
|
is passed to jail definitions.
|
||||||
|
|
||||||
|
```nix
|
||||||
|
pkgs = import nixpkgs { system = "x86_64-linux"; };
|
||||||
|
|
||||||
|
jail = jail-nix.lib.extend {
|
||||||
|
inherit pkgs;
|
||||||
|
additionalCombinators = baseCombinators: with baseCombinators; [
|
||||||
|
my-combinator = compose [
|
||||||
|
(readonly "/foo")
|
||||||
|
(readonly "/bar")
|
||||||
|
];
|
||||||
|
];
|
||||||
|
};
|
||||||
|
|
||||||
|
jailed-hello = jail "jailed-hello" pkgs.hello (c: with c; [
|
||||||
|
my-combinator
|
||||||
|
]);
|
||||||
|
```
|
||||||
|
|
||||||
|
## Usage
|
||||||
|
|
||||||
|
Once you have an [initialized](#initializing) `jail` function, it takes the
|
||||||
|
following positional arguments:
|
||||||
|
|
||||||
|
* **name**: (String) - the nix store name of wrapper script that is generated.
|
||||||
|
* **executable to wrap**: (String or Derivation) - An entrypoint to jail, this can
|
||||||
|
be a derivation like `pkgs.hello`, or a string like
|
||||||
|
`"${pkgs.hello}/bin/hello"`. If a derivation is passed it will call
|
||||||
|
`nixpkgs.lib.getExe` on it to get the entrypoint.
|
||||||
|
* **combinators**: (Function returning a list of **Combinators**) - The third
|
||||||
|
argument allows you to control the permissions of the jail. By default, the
|
||||||
|
wrapped program runs with very few permissions and to get it to even work you
|
||||||
|
will need to define what you want it to have access to here. For convenience,
|
||||||
|
this is a function that passes all the available combinators.
|
||||||
|
|
||||||
|
## Examples
|
||||||
|
|
||||||
|
### Provide jail.nix as a module arg in a Nixos configuration:
|
||||||
|
|
||||||
|
It may be more ergonomic to provide the jail function as a module argument in
|
||||||
|
your Nixos configurations:
|
||||||
|
|
||||||
|
```nix
|
||||||
|
# flake.nix
|
||||||
|
{
|
||||||
|
inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixos-24.11";
|
||||||
|
inputs.jail-nix.url = "sourcehut:~alexdavid/jail.nix";
|
||||||
|
outputs = { nixpkgs, jail-nix, ... }: {
|
||||||
|
nixosConfigurations.my-nixos-host = nixpkgs.lib.nixosSystem {
|
||||||
|
system = "x86_64-linux";
|
||||||
|
modules = [
|
||||||
|
({ pkgs, ... }: { _module.args.jail = jail-nix.lib.init pkgs; })
|
||||||
|
|
||||||
|
# Now all modules have `jail` passed into them:
|
||||||
|
({ jail, ... }: {
|
||||||
|
environment.systemPackages = [
|
||||||
|
(jail "jailed-hello" pkgs.hello (c: []))
|
||||||
|
];
|
||||||
|
})
|
||||||
|
];
|
||||||
|
};
|
||||||
|
};
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Using jail.nix to jail a flake package
|
||||||
|
```nix
|
||||||
|
# flake.nix
|
||||||
|
{
|
||||||
|
inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixos-24.11";
|
||||||
|
inputs.jail-nix.url = "sourcehut:~alexdavid/jail.nix";
|
||||||
|
outputs = { nixpkgs, jail-nix, ... }: {
|
||||||
|
packages.x86_64-linux =
|
||||||
|
let
|
||||||
|
pkgs = import nixpkgs { system = "x86_64-linux"; };
|
||||||
|
jail = jail-nix.lib.init pkgs;
|
||||||
|
in {
|
||||||
|
my-jailed-package = jail "jailed-hello" pkgs.hello (c: []);
|
||||||
|
};
|
||||||
|
};
|
||||||
|
}
|
||||||
|
```
|
||||||
Loading…
Add table
Add a link
Reference in a new issue