Note
This documentation has been written to the attention of rudder-lang contributors, or anyone would like to have an insight into rudder-lang source.
Note
rudder-lang is often abbreviated to RL

rudderc

rudderc is a binary, standing for rudder compiler.
It is rudder-lang (.rl file format) compiler. For now its purpose is to generate a configuration file (CFEngine, DSC, JSON…​) from an RL file.

rudderc abilities

Abilities

As of now rudderc has two capabilities: - translate - compile

Translate

Temporary functionality.
Takes a JSON technique and converts it into a rudder-lang (.rl) technique.
Translate purpose is to allow a full testing cycle of the language (more on that here: Integration testing loop).

View of the translate() process
translate() steps

Compile

Default and main behavior.
For now compile purpose is to generate a cfengine technique from a rudder-lang technique.
Upcoming versions of rudderc-lang will support generation of several other formats like DSC or JSON.

Simple view of the compile_file() process
compile_file() steps
Complete view of the compile_file() process
Part 1 - Parsing and abstract syntax tree creation
compilation process 1
Part 2 - Generation of output format from abstract syntax tree

Example taken from the CFEngine generator

compilation process 2

stdlib

What is called stdlib (standing for standard library) is the following set of files, available in ./libs: - resourcelib.rl Contains the list of methods (resources and their relative states and params) available to rudder-lang users. - corelib.rl Contains standard enums available to rudder-lang users. - oslib.rl Contains the exhaustive list of OSes available to rudder-lang users. - cfengine_core.rl Contains the exhaustive list of CFEngine reserved words and namespaces that rudder-lang users cannot create.

Side tools (scripts)

generate_lib

A perl script that generates resourcelib.rl calling ncf api: rudder-lang generic methods library

_rudder-lang-lib generation

cfjson_tester

A python script that can either:

  • generate a json technique out of a cfengine technique using ncf api

  • compare two json techniques and output unexpected differences

  • compare two cf techniques and output unexpected differences

It is called by ./tools/tester.sh in the full testing loop.

Full testing loop: tester.sh

It is the script called both from the production and dev (with a configuration file) environments. See Integration testing loop for explanations.

Integration testing loop

Right now rudder-lang is deployed but not properly released: what it means is that it is only called for its own testing purpose, it is not used to generated techniques yet.

In practice, every time a technique is saved from the Technique Editor (which outputs a cfengine technique), a script takes that technique and does the following:

  • generates cf json and rl files by calling libraries and rudderc

  • compares the original files with rudderc generated files

  • differences and potential compilation / scripting errors are logged to /var/log/rudder/rudder-lang/${technique_name}/*.

Note
diff comparison is custom as some differences are purposeful. Only unpurposeful differences (and errors) are logged.

Below is the full test loop:

test loop
Note
Once log errors become rare enough rudder-lang will be released.

Supported File formats

rudderc mostly deals with the following file formats, whether as input or output files:

  • JSON (.json)

  • rudder-lang (.rl)

  • CFEngine (.cf)

(DSC is not currently supported but is planned for Rudder 7.0 release.)

I/O file formats

Contribution process

Contribute by simply declaring a new issue here: https://issues.rudder.io/issues/

Contribute by fixing issues: