dream2nix/docs/contributors-guide.md

# dream2nix contributers guide

## Contribute Translator

In general there are 3 different types of translators

1. pure translator

   - translation logic is implemented in nix lang only
   - does not invoke build or read from any build output

2. IFD translator

   - part of the logic is integrated as a nix build
   - nix code is used to invoke a nix build and parse its results
   - same interface as pure translator

3. impure

   - translator can be any executable program running outside of a nix build
   - not constrained in any way (can do arbitrary network access etc.)

### Add a new translator

Clone repo and execute:
```shell
nix run .#contribute
```
... then select `translator` and answer all questions. This will generate a template.

The nix file must declare the following attributes:

In case of a `pure` or `IFD` translator:

See the template generated by the contribute app

In case of an `impure` translator:

See the template generated by the contribute app

Ways of debugging your translator:

- run the dream2nix flake app and use the new translator
- temporarily expose internal functions of your translator, then use nix repl `nix repl ./.` and invoke a function via `translators.translators.{subsystem}.{type}.{translator-name}.some_function`



## Contribute Builder
### Add a new builder

Clone repo and execute:
```shell
nix run .#contribute
```
... then select `builder` and answer all questions. This will generate a template.