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

To add a new translator, execute the flakes app contribute which will generate a template for you. Then open the new default.nix file in an edtior

The nix file must declare the following attributes:

In case of a pure or IFD translator:

{
  # function which receives source files and returns an attribute set
  # which follows the dream lock format
  translate = ...;

  # function which receives source files and returns either true or false
  # indicating if the current translator is capable of translating these files
  compatiblePaths = ;

  # optionally specify additional arguments that the user can provide to the
  # translator to customize its behavior
  specialArgs = ...;
}

In case of an impure translator:

{
  # A derivation which outputs an executable at `/bin/translate`.
  # The executable will be called by dream2nix for translation
  #
  # The first arg `$1` will be a json file containing the input parameters
  # like defined in /specifications/translator-call-example.json and the
  # additional arguments required according to specialArgs
  #
  # The program is expected to create a file at the location specified
  # by the input parameter `outFile`.
  # The output file must contain the dream lock data encoded as json.
  translateBin = ...;

  # A function which receives source files and returns either true or false
  # indicating if the current translator is capable of translating these files
  compatiblePaths = ;

  # optionally specify additional arguments that the user can provide to the
  # translator to customize its behavior
  specialArgs = ...;
}

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