<span class="text-secondary">This is a repost of an <a href="https://islandoftex.gitlab.io/arara/news/release-v8">arara blog post.</a></span></p><p class="lead"> We are preparing arara version 8 for 7 February 2027, the start of TeX Live 2027 pretest. With this release, we are making Lua the preferred language for rules and extending the project support introduced in version 7. We have also worked on making build results and problems easier to follow in the terminal.

Important changes

Please consult our changelog for a detailed view on all changes and references to our issue tracker. This post is targeted at our users and covers the most relevant changes.

Updating from arara 7

arara now requires Java 21 or newer. Before updating an existing workflow, read the migration notes below for compatibility changes and examples.

The supplied launchers handle the Java options and libraries needed to run arara. If you launch the jar directly or embed arara in another application, check the updated installation instructions.

We have used AI agents to help develop arara 8. If you prefer to use a release authored entirely by humans, you are welcome to stay with arara 7. Please note that version 7 no longer receives updates.

Lua rules and configuration

All official rules are available in Lua. Existing directive comments still select rules by name, so ordinary documents can use the new engine without rewriting their directives. To migrate custom rules to Lua, translate their expressions as well as their structure; the migration notes below explain the differences.

YAML/MVEL rules are detected automatically as a legacy format. The --preferred-engine option (-e) changes which format arara tries first within each rule directory; the other format remains available as a fallback. Each directive uses the language of its resolved rule for conditionals and option interpolation. Using YAML/MVEL rules produces compatibility warnings, which can be disabled in the configuration. Support for these rules will end in arara 9. YAML configuration files and YAML directive parameters remain supported.

Lua configuration files can compute settings and paths. Configuration lookup prefers a local file over a global one, and Lua over YAML within a directory. Lua project specifications can be combined with other projects and ordinary input files in one invocation, with dependencies determining the project order.

Feedback from your builds

The plain console remains the default. An optional styled console adds task frames, interactive terminal dialogs and progress indicators. Both layouts report build outcomes and files left unprocessed after a failure. Dialogs run in the terminal instead of opening graphical windows.

Diagnostic logs can use text or JSON Lines. They record the selected rules, commands, timings and outcomes, together with configuration and runtime context. JSON records let tools inspect a run without parsing console presentation.

French joins the available interface languages, and the new upmendex rule supports multilingual Unicode indexes in both engines.

The next steps

The refreshed website brings together the quickstart, manual and the migration notes below. Library users also have an updated API reference alongside the published Kotlin artifacts.

During TeX Live pretest, please try your existing documents and custom rules with arara 8. Report problems on our GitLab issue tracker, including a small example and the arara and Java versions used.

The transition to Lua does not include a native executable in this release. arara continues to run on the JVM. We welcome feedback on the new Lua rules and project support before considering further changes to the runtime.

Migrating from arara 7

The following notes focus on updating existing rules, configuration and projects. The manual describes each feature in detail.

Runtime and rule engines

arara 8 requires Java 21 or later. Check the Java installation used by the launcher, as it may differ from the one selected in an editor.

Lua is now the preferred rule engine. The official rules have Lua counterparts. Existing custom YAML/MVEL rules are detected automatically; they are deprecated and will be discontinued in v9. Each YAML rule used produces a log warning, and the summary includes a compatibility warning. Set warn_deprecated_yaml = false in Lua configuration or warnDeprecatedYaml: false in YAML configuration to suppress both. Choosing Lua does not require converting a YAML configuration file, and choosing a Lua configuration does not change the rule-engine preference.

Directive parameter mappings still use YAML. Their scalar types matter: quote a value that must remain a string. For example, "True" remains text while plain True is a boolean. Integers outside the supported Long range remain strings rather than being truncated. Null parameter values are rejected.

Custom rules

YAML rules continue to work. Custom rules which relied on the unfinished Kotlin scripting DSL need to be written in a supported format instead; .kts rule lookup has been removed.

To adopt Lua, translate the rule's expressions and functions as well as its outer structure. For example, this YAML command:

commands:
- command: >
    @{
        return getCommand('pdflatex', options, reference.fileName);
    }
arguments:
- identifier: options
  default: ''
  flag: "@{ return parameters.options; }"

has the following Lua counterpart inside the returned rule table:

commands = {
  { command = function(ctx)
      return get_command("pdflatex", ctx.options, ctx.reference.file_name)
    end }
},
arguments = {
  { identifier = "options", default = "",
    flag = function(ctx, value) return value end }
}

Keep the rule's identifier, name and optional authors alongside these fields. The complete structure is described in Lua rules. The paired sources in the official rule pack provide worked examples for individual tools.

When replacing a YAML rule with a Lua rule, convert its directive conditionals too: MVEL's &&, ||, ! and != become Lua's and, or, not and ~=. Option interpolation uses {{ ... }} with Lua instead of @{ ... } with MVEL. The expression inside the tag must use the resolved rule's language. Check the selected file with arara rules --info <name>: --preferred-engine lua still permits YAML fallback.

Dialogs and halt requests

Dialogs now use the terminal. Remove the laf configuration key and the old pixel-width arguments to dialog helpers. Rename showDropdown to showList (show_dropdown to show_list in Lua). Choices are numbered from one; zero cancels a selection. Closed input reports an error. See Dialog boxes.

Rules must call halt(status) to stop the current file. The old session entry arara:<file>:halt is no longer read. A successful halt does not erase an earlier command failure when execution has continued after errors.

Configuration and logging

Local configuration takes priority over configuration in the user's home directory. Within one directory, Lua takes priority over YAML. If both files exist, check that the selected file contains the settings you intend to use; they are not merged.

Logging now uses one format setting. Replace YAML logging: true with logformat: text, or Lua log.enabled = true with log.format = "text":

!config
logformat: text
logname: arara.log

return { log = { format = "text", file = "arara.log" } }

Use none to disable logging or json for JSON Lines output. On the command line, -l / --log still enables text logging; --log-format selects any of the three formats. Application log labels are English independently of the console language. See Logging.

The configured database path is now honored in full, including parent directories. A relative path is resolved against the project's working directory; an absolute path is used as given. Ensure the parent directory exists. Existing YAML databases remain readable and are converted to JSON on their next save. Older arara versions cannot read the converted databases. See The file database.

Project specifications

Rename an arara 7 project specification from project.lua to project.proj.lua. An ordinary .lua argument is now an input file, and a malformed .proj.lua file is an error rather than a request to scan for directives. Rename the fields workingDirectory to working_directory and fileType to file_type; the old names are rejected.

Project names and normalized file paths must be unique across the invocation. To run several sets of directives on one file, keep one file entry and use its directives list:

return {
  files = {
    ["main.tex"] = {
      directives = {
        "% arara: pdflatex: { synctex: no }",
        "% arara: pdflatex: { synctex: yes }"
      }
    }
  }
}

Each project's working directory selects its local configuration. Projects do not inherit settings from the previously processed project. See Projects for dependencies, priorities and mixed runs.

Library users

The Kotlin rule API separates interpreted commands from executable Kotlin commands: programmatic command lambdas belong to ExecutableRuleCommand. MPPPath.toJVMPath() and toJVMFile() return absolute, normalized paths. Use suppliedSpelling to retrieve the text supplied to a path object; compute relative path relationships explicitly.

Localization contracts and host hooks live in api; locale implementations and shared runtime services live in core. Consult the API reference when updating an embedding application; arara as a library describes the module boundaries.