Invocation

CongoCC is run from its executable JAR. This chapter is the reference for CongoCC’s command line and runtime environment. For JAR installation instructions, see Installation.

Basic usage

$ java -jar congocc.jar [flags] grammarfile

The single non-flag argument is the grammar file to process. With no arguments at all, CongoCC prints its banner and the usage message and exits.

Command-line flags

-d <directory>

Output directory for the generated files, absolute or relative to the grammar file’s location. If omitted, files are written relative to the grammar file. The directory is created if it does not exist.

-lang <language>

Target language: java (the default), python, csharp, or rust.

-p <symbols>

One or more comma-separated preprocessor symbols (no spaces), each either a bare NAME or NAME=value. A bare name is given the value 1. These symbols drive the preprocessor (see The Grammar File).

-n

Suppress the check for a newer release (below).

-q

Request quieter output.

Flags may be written with one or two leading dashes. An unrecognized flag is reported and ignored rather than treated as an error. The old -jdk flag has been removed; if present it is ignored with a notice.

The newer-version check

By default, each run checks online whether a newer congocc.jar is available and, if so, offers to download it. Pass -n to skip this — appropriate when working offline or in automated builds.

Overriding settings from the environment

Settings in the grammar file take the form SETTING=value. See the Settings Reference for the list of all available settings. Grammar file settings can be overridden by environment variables or by command-line flags. An environment variable named CONGOCC_<SETTING> overrides that setting in the grammar file. A command-line flag of the form -p SETTING=value does the same from the command line. When a setting is specified in more than one place, the order of priority is:

grammar file < environment variable < command line

This is convenient for build scripts that need to redirect output or flip a flag without editing the grammar.

Exit status

CongoCC exits 0 on success and with a non-zero status on failure. Failures include usage errors (no input file, an unreadable grammar, a bad flag argument) or errors detected in the grammar itself. On success it lists each generated file and finishes with Parser generated successfully.

Converting legacy JavaCC grammars

CongoCC does not itself convert legacy JavaCC or JavaCC 21 grammars; it only reads current CongoCC syntax. The migration path, including the separate converter tool used to modernize older grammars, is described in Appendix: Legacy Mapping and Migrating from JavaCC / JavaCC21.

Build integration

For driving CongoCC from Ant, Maven, Gradle, or CI — and for regenerating deterministically — see How To: Integrate the Build, and the Target Language Guide for per-language build details.