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.

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

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

Complete view of the `compile_file()` process

Part 1 - Parsing and abstract syntax tree creation

Part 2 - Generation of output format from abstract syntax tree

Example taken from the CFEngine generator

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

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:

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.)

Contribution process

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

Contribute by fixing issues:

First, fork https://github.com/Normation/rudder
Push your fix with the following commit name: git commit -m "Fixes #{issue_id}: {branch name}"
Create a pull request to the right branch. Add the following PR comment: https://issues.rudder.io/issues/{issue_id}