* refactor: implement a validation system for builders / translators etc, organize files * refactor: use seq instead of complicated validation function for validator * feat: allow adding discoverers, translators and builders via config * refactor: rework discoverers to use makeSubsystemModules as well * fix: validate extra modules properly * feat: support inline modules * feat: use extra attribute for extending * feat: make fetchers extensible properly * fix: add name to extra fetchers * feat: support list for extra * docs: add some comment to lib/modules.nix * fix: get extra module args from extraArgs * fix: collect all modules instead of only collecting modules for built-in subsystems * refactor: minor improvements * refactor: improve how default subsystem modules are declared * fix: translators and builders are directly under subsystem now * fix: correct attribute path, remove unused argument * fix: correct translators attribute paths * fix: correct file paths and translators attribute paths * fix: use correct translator attr path in wrapPureTranslator * fix: update unit tests code * fix: remove extra paranthesis in unit tests code * tests: add an extended dream2nix example * refactor: replace recursiveUpdate usage with normal update op * tests: fix and extend d2n-extended example * fix: pass config to d2n instance in wrap pure translator script * fix: correct toFile usage * fix: pass config to dlib in more places * fix: pass config to d2n instance in aggregated hashes cli and gomod2nix translator * refactor: remove unused extra modules validation, add warning for function modules * fix: remove non-existent inherited variable * docs: update translator attr path in contributors guide * docs: add docs for extending dream2nix * refactor: comment more code, warn for function modules only if extra is an attrset decl * docs: fix some typos * docs: explain some stuff in extending d2n better * fix: print function modules warning when it is a function * tests: add a new example that tests adding new subsystem and config.extra as nix file * tests: use cargo-toml as translator on d2n-extended to potentially catch more bugs * feat: add ifd warning for builders * tests: use build-rust-package builder instead of crane builder in d2n-extended to also test it instead of only testing crane builder * fix(rust/builders): always write the generated Cargo.lock so it doesnt get out of sync with our dream-lock * fix(rust/builders): delete cargo lock before writing it? * refactor: also print ifd warnings for translators * docs: link extending d2n doc in readme, link examples in extending d2n * docs: example naming (translators.new -> translators.example-translator) * feat: allow setting nix files for modules declarations (eg. subsystems, subsystems.translators) * refactor: move IFD warnings to src/lib/builders.nix / translators.nix respectively * refactor: throw instead of warning if function declarations for modules are used * refactor: fix throw usage * refactor: improve modules code * chore(deps): update nixpkgs * fix: correct some map usages * fix: use correct attr path for extra modules * chore: update examples flake inputs * style: minor formatting changes
2.0 KiB
dream2nix contributers guide
Translator Notes
In general there are 3 different types of translators
-
pure translator
- translation logic is implemented in nix lang only
- does not invoke build or read from any build output
-
pure translator utilizing IFD (import from derivation)
- 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
-
impure
- translator can be any executable program running outside of a nix build
- not constrained in any way (can do arbitrary network access etc.)
Initialize a new translator
Clone dream2nix repo and execute:
nix run .#contribute
... then select translator
and answer all questions. This will generate a template.
Further instructions are contained in the template in form of code comments.
Debug or test a translator
Unit tests (pure translators only)
Unit tests will automatically be generated as soon as your translator specifies generateUnitTestsForProjects
.
Unit tests can be executed via nix run .#tests-unit
Repl debugging
- temporarily expose internal functions of your translator
- use nix repl
nix repl ./.
- invoke a function via
subsystems.{subsystem}.translators.{translator-name}.some_function
Tested example flake
Add an example flake under ./examples/name-of-example
.
The flake can be tested via:
nix run .#tests-examples name-of-example --show-trace
The flake will be tested in the CI-pipeline as well.
Initialize a new builder
Clone dream2nix repo and execute:
nix run .#contribute
... then select builder
and answer all questions. This will generate a template.
Further instructions are contained in the template in form of code comments.
Debug or test a builder
Tested example flake
Add an example flake under ./examples/name-of-example
.
The flake can be tested via:
nix run .#tests-examples name-of-example --show-trace
The flake will be tested in the CI-pipeline as well.