mirror of
https://github.com/divnix/digga.git
synced 2024-10-05 19:17:59 +03:00
docs: add general docs (w/o library reference)
library reference expected to come as soon as flake-utils-plus has the corresponding implementation.
This commit is contained in:
David Arnold
Parthiv Seetharaman
parent
736b50eeb0
commit
fee8829dd7
27
.github/workflows/mdbook_docs.yml
vendored
Normal file
27
.github/workflows/mdbook_docs.yml
vendored
Normal file
@ -0,0 +1,27 @@
|
||||
name: Deploy Docs to GitHub Pages
|
||||
|
||||
on:
|
||||
push:
|
||||
branches:
|
||||
- main
|
||||
|
||||
jobs:
|
||||
deploy:
|
||||
runs-on: ubuntu-18.04
|
||||
steps:
|
||||
- uses: actions/checkout@v2
|
||||
|
||||
- name: Setup mdBook
|
||||
uses: peaceiris/actions-mdbook@v1
|
||||
with:
|
||||
mdbook-version: 'latest'
|
||||
|
||||
- run: mdbook build doc
|
||||
|
||||
- name: Deploy
|
||||
uses: peaceiris/actions-gh-pages@v3
|
||||
with:
|
||||
github_token: ${{ secrets.GITHUB_TOKEN }}
|
||||
publish_branch: gh-pages
|
||||
publish_dir: ./doc/book
|
||||
cname: digga.divnix.com
|
||||
82
README.md
82
README.md
@ -1,40 +1,86 @@
|
||||
[](https://app.bors.tech/repositories/33905)
|
||||
[][mit]
|
||||
[](https://nixos.org)
|
||||
[](https://matrix.to/#/#devos:nixos.org)
|
||||
|
||||
> #### ⚠ Advisory ⚠
|
||||
> DevOS requires the [flakes][flakes] feature available via an _experimental_
|
||||
> Digga requires the [flakes][flakes] feature available via an _experimental_
|
||||
> branch of [nix][nix]. Until nix 3.0 is released, this project
|
||||
> should be considered unstable, though quite usable as flakes have been
|
||||
> maturing _well_ [for a while](https://github.com/divnix/devos/tree/17713c22d07c54525c728c62060a0428b76dee3b).
|
||||
> maturing _well_ for a while.
|
||||
|
||||
|
||||
Digga is the underlying library implementation for the
|
||||
[DevOS template](https://github.com/divnix/devos). There is an API to create
|
||||
productive personal and professional flakes in a clean and organized manner.
|
||||
By using this library your creations will be part of a community-first sharing
|
||||
model.
|
||||
Digga — slangy german for "good friend" — is a flake utility library
|
||||
that helps you declaratively craft and manage all three layers of your system
|
||||
environment within a single [nix flakes][flakes] repository:
|
||||
|
||||
- development shells (via [`numtide/devshell`][devshell]),
|
||||
- home environments (via [`nix-community/home-manager`][home-manager]), and
|
||||
- host configurations (via [`NixOS/nixpkgs/nixos`][nixpkgs]).
|
||||
|
||||
This library is based on [flake-utils-plus][].
|
||||
|
||||
# Usage
|
||||
The best way to make use of library is with the [Official template](https://github.com/divnix/devos).
|
||||
The primary function to make use of is `mkFlake` to create your devos flake.
|
||||
To learn about `mkFlake`'s options, take a look at the [mkFlake options doc](./doc/mkFlakeOptions.md)
|
||||
The best way to make use of library is with the [Official template][template].
|
||||
|
||||
This library is based on [flake-utils-plus](https://github.com/gytis-ivaskevicius/flake-utils-plus).
|
||||
You can also have a look at the different [examples][].
|
||||
|
||||
# Philosophy
|
||||
|
||||
In it's `lib.mkFlake` function, _digga_ implements a well-secified API
|
||||
interface comprising four API containers that allow you to:
|
||||
|
||||
1. configure **nixpkgs channels** including internal and external overlays,
|
||||
|
||||
2. define **nixos hosts** including internal and external nixos modules as well as
|
||||
host defaults that apply to all hosts in the environment,
|
||||
|
||||
3. specify **user home environments** including internal and external home-manager
|
||||
modules, and
|
||||
|
||||
4. setup & combine a series of **devshells** that you like to have available in
|
||||
your projects.
|
||||
|
||||
## Modules, Profiles & Suites
|
||||
For nixos- & home-manager-modules, _digga_ allows you to distinguish between
|
||||
_modules_, _profiles_ and _suites_.
|
||||
|
||||
- **Modules** are abstract configurations that, while holding the implementation, do not
|
||||
set any system state.
|
||||
|
||||
- **Profiles** are concrete configurations that set system state within the profile domain.
|
||||
|
||||
- **Suites** are a composable, clean and discoverable mechanism for profile aggregation.
|
||||
|
||||
## Internal Art vs External Art
|
||||
Overlays and modules can be defined internally coming form your repo or externally
|
||||
coming from an upstream flake. This distinction serves the library to only export
|
||||
your own work as the public flake output.
|
||||
|
||||
Downstream consumers of your flake can now more easily tell your art apart from
|
||||
other upstream art.
|
||||
|
||||
# Contributing
|
||||
We encourage contributions of any kind. The simplest way to get involved is to
|
||||
start posting your opinions on the issue or discussion threads. To craft well
|
||||
thought out APIs we need all the thoughts regarding new ideas.
|
||||
join the [chat][] or report problems and ideas on the [issue thread][issues].
|
||||
|
||||
Pull Requests are just as amazing. To keep the library stable, all changes should
|
||||
target the `develop` branch. Only minor bug-fixes or release PRs can target master.
|
||||
To craft well thought out APIs we need all the thoughts regarding new ideas.
|
||||
|
||||
Pull Requests are just as amazing.
|
||||
|
||||
# License
|
||||
|
||||
Digga is licensed under the [MIT License][mit].
|
||||
|
||||
[nix]: https://nixos.org/manual/nix/stable
|
||||
[mit]: https://mit-license.org
|
||||
[chat]: https://matrix.to/#/#devos:nixos.org
|
||||
[devshell]: https://github.com/numtide/devshell
|
||||
[examples]: https://github.com/divnix/digga/tree/main/examples
|
||||
[flakes]: https://nixos.wiki/wiki/Flakes
|
||||
|
||||
[flake-utils-plus]: https://github.com/gytis-ivaskevicius/flake-utils-plus
|
||||
[home-manager]: https://github.com/nix-community/home-manager
|
||||
[issues]: https://github.com/divnix/digga/issues
|
||||
[mit]: https://mit-license.org
|
||||
[nix]: https://nixos.org/manual/nix/stable
|
||||
[nixpkgs]: https://github.com/nixos/nixpkgs
|
||||
[template]: https://github.com/divnix/devos
|
||||
|
||||
|
||||
2
doc/.gitignore
vendored
Normal file
2
doc/.gitignore
vendored
Normal file
@ -0,0 +1,2 @@
|
||||
book
|
||||
index.html
|
||||
16
doc/CONTRIBUTING.md
Normal file
16
doc/CONTRIBUTING.md
Normal file
@ -0,0 +1,16 @@
|
||||
# TL;DR;
|
||||
- **Target Branch**: `main`
|
||||
- **Merge Policy**: [`bors`][bors] is alwyas right (→ `bors try`)
|
||||
- **Docs**: every changeset is expected to contain doc updates
|
||||
- **Commit Msg**: be a poet! Comprehensive and explanatory commit messages
|
||||
should cover the motivation and use case in an easily understandable manner
|
||||
even when read after a few months.
|
||||
- **Test Driven Development**: please default to test driven development you can
|
||||
make use of the `./examples` & `./e2e` and wire test up in the devshell.
|
||||
|
||||
### Within the Devshell (`nix develop`)
|
||||
- **Hooks**: please `git commit` within the devshell
|
||||
- **Fail Early**: please run `check-all` from within the devshell on your local machine
|
||||
|
||||
[bors]: https://bors.tech
|
||||
|
||||
10
doc/SUMMARY.md
Normal file
10
doc/SUMMARY.md
Normal file
@ -0,0 +1,10 @@
|
||||
# Summary
|
||||
|
||||
- [Introduction](../README.md)
|
||||
- [API Reference](./api-reference.md)
|
||||
- [Channels](./api-reference-channels.md)
|
||||
- [Home](./api-reference-home.md)
|
||||
- [Devshell](./api-reference-devshell.md)
|
||||
- [Nixos](./api-reference-nixos.md)
|
||||
- [Library Reference]()
|
||||
- [Contributing](./CONTRIBUTING.md)
|
||||
75
doc/api-reference-channels.md
Executable file
75
doc/api-reference-channels.md
Executable file
@ -0,0 +1,75 @@
|
||||
# Channels API Container
|
||||
Configure your channels that you can use throughout your configurations.
|
||||
|
||||
> #### ⚠ Gotcha ⚠
|
||||
> Devshell & Home-Manager `pkgs` instances are rendered off the
|
||||
> `nixos.hostDefaults.channelName` (default) channel.
|
||||
|
||||
|
||||
## channels
|
||||
nixpkgs channels to create
|
||||
|
||||
|
||||
*_Type_*:
|
||||
attribute set of submodules or path convertible to it
|
||||
|
||||
|
||||
*_Default_*
|
||||
```
|
||||
{}
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
## channels.\<name\>.config
|
||||
nixpkgs config for this channel
|
||||
|
||||
|
||||
*_Type_*:
|
||||
attribute set or path convertible to it
|
||||
|
||||
|
||||
*_Default_*
|
||||
```
|
||||
{}
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
## channels.\<name\>.input
|
||||
nixpkgs flake input to use for this channel
|
||||
|
||||
|
||||
*_Type_*:
|
||||
nix flake
|
||||
|
||||
|
||||
*_Default_*
|
||||
```
|
||||
"config.self.inputs.<name>"
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
## channels.\<name\>.overlays
|
||||
overlays to apply to this channel
|
||||
these will get exported under the 'overlays' flake output
|
||||
as \<channel\>/\<name\> and any overlay pulled from ${inputs}
|
||||
will be filtered out
|
||||
|
||||
|
||||
*_Type_*:
|
||||
list of valid Nixpkgs overlay or path convertible to its or anything convertible to it or path convertible to it
|
||||
|
||||
|
||||
*_Default_*
|
||||
```
|
||||
[]
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
54
doc/api-reference-devshell.md
Executable file
54
doc/api-reference-devshell.md
Executable file
@ -0,0 +1,54 @@
|
||||
# Devshell API Container
|
||||
Configure your devshell module collections of your environment.
|
||||
|
||||
|
||||
## devshell
|
||||
Modules to include in your devos shell. the `modules` argument
|
||||
will be exported under the `devshellModules` output
|
||||
|
||||
|
||||
*_Type_*:
|
||||
submodule or path convertible to it
|
||||
|
||||
|
||||
*_Default_*
|
||||
```
|
||||
{}
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
## devshell.externalModules
|
||||
modules to include that won't be exported
|
||||
meant importing modules from external flakes
|
||||
|
||||
|
||||
*_Type_*:
|
||||
list of valid modules or anything convertible to it
|
||||
|
||||
|
||||
*_Default_*
|
||||
```
|
||||
[]
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
## devshell.modules
|
||||
modules to include in all hosts and export to devshellModules output
|
||||
|
||||
|
||||
*_Type_*:
|
||||
list of valid module or path convertible to its or anything convertible to it
|
||||
|
||||
|
||||
*_Default_*
|
||||
```
|
||||
[]
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
149
doc/api-reference-home.md
Executable file
149
doc/api-reference-home.md
Executable file
@ -0,0 +1,149 @@
|
||||
# Home-Manager API Container
|
||||
Configure your home manager modules, profiles & suites.
|
||||
|
||||
|
||||
## home
|
||||
hosts, modules, suites, and profiles for home-manager
|
||||
|
||||
|
||||
*_Type_*:
|
||||
submodule or path convertible to it
|
||||
|
||||
|
||||
*_Default_*
|
||||
```
|
||||
{}
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
## home.externalModules
|
||||
modules to include that won't be exported
|
||||
meant importing modules from external flakes
|
||||
|
||||
|
||||
*_Type_*:
|
||||
list of valid modules or anything convertible to it
|
||||
|
||||
|
||||
*_Default_*
|
||||
```
|
||||
[]
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
## home.importables
|
||||
Packages of paths to be passed to modules as `specialArgs`.
|
||||
|
||||
|
||||
*_Type_*:
|
||||
attribute set
|
||||
|
||||
|
||||
*_Default_*
|
||||
```
|
||||
{}
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
## home.importables.suites
|
||||
collections of profiles
|
||||
|
||||
|
||||
*_Type_*:
|
||||
null or attribute set of list of paths or anything convertible to its or path convertible to it
|
||||
|
||||
|
||||
*_Default_*
|
||||
```
|
||||
null
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
## home.modules
|
||||
modules to include in all hosts and export to homeModules output
|
||||
|
||||
|
||||
*_Type_*:
|
||||
list of valid modules or anything convertible to it
|
||||
|
||||
|
||||
*_Default_*
|
||||
```
|
||||
[]
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
## home.profiles
|
||||
WARNING: The 'suites' and `profiles` options have been deprecated, you can now create
|
||||
both with the importables option. `rakeLeaves` can be used to create profiles and
|
||||
by passing a module or `rec` set to `importables`, suites can access profiles.
|
||||
Example:
|
||||
```
|
||||
importables = rec {
|
||||
profiles = digga.lib.importers.rakeLeaves ./profiles;
|
||||
suites = with profiles; { };
|
||||
}
|
||||
```
|
||||
See https://github.com/divnix/digga/pull/30 for more details
|
||||
|
||||
|
||||
*_Type_*:
|
||||
list of paths or path convertible to it
|
||||
|
||||
|
||||
*_Default_*
|
||||
```
|
||||
[]
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
## home.suites
|
||||
WARNING: The 'suites' and `profiles` options have been deprecated, you can now create
|
||||
both with the importables option. `rakeLeaves` can be used to create profiles and
|
||||
by passing a module or `rec` set to `importables`, suites can access profiles.
|
||||
Example:
|
||||
```
|
||||
importables = rec {
|
||||
profiles = digga.lib.importers.rakeLeaves ./profiles;
|
||||
suites = with profiles; { };
|
||||
}
|
||||
```
|
||||
See https://github.com/divnix/digga/pull/30 for more details
|
||||
|
||||
|
||||
*_Type_*:
|
||||
function that evaluates to a(n) attrs or path convertible to it
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
## home.users
|
||||
HM users that can be deployed portably without a host.
|
||||
|
||||
|
||||
*_Type_*:
|
||||
attribute set of hm user configs
|
||||
|
||||
|
||||
*_Default_*
|
||||
```
|
||||
{}
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
244
doc/api-reference-nixos.md
Executable file
244
doc/api-reference-nixos.md
Executable file
@ -0,0 +1,244 @@
|
||||
# NixOS API Container
|
||||
Configure your nixos modules, profiles & suites.
|
||||
|
||||
|
||||
## nixos
|
||||
hosts, modules, suites, and profiles for nixos
|
||||
|
||||
|
||||
*_Type_*:
|
||||
submodule or path convertible to it
|
||||
|
||||
|
||||
*_Default_*
|
||||
```
|
||||
{}
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
## nixos.hostDefaults
|
||||
Defaults for all hosts.
|
||||
the modules passed under hostDefaults will be exported
|
||||
to the 'nixosModules' flake output.
|
||||
They will also be added to all hosts.
|
||||
|
||||
|
||||
*_Type_*:
|
||||
submodule
|
||||
|
||||
|
||||
*_Default_*
|
||||
```
|
||||
{}
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
## nixos.hostDefaults.channelName
|
||||
Channel this host should follow
|
||||
|
||||
|
||||
*_Type_*:
|
||||
channel defined in `channels`
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
## nixos.hostDefaults.externalModules
|
||||
modules to include that won't be exported
|
||||
meant importing modules from external flakes
|
||||
|
||||
|
||||
*_Type_*:
|
||||
list of valid modules or anything convertible to it
|
||||
|
||||
|
||||
*_Default_*
|
||||
```
|
||||
[]
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
## nixos.hostDefaults.modules
|
||||
modules to include in all hosts and export to nixosModules output
|
||||
|
||||
|
||||
*_Type_*:
|
||||
list of valid modules or anything convertible to it
|
||||
|
||||
|
||||
*_Default_*
|
||||
```
|
||||
[]
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
## nixos.hostDefaults.system
|
||||
system for this host
|
||||
|
||||
|
||||
*_Type_*:
|
||||
null or system defined in `supportedSystems`
|
||||
|
||||
|
||||
*_Default_*
|
||||
```
|
||||
null
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
## nixos.hosts
|
||||
configurations to include in the nixosConfigurations output
|
||||
|
||||
|
||||
*_Type_*:
|
||||
attribute set of submodules
|
||||
|
||||
|
||||
*_Default_*
|
||||
```
|
||||
{}
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
## nixos.hosts.\<name\>.channelName
|
||||
Channel this host should follow
|
||||
|
||||
|
||||
*_Type_*:
|
||||
null or channel defined in `channels`
|
||||
|
||||
|
||||
*_Default_*
|
||||
```
|
||||
null
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
## nixos.hosts.\<name\>.modules
|
||||
modules to include
|
||||
|
||||
|
||||
*_Type_*:
|
||||
list of valid modules or anything convertible to it
|
||||
|
||||
|
||||
*_Default_*
|
||||
```
|
||||
[]
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
## nixos.hosts.\<name\>.system
|
||||
system for this host
|
||||
|
||||
|
||||
*_Type_*:
|
||||
null or system defined in `supportedSystems`
|
||||
|
||||
|
||||
*_Default_*
|
||||
```
|
||||
null
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
## nixos.importables
|
||||
Packages of paths to be passed to modules as `specialArgs`.
|
||||
|
||||
|
||||
*_Type_*:
|
||||
attribute set
|
||||
|
||||
|
||||
*_Default_*
|
||||
```
|
||||
{}
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
## nixos.importables.suites
|
||||
collections of profiles
|
||||
|
||||
|
||||
*_Type_*:
|
||||
null or attribute set of list of paths or anything convertible to its or path convertible to it
|
||||
|
||||
|
||||
*_Default_*
|
||||
```
|
||||
null
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
## nixos.profiles
|
||||
WARNING: The 'suites' and `profiles` options have been deprecated, you can now create
|
||||
both with the importables option. `rakeLeaves` can be used to create profiles and
|
||||
by passing a module or `rec` set to `importables`, suites can access profiles.
|
||||
Example:
|
||||
```
|
||||
importables = rec {
|
||||
profiles = digga.lib.importers.rakeLeaves ./profiles;
|
||||
suites = with profiles; { };
|
||||
}
|
||||
```
|
||||
See https://github.com/divnix/digga/pull/30 for more details
|
||||
|
||||
|
||||
*_Type_*:
|
||||
list of paths or path convertible to it
|
||||
|
||||
|
||||
*_Default_*
|
||||
```
|
||||
[]
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
## nixos.suites
|
||||
WARNING: The 'suites' and `profiles` options have been deprecated, you can now create
|
||||
both with the importables option. `rakeLeaves` can be used to create profiles and
|
||||
by passing a module or `rec` set to `importables`, suites can access profiles.
|
||||
Example:
|
||||
```
|
||||
importables = rec {
|
||||
profiles = digga.lib.importers.rakeLeaves ./profiles;
|
||||
suites = with profiles; { };
|
||||
}
|
||||
```
|
||||
See https://github.com/divnix/digga/pull/30 for more details
|
||||
|
||||
|
||||
*_Type_*:
|
||||
function that evaluates to a(n) attrs or path convertible to it
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
@ -1,69 +1,10 @@
|
||||
## channels
|
||||
nixpkgs channels to create
|
||||
|
||||
|
||||
*_Type_*:
|
||||
attribute set of submodules or path convertible to it
|
||||
|
||||
|
||||
*_Default_*
|
||||
```
|
||||
{}
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
## channels.\<name\>.config
|
||||
nixpkgs config for this channel
|
||||
|
||||
|
||||
*_Type_*:
|
||||
attribute set or path convertible to it
|
||||
|
||||
|
||||
*_Default_*
|
||||
```
|
||||
{}
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
## channels.\<name\>.input
|
||||
nixpkgs flake input to use for this channel
|
||||
|
||||
|
||||
*_Type_*:
|
||||
nix flake
|
||||
|
||||
|
||||
*_Default_*
|
||||
```
|
||||
"config.self.inputs.<name>"
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
## channels.\<name\>.overlays
|
||||
overlays to apply to this channel
|
||||
these will get exported under the 'overlays' flake output
|
||||
as \<channel\>/\<name\> and any overlay pulled from ${inputs}
|
||||
will be filtered out
|
||||
|
||||
|
||||
*_Type_*:
|
||||
list of valid Nixpkgs overlay or path convertible to its or anything convertible to it or path convertible to it
|
||||
|
||||
|
||||
*_Default_*
|
||||
```
|
||||
[]
|
||||
```
|
||||
|
||||
|
||||
# Top Level API
|
||||
`digga`'s top level api. API Containers are documented in their respective subchapter:
|
||||
|
||||
- [Channels](./api-reference-channels.md)
|
||||
- [Home](./api-reference-home.md)
|
||||
- [Devshell](./api-reference-devshell.md)
|
||||
- [Nixos](./api-reference-nixos.md)
|
||||
|
||||
## channelsConfig
|
||||
nixpkgs config for all channels
|
||||
@ -81,201 +22,6 @@ attribute set or path convertible to it
|
||||
|
||||
|
||||
|
||||
## devshell
|
||||
Modules to include in your devos shell. the `modules` argument
|
||||
will be exported under the `devshellModules` output
|
||||
|
||||
|
||||
*_Type_*:
|
||||
submodule or path convertible to it
|
||||
|
||||
|
||||
*_Default_*
|
||||
```
|
||||
{}
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
## devshell.externalModules
|
||||
modules to include that won't be exported
|
||||
meant importing modules from external flakes
|
||||
|
||||
|
||||
*_Type_*:
|
||||
list of valid modules or anything convertible to it
|
||||
|
||||
|
||||
*_Default_*
|
||||
```
|
||||
[]
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
## devshell.modules
|
||||
modules to include in all hosts and export to devshellModules output
|
||||
|
||||
|
||||
*_Type_*:
|
||||
list of valid module or path convertible to its or anything convertible to it
|
||||
|
||||
|
||||
*_Default_*
|
||||
```
|
||||
[]
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
## home
|
||||
hosts, modules, suites, and profiles for home-manager
|
||||
|
||||
|
||||
*_Type_*:
|
||||
submodule or path convertible to it
|
||||
|
||||
|
||||
*_Default_*
|
||||
```
|
||||
{}
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
## home.externalModules
|
||||
modules to include that won't be exported
|
||||
meant importing modules from external flakes
|
||||
|
||||
|
||||
*_Type_*:
|
||||
list of valid modules or anything convertible to it
|
||||
|
||||
|
||||
*_Default_*
|
||||
```
|
||||
[]
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
## home.importables
|
||||
Packages of paths to be passed to modules as `specialArgs`.
|
||||
|
||||
|
||||
*_Type_*:
|
||||
attribute set
|
||||
|
||||
|
||||
*_Default_*
|
||||
```
|
||||
{}
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
## home.importables.suites
|
||||
collections of profiles
|
||||
|
||||
|
||||
*_Type_*:
|
||||
null or attribute set of list of paths or anything convertible to its or path convertible to it
|
||||
|
||||
|
||||
*_Default_*
|
||||
```
|
||||
null
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
## home.modules
|
||||
modules to include in all hosts and export to homeModules output
|
||||
|
||||
|
||||
*_Type_*:
|
||||
list of valid modules or anything convertible to it
|
||||
|
||||
|
||||
*_Default_*
|
||||
```
|
||||
[]
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
## home.profiles
|
||||
WARNING: The 'suites' and `profiles` options have been deprecated, you can now create
|
||||
both with the importables option. `rakeLeaves` can be used to create profiles and
|
||||
by passing a module or `rec` set to `importables`, suites can access profiles.
|
||||
Example:
|
||||
```
|
||||
importables = rec {
|
||||
profiles = digga.lib.importers.rakeLeaves ./profiles;
|
||||
suites = with profiles; { };
|
||||
}
|
||||
```
|
||||
See https://github.com/divnix/digga/pull/30 for more details
|
||||
|
||||
|
||||
*_Type_*:
|
||||
list of paths or path convertible to it
|
||||
|
||||
|
||||
*_Default_*
|
||||
```
|
||||
[]
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
## home.suites
|
||||
WARNING: The 'suites' and `profiles` options have been deprecated, you can now create
|
||||
both with the importables option. `rakeLeaves` can be used to create profiles and
|
||||
by passing a module or `rec` set to `importables`, suites can access profiles.
|
||||
Example:
|
||||
```
|
||||
importables = rec {
|
||||
profiles = digga.lib.importers.rakeLeaves ./profiles;
|
||||
suites = with profiles; { };
|
||||
}
|
||||
```
|
||||
See https://github.com/divnix/digga/pull/30 for more details
|
||||
|
||||
|
||||
*_Type_*:
|
||||
function that evaluates to a(n) attrs or path convertible to it
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
## home.users
|
||||
HM users that can be deployed portably without a host.
|
||||
|
||||
|
||||
*_Type_*:
|
||||
attribute set of hm user configs
|
||||
|
||||
|
||||
*_Default_*
|
||||
```
|
||||
{}
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
## inputs
|
||||
The flake's inputs
|
||||
|
||||
@ -287,246 +33,6 @@ attribute set of nix flakes
|
||||
|
||||
|
||||
|
||||
## nixos
|
||||
hosts, modules, suites, and profiles for nixos
|
||||
|
||||
|
||||
*_Type_*:
|
||||
submodule or path convertible to it
|
||||
|
||||
|
||||
*_Default_*
|
||||
```
|
||||
{}
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
## nixos.hostDefaults
|
||||
Defaults for all hosts.
|
||||
the modules passed under hostDefaults will be exported
|
||||
to the 'nixosModules' flake output.
|
||||
They will also be added to all hosts.
|
||||
|
||||
|
||||
*_Type_*:
|
||||
submodule
|
||||
|
||||
|
||||
*_Default_*
|
||||
```
|
||||
{}
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
## nixos.hostDefaults.channelName
|
||||
Channel this host should follow
|
||||
|
||||
|
||||
*_Type_*:
|
||||
channel defined in `channels`
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
## nixos.hostDefaults.externalModules
|
||||
modules to include that won't be exported
|
||||
meant importing modules from external flakes
|
||||
|
||||
|
||||
*_Type_*:
|
||||
list of valid modules or anything convertible to it
|
||||
|
||||
|
||||
*_Default_*
|
||||
```
|
||||
[]
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
## nixos.hostDefaults.modules
|
||||
modules to include in all hosts and export to nixosModules output
|
||||
|
||||
|
||||
*_Type_*:
|
||||
list of valid modules or anything convertible to it
|
||||
|
||||
|
||||
*_Default_*
|
||||
```
|
||||
[]
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
## nixos.hostDefaults.system
|
||||
system for this host
|
||||
|
||||
|
||||
*_Type_*:
|
||||
null or system defined in `supportedSystems`
|
||||
|
||||
|
||||
*_Default_*
|
||||
```
|
||||
null
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
## nixos.hosts
|
||||
configurations to include in the nixosConfigurations output
|
||||
|
||||
|
||||
*_Type_*:
|
||||
attribute set of submodules
|
||||
|
||||
|
||||
*_Default_*
|
||||
```
|
||||
{}
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
## nixos.hosts.\<name\>.channelName
|
||||
Channel this host should follow
|
||||
|
||||
|
||||
*_Type_*:
|
||||
null or channel defined in `channels`
|
||||
|
||||
|
||||
*_Default_*
|
||||
```
|
||||
null
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
## nixos.hosts.\<name\>.modules
|
||||
modules to include
|
||||
|
||||
|
||||
*_Type_*:
|
||||
list of valid modules or anything convertible to it
|
||||
|
||||
|
||||
*_Default_*
|
||||
```
|
||||
[]
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
## nixos.hosts.\<name\>.system
|
||||
system for this host
|
||||
|
||||
|
||||
*_Type_*:
|
||||
null or system defined in `supportedSystems`
|
||||
|
||||
|
||||
*_Default_*
|
||||
```
|
||||
null
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
## nixos.importables
|
||||
Packages of paths to be passed to modules as `specialArgs`.
|
||||
|
||||
|
||||
*_Type_*:
|
||||
attribute set
|
||||
|
||||
|
||||
*_Default_*
|
||||
```
|
||||
{}
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
## nixos.importables.suites
|
||||
collections of profiles
|
||||
|
||||
|
||||
*_Type_*:
|
||||
null or attribute set of list of paths or anything convertible to its or path convertible to it
|
||||
|
||||
|
||||
*_Default_*
|
||||
```
|
||||
null
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
## nixos.profiles
|
||||
WARNING: The 'suites' and `profiles` options have been deprecated, you can now create
|
||||
both with the importables option. `rakeLeaves` can be used to create profiles and
|
||||
by passing a module or `rec` set to `importables`, suites can access profiles.
|
||||
Example:
|
||||
```
|
||||
importables = rec {
|
||||
profiles = digga.lib.importers.rakeLeaves ./profiles;
|
||||
suites = with profiles; { };
|
||||
}
|
||||
```
|
||||
See https://github.com/divnix/digga/pull/30 for more details
|
||||
|
||||
|
||||
*_Type_*:
|
||||
list of paths or path convertible to it
|
||||
|
||||
|
||||
*_Default_*
|
||||
```
|
||||
[]
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
## nixos.suites
|
||||
WARNING: The 'suites' and `profiles` options have been deprecated, you can now create
|
||||
both with the importables option. `rakeLeaves` can be used to create profiles and
|
||||
by passing a module or `rec` set to `importables`, suites can access profiles.
|
||||
Example:
|
||||
```
|
||||
importables = rec {
|
||||
profiles = digga.lib.importers.rakeLeaves ./profiles;
|
||||
suites = with profiles; { };
|
||||
}
|
||||
```
|
||||
See https://github.com/divnix/digga/pull/30 for more details
|
||||
|
||||
|
||||
*_Type_*:
|
||||
function that evaluates to a(n) attrs or path convertible to it
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
## outputsBuilder
|
||||
builder for flake system-spaced outputs
|
||||
The builder gets passed an attrset of all channels
|
||||
@ -570,3 +76,4 @@ list of strings
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
10
doc/book.toml
Normal file
10
doc/book.toml
Normal file
@ -0,0 +1,10 @@
|
||||
[book]
|
||||
authors = [
|
||||
"Timothy DeHerrera",
|
||||
"Parthiv Seetharaman",
|
||||
"David Arnold",
|
||||
]
|
||||
language = "en"
|
||||
multilingual = false
|
||||
src = "."
|
||||
title = "Digga Library Docs"
|
||||
33
doc/tests.md
Normal file
33
doc/tests.md
Normal file
@ -0,0 +1,33 @@
|
||||
# Testing
|
||||
|
||||
Testing is always an important aspect of any software development project, and
|
||||
NixOS offers some incredibly powerful tools to write tests for your
|
||||
configuration, and, optionally, run them in
|
||||
[CI](./integrations/hercules.md).
|
||||
|
||||
## Unit Tests
|
||||
Unit tests can be created from regular derivations, and they can do
|
||||
almost anything you can imagine. By convention, it is best to test your
|
||||
packages during their [check phase][check]. All packages and their tests will
|
||||
be built during CI.
|
||||
|
||||
## Integration Tests
|
||||
All your profiles defined in suites will be tested in a NixOS VM.
|
||||
|
||||
You can write integration tests for one or more NixOS VMs that can,
|
||||
optionally, be networked together, and yes, it's as awesome as it sounds!
|
||||
|
||||
Be sure to use the `mkTest` function from digga, `digga.lib.pkgs-lib.mkTest`
|
||||
which wraps the official [testing-python][testing-python] function to ensure
|
||||
that the system is setup exactly as it is for a bare DevOS system. There are
|
||||
already great resources for learning how to use these tests effectively,
|
||||
including the official [docs][test-doc], a fantastic [blog post][test-blog],
|
||||
and the examples in [nixpkgs][nixos-tests].
|
||||
|
||||
[test-doc]: https://nixos.org/manual/nixos/stable/index.html#sec-nixos-tests
|
||||
[test-blog]: https://www.haskellforall.com/2020/11/how-to-use-nixos-for-lightweight.html
|
||||
[default]: https://github.com/divnix/devos/tree/core/tests/default.nix
|
||||
[run-test]: https://github.com/NixOS/nixpkgs/blob/6571462647d7316aff8b8597ecdf5922547bf365/lib/debug.nix#L154-L166
|
||||
[nixos-tests]: https://github.com/NixOS/nixpkgs/tree/master/nixos/tests
|
||||
[testing-python]: https://github.com/NixOS/nixpkgs/tree/master/nixos/lib/testing-python.nix
|
||||
[check]: https://nixos.org/manual/nixpkgs/stable/#ssec-check-phase
|
||||
6
doc/theme/highlight.js
vendored
Normal file
6
doc/theme/highlight.js
vendored
Normal file
File diff suppressed because one or more lines are too long
@ -7,17 +7,59 @@ let
|
||||
digga = inputs.digga;
|
||||
pkgs = import nixpkgs { inherit system; config = { }; overlays = [ ]; };
|
||||
|
||||
docOptions = (digga.lib.mkFlake { self = {}; inputs = {};}).options;
|
||||
evaledOptions = (pkgs.lib.evalModules { modules = [ docOptions ]; }).options;
|
||||
|
||||
mkDocPartMd = part: title: intro:
|
||||
pkgs.writeText "api-reference-${part}.md" ''
|
||||
# ${title}
|
||||
${intro}
|
||||
|
||||
${(
|
||||
pkgs.nixosOptionsDoc { options = evaledOptions.${part}; }
|
||||
).optionsMDDoc}
|
||||
'';
|
||||
|
||||
in
|
||||
{
|
||||
|
||||
mkApiReference = let
|
||||
inherit (digga.lib.mkFlake { self = {}; inputs = {};}) options;
|
||||
in
|
||||
pkgs.writeText "mkFlakeOptions.md"
|
||||
(
|
||||
pkgs.nixosOptionsDoc {
|
||||
inherit (pkgs.lib.evalModules { modules = [ options]; } ) options;
|
||||
}
|
||||
).optionsMDDoc;
|
||||
mkApiReferenceTopLevel = pkgs.writeText "api-reference.md" ''
|
||||
# Top Level API
|
||||
`digga`'s top level api. API Containers are documented in their respective subchapter:
|
||||
|
||||
- [Channels](./api-reference-channels.md)
|
||||
- [Home](./api-reference-home.md)
|
||||
- [Devshell](./api-reference-devshell.md)
|
||||
- [Nixos](./api-reference-nixos.md)
|
||||
|
||||
${( pkgs.nixosOptionsDoc {
|
||||
options = {
|
||||
inherit (evaledOptions)
|
||||
channelsConfig
|
||||
self
|
||||
inputs
|
||||
outputsBuilder
|
||||
supportedSystems
|
||||
;
|
||||
};
|
||||
}).optionsMDDoc}
|
||||
'';
|
||||
|
||||
mkApiReferenceChannels = mkDocPartMd "channels" "Channels API Container" ''
|
||||
Configure your channels that you can use throughout your configurations.
|
||||
|
||||
> #### ⚠ Gotcha ⚠
|
||||
> Devshell & Home-Manager `pkgs` instances are rendered off the
|
||||
> `nixos.hostDefaults.channelName` (default) channel.
|
||||
'';
|
||||
mkApiReferenceDevshell = mkDocPartMd "devshell" "Devshell API Container" ''
|
||||
Configure your devshell module collections of your environment.
|
||||
'';
|
||||
mkApiReferenceHome = mkDocPartMd "home" "Home-Manager API Container" ''
|
||||
Configure your home manager modules, profiles & suites.
|
||||
'';
|
||||
mkApiReferenceNixos = mkDocPartMd "nixos" "NixOS API Container" ''
|
||||
Configure your nixos modules, profiles & suites.
|
||||
'';
|
||||
|
||||
}
|
||||
|
||||
40
shell.nix
40
shell.nix
@ -10,7 +10,31 @@ let
|
||||
devshell = import inputs.devshell { inherit pkgs system; };
|
||||
|
||||
withCategory = category: attrset: attrset // { inherit category; };
|
||||
util = withCategory "utils";
|
||||
utils = withCategory "utils";
|
||||
docs = withCategory "docs";
|
||||
|
||||
makeDocs = {
|
||||
name = "make-docs";
|
||||
help = "Execute the docs creating jobs and place the results in ./doc";
|
||||
command = ''
|
||||
nix build "$DEVSHELL_ROOT#jobs.${pkgs.system}.mkApiReferenceTopLevel" \
|
||||
&& cp result "$DEVSHELL_ROOT/doc/api-reference.md" \
|
||||
&& chmod 755 "$DEVSHELL_ROOT//doc/api-reference.md"
|
||||
nix build "$DEVSHELL_ROOT#jobs.${pkgs.system}.mkApiReferenceChannels" \
|
||||
&& cp result "$DEVSHELL_ROOT/doc/api-reference-channels.md" \
|
||||
&& chmod 755 "$DEVSHELL_ROOT//doc/api-reference-channels.md"
|
||||
nix build "$DEVSHELL_ROOT#jobs.${pkgs.system}.mkApiReferenceHome" \
|
||||
&& cp result "$DEVSHELL_ROOT/doc/api-reference-home.md" \
|
||||
&& chmod 755 "$DEVSHELL_ROOT//doc/api-reference-home.md"
|
||||
nix build "$DEVSHELL_ROOT#jobs.${pkgs.system}.mkApiReferenceDevshell" \
|
||||
&& cp result "$DEVSHELL_ROOT/doc/api-reference-devshell.md" \
|
||||
&& chmod 755 "$DEVSHELL_ROOT//doc/api-reference-devshell.md"
|
||||
nix build "$DEVSHELL_ROOT#jobs.${pkgs.system}.mkApiReferenceNixos" \
|
||||
&& cp result "$DEVSHELL_ROOT/doc/api-reference-nixos.md" \
|
||||
&& chmod 755 "$DEVSHELL_ROOT//doc/api-reference-nixos.md"
|
||||
'';
|
||||
|
||||
};
|
||||
|
||||
test = type: name: withCategory "tests" {
|
||||
name = "check-${name}";
|
||||
@ -100,26 +124,28 @@ devshell.mkShell {
|
||||
'');
|
||||
|
||||
commands = [
|
||||
{
|
||||
(utils {
|
||||
command = "git rm --ignore-unmatch -f $DEVSHELL_ROOT/{tests,examples}/*/flake.lock";
|
||||
help = "Remove all lock files";
|
||||
name = "rm-locks";
|
||||
}
|
||||
{
|
||||
})
|
||||
(utils {
|
||||
name = "fmt";
|
||||
help = "Check Nix formatting";
|
||||
command = "nixpkgs-fmt \${@} $DEVSHELL_ROOT";
|
||||
}
|
||||
{
|
||||
})
|
||||
(utils {
|
||||
name = "evalnix";
|
||||
help = "Check Nix parsing";
|
||||
command = "fd --extension nix --exec nix-instantiate --parse --quiet {} >/dev/null";
|
||||
}
|
||||
})
|
||||
|
||||
(test "examples" "downstream")
|
||||
(test "examples" "groupByConfig")
|
||||
(test "examples" "hmOnly")
|
||||
(test "examples" "all" // { command = "check-downstream && check-groupByConfig && check-hmOnly"; })
|
||||
(docs { package = pkgs.mdbook;})
|
||||
(docs makeDocs)
|
||||
|
||||
];
|
||||
}
|
||||
|
||||
Loading…
Reference in New Issue
Block a user