mirror of
https://github.com/nix-community/dream2nix.git
synced 2024-09-11 14:35:30 +03:00
docs: update extending dream2nix document to reflect module system changes
This commit is contained in:
parent
e7c7077f22
commit
03f9323d2c
@ -1,73 +1,31 @@
|
||||
# Extending dream2nix with external translators, builders etc.
|
||||
|
||||
`dream2nix` can be extended while you are `init`ializing it. This can be done in a few ways.
|
||||
For extending, you need to utilize the `config.extra` option of the dream2nix config.
|
||||
`dream2nix` uses the NixOS module system for it's internal components.
|
||||
This means you can extend it using the module system.
|
||||
This can be done while the framework is being `init`ialized.
|
||||
To do this, you need to utilize the `config.modules` option of the dream2nix config.
|
||||
|
||||
## Module System Transition
|
||||
The dream2nix architecture is currently in the process of being refactored into nixos modules. The actual APIs can deviate from what is described in this document.
|
||||
For up-to-date examples see `/examples/_d2n-extended` and `/examples/_d2n-extended-new-subsystem`
|
||||
Once the transition is completed we will update this document and remove this notice.
|
||||
## Declaring `modules`
|
||||
|
||||
## Declare `extra`s from a nix file
|
||||
`config.modules` is a configuration option that expects paths to module files.
|
||||
|
||||
```nix
|
||||
dream2nix.lib.init {
|
||||
# this also works around errors with function modules
|
||||
# being declared here, which will be explained later.
|
||||
config.extra = ./nix/d2n/extras.nix;
|
||||
config.modules = [./nix/d2n/extras.nix];
|
||||
}
|
||||
```
|
||||
this file should look like this:
|
||||
this file can look like this:
|
||||
```nix
|
||||
{ dlib, lib, config, ... }:
|
||||
{ config, ... }:
|
||||
let
|
||||
inherit (config) pkgs lib dlib;
|
||||
in
|
||||
{
|
||||
subsystems.rust.translators.example-translator = ./rust-translator.nix;
|
||||
translators.example-translator = {/* translator attrs */};
|
||||
# you can declare modules using functions here
|
||||
fetchers.ipfs = {...}: {/* fetcher attrs */};
|
||||
fetchers.ipfs = {/* fetcher attrs */};
|
||||
}
|
||||
```
|
||||
|
||||
See the [`d2n-extended-new-subsystem` example](https://github.com/nix-community/dream2nix/tree/main/examples/_d2n-extended-new-subsystem) for a basic example.
|
||||
|
||||
## Declare `extra`s as an attribute set
|
||||
|
||||
```nix
|
||||
dream2nix.lib.init {
|
||||
config.extra = {
|
||||
subsystems = {
|
||||
# add new modules
|
||||
ruby.discoverers.default = ./nix/d2n/ruby/discoverer.nix;
|
||||
ruby.translators.bundix = ./nix/d2n/ruby/bundix.nix;
|
||||
# existing modules can be overridden
|
||||
rust.builders.crane = ./nix/d2n/rust/crane.nix;
|
||||
};
|
||||
# add new fetchers
|
||||
fetchers.ipfs = ./nix/d2n/fetchers/ipfs.nix;
|
||||
fetchers.gitea = ./nix/d2n/fetchers/gitea.nix;
|
||||
# existing fetchers can be overridden
|
||||
fetchers.http = ./nix/d2n/fetchers/http-proxied.nix;
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
note: you can't declare modules using functions here.
|
||||
This is because the `config` may need to be serialized to JSON and passed around in impure situations (mostly impure translators).
|
||||
|
||||
See the [`d2n-extended` example](https://github.com/nix-community/dream2nix/tree/main/examples/_d2n-extended/flake.nix) for a basic example.
|
||||
|
||||
## Compose multiple different `extra`s
|
||||
|
||||
This allows one to compose multiple `extra`s together with ease.
|
||||
The `dream2nixExtras` flake output in this case can be any of the approaches explained in this document for declaring `config.extra`.
|
||||
|
||||
```nix
|
||||
dream2nix.lib.init {
|
||||
# note: .dream2nixExtras is a hypothetical standardized flake output
|
||||
# in practice this can be any flake output.
|
||||
config.extra = [
|
||||
haskellSubsystemFlake.dream2nixExtras
|
||||
crystalSubsystemFlake.dream2nixExtras
|
||||
gleamSubsystemFlake.dream2nixExtras
|
||||
];
|
||||
}
|
||||
```
|
||||
See the [`d2n-extended` example](https://github.com/nix-community/dream2nix/tree/main/examples/_d2n-extended) for an example on how to extend existing subsystems.
|
||||
See the [`d2n-extended-new-subsystem` example](https://github.com/nix-community/dream2nix/tree/main/examples/_d2n-extended-new-subsystem) for an example on how to implement a new subsystem.
|
||||
|
@ -39,7 +39,7 @@ in {
|
||||
'';
|
||||
};
|
||||
modules = l.mkOption {
|
||||
type = t.listOf (t.oneOf [t.attrs t.path (t.functionTo t.attrs)]);
|
||||
type = t.listOf t.path;
|
||||
default = [];
|
||||
description = ''
|
||||
Extra modules to import in while evaluating the dream2nix framework.
|
||||
|
Loading…
Reference in New Issue
Block a user