After more than one year of on-and-off work, we are proud to announce the release of arara version 7, the TeX Live 2022 major release of arara. With this release, we implemented many long-standing feature requests and finally settled several technical questions concerning the future of arara.

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 will only cover the most relevant changes.

Making header mode the default

Prior to this release, arara checked the whole input file for directives. Thus, a file like

% arara: pdflatex
\documentclass{article}
\begin{document}
Hello World
% arara: pdflatex
\end{document}

would execute pdflatex twice. This behavior repeatedly produced unwanted behavior. For years, arara ships with -H (header mode) which scans the beginning of the file for comments and directives skipping empty lines. Hence, the following will run pdflatex once.

%!TeX program=pdflatex
% arara: pdflatex
\documentclass{article}
\begin{document}
Hello World
\end{document}

This behavior is the new default. The new -w flag restores the old behavior.

If this change does not work well for you, please consider giving feedback at the respective issue. We may consider returning to the old default if there are too many complaints. But please give the new scanning mode a sincere try before reporting, after all it is the more sensible default to increase arara's robustness.

Using an own I/O API instead of Java's File objects

In previous versions, arara's rules relied on Java's File API. That was bad for several reasons. Most importantly, we have switched to Java's Path API quite a while ago. Hence, what was used internally and what users accessed diverged.

With our general refactoring, there has been a change of strategies: we now avoid exposing any Java-specific API. The new API which you have access to when using the toFile("some file.txt") method exposes the following properties and methods:

• The properties isAbsolute, fileName, fileSize, lastModified, parent, exists, isDirectory, and isRegularFile do what their names indicate.
• The method startsWith(File) checks if the string representation of the one file is prefix of the other one's.
• normalize() turns a path into an absolute path and normalizes it.
• resolve(String | File) resolves a child.
• resolveSibling(String | File) resolves a sibling.
• readLines() reads the file's content into a List<String>.
• readText() reads the file's content into a continuous String.
• writeText(String, append? = false) writes the argument to the file; the optional argument allows appending instead of overwriting.

If you use the toFile method in your rules, you do not need to change anything. All the arara-internal methods like exists(File) have been adjusted to accept objects of the new format. In the end, the only need to change anything is in rules where you have accessed Java's File API yourself.

Introducing project definitions

The most important new feature in arara v7 is project support. Long awaited and announced, we finally managed to add projects to arara. This is a preliminary project format and definition. It will be extended in future versions.

Currently, a project may be specified in any .lua file. Running a project boils down to calling arara project.lua. The Lua script must contain a return statement returning either

• a table which matches the project format (“a project definition”), or
• a table of tables matching the project format (“a list of project definitions”).

As an example, consider the following project.lua:

return {
  {
    name = "My awesome book",
    workingDirectory = "book",
    files = {
      ["a.mp"] = {
        directives = { "metapost" },
        priority = 1
      },
      ["file.tex"] = { }
    }
  },
  {
    name = "My awesome book vol. 2",
    workingDirectory = "bookv2",
    files = { ["file.tex"] = { } },
    dependencies = { "My awesome book" }
  }
}

It contains all currently supported properties of Lua projects. This includes:

• defining multiple projects at once,
• specifying the working directory for a project,
• specifying the files belonging to a project and prioritizing those which are expected to be processed first, and
• overwriting directives from the project file (or specify directives if the file does not have some).

A minimal project specification looks like this:

return {
  files = { ["file.tex"] = { } }
}

which is basically equivalent to saying arara file.tex on the command-line.

The full Lua project specification format may be found in our documentation at our manual page.

Please consider giving us feedback on this feature. We would love to hear your use cases. See the next section to see how we are planning to extend projects in the next releases.

The next steps

For version 8 of arara, i.e. TeX Live 2023, we have big plans (as always). While not all of them may eventually end up in the released version we still want to share our ideas with you.

Improving projects

Our project model allows defining projects which may depend on each other. Hence, there exists a proper execution order (topological sorting). Having such a order (in form of a directed acyclic graph) enables us to think about parallelizing dependencies.

This does not only apply to projects but files within projects as well. Imagine compiling all metapost pictures or all standalone graphics listed as dependencies of the main file in parallel. This speedup will be significant in larger projects.

Another important improvement to projects is to make them self-sufficient. That will most probably include making configuration options like where to look for rules available within the project specification. Once rules are available in Lua as well (see next section), we might even consider ad-hoc rules in the project definition.

Furthermore, we are interested in exploring different build targets (okay, we do not want to be another make or l3build but after all it might be an interesting direction to think about). Having a target like debug and one like release might simplify workflows where a full build is not advisable most of the time. Still, we like to model explicit workflows and currently the typical solution would be to use two different preambles for both types which we consider not too elegant.

Transitioning the rule set to Lua

In order to exploit the power of the Lua engine shipped by arara, we intend to replace YAML + MVEL with Lua in the long run. That implies, the next item on our list will be adding a proper Lua rule API. arara v8 will then only ship with Lua rules by default.

There are several reasons why we think Lua rules will be a massive improvement:

• Lua is more widespread in the TeX community than Java-like MVEL.
• A proper programming language saves us from trying to fit inheritance or composition into a format like YAML.
• One rule file may bundle multiple related rules. This breaking change was planned anyway but we see a better potential of realizing this with Lua.
• And our actual main reason: it enables us to ship a rule format which is independent of the JVM (see the next section).

Compiling native executables

We will not repeat the basics from arara v6's release post. But there have been a few updates on this, especially with respect to the Lua inclusion. Last release, we described MVEL as one of the blockers which we are now about to leave behind.

Of course, we do not consider to drop MVEL just yet. After all, users have their YAML + MVEL rules since day one. We envision to provide a JVM version of arara which is able to process Lua and MVEL rules and a second, native, version which will only digest Lua rules.

This split will not be forever, most likely only one or two releases but it will be long enough to iron out all problems with the Lua rules and safely transitioning. As with all arara upgrades, we will be helping our users to port their rules once the Lua rule format is stable.