The Ludwig Compiler

lwc is the compiler for the Ludwig language. This guide details lwc usage, arguments, options, and examples.

Usage

lwc <FILE> [options]

Arguments

<FILE>
Ludwig file to compile

Options

-h | --help
Show help text.
-s | --semantics <BACKEND>

Select output backend. Note: Only two semantic backends are recommended for users: -s null and -s simple. -s null displays no output if there are no errors, and is the default backend. -s simple displays JSON output of the compiled composition, or errors if they exist. Other backends are designed for Fugue developer use only.

Values:

  • null: No output displayed. Default.
  • tree: Output a flat, tree-structured, strongly normalized form. All variables are inlined and replaced with their definitions. *
  • graph: Deprecated. *
  • proto: Output protocol buffer code. Note: Requires -o | --output-file option. *
  • simple: Output a JSON rendering of the proto version. The output contains UUIDs.
  • snapshot: Output an archive file that can be used to run a composition again. Users who want to re-run a composition can simply execute fugue run again. Note: Requires -o | --output-file option. *
--composition
Compile a Ludwig file strictly as a composition.
-d | --dump <DUMP1:DUMP2>

Dump debug info to stderr. *

Values:

  • modules: Module file paths
  • constraints: Inferred type constraints
  • core: Program core
  • lexer: Lexer output
  • operators: Operator table
  • profiling: Timing information
  • restructure: Graph after restructuring
  • types: Inferred types
  • logs: Logs
  • env: Environment variables used in the composition (via String.getEnv)
  • files: Files used in the composition (via String.readFileUtf8 or Bytes.readFile)
-i | --include-dirs DIR1:DIR2
Include additional search directories for modules.
--typecheck-only
Run the typechecker only. *
-w | --warnings
Show warnings (default).
--no-warnings
Don’t show warnings.
--werror
Exit on warnings.
--color
Enable colorized output (default).
--no-color
Disable colorized output.
--timeout SECONDS
Set length of compilation timeout, in seconds.
-o | --output-file FILE
Set output file. Required for proto and snapshot backends. Optional for text-based backends. snapshot output files must have a .tar.gz extension.
--validation-modules MODULE1:MODULE2
Specify validation module names. *
--environment-write FILE
Create a JSON file with environment variables and file mapping of the current environment. *
--environment-read FILE
Specify JSON file containing environment variables and file mapping. For use with snapshots. *
--error-format {text | json}
Set format for displaying errors and warnings. Use text for text output and json for JSON output.

* These options are meant for Fugue developer use only, and are not supported for customer use.

Definition

lwc is the compiler for the Ludwig language. It is built to support numerous backend formats and can verify the logical integrity of Ludwig programs at compile time. The Fugue CLI uses lwc to compile compositions prior to creating or updating a process, but lwc can be used on its own to test compilation.

For more information, see The Ludwig Compiler in Writing Ludwig.

Examples

Basic compilation of compositions

To quickly compile a composition, use a command like this:

lwc --composition FILE

If no output is returned, the composition has successfully compiled.

Recurring compilation of compositions

If you are working with Ludwig in an editor and on a platform with the watch command (available on OSX via Homebrew), you can get IDE-like fast feedback by running the following command in a separate pane or window on-screen:

watch -n2 -- lwc --composition FILE

A similar behavior can be achieved in bash without watch this way:

while true; do clear; lwc --composition FILE; sleep 2; done