Changelog
All notable changes to this project will be documented in this file.
The format is based on Keep a Changelog, and this project tries to adhere to Semantic Versioning from version 5.0.0 on.
Important: This CHANGELOG documents the technical nature of changes. While it is written for users, it does not attempt to provide migration guides. For these, please read the announcement blog posts on our website at https://islandoftex.gitlab.io/arara/news/.
Unreleased
7.2.0 - 2025-06-29
Added
- The new command line parameter
-Fallows specifying multiple entries in thekey=valueformat from a specified.propertiesfile to be passed to arara's session map. - A new
texfmtrule to format LaTeX documents (thanks to William Underwood for suggesting it). (see #127)
Fixed
- Resolved a potential issue with root path resolution in Windows under certain scenarios. (see #128)
- Updated
MPPPathtests to improve coverage on Windows. (see #128)
Changed
- Various build system improvements by @b-fein. (see !61, !62)
- Updated dependencies.
araranow requires Java 11 or later to run.- Kotlin Multiplatform updated to 2.2.0.
- Compatibility mode for Kotlin API and language updated to 2.2.
- Gradle updated to 8.14.2.
7.1.5 - 2024-05-06
Fixed
ararafailed to run on Windows, macOS and Linux on certain JVM versions due to a wrong method call. (see #124)
7.1.4 - 2024-05-02
Added
- A new
pdftocairorule to convert pdf's into various formats (thanks to @samcarter). (see !57)
Fixed
- Documentation for imagemagick options (thanks to @samcarter). (see !58)
7.1.3 - 2024-02-13
Added
- A new
rmdirrule to remove directories (thanks to @hackbaellchen). (see !53)
7.1.2 - 2023-10-01
Fixed
ararafailed to run on Windows, fixed by including JNA classes into the JAR (thanks to @hackbaellchen). (see #119)
7.1.1 - 2023-09-29
Fixed
ararawould raise an error when running on Java 21. (see #118)
7.1.0 - 2023-05-05
Added
- A new
mkdirrule to create directories (thanks to @hackbaellchen). (see !48) - The
MPPPathpublic API has been extended with a new method:createDirectorieswhich creates a directory and all relevant parents at the current path. It can be used in rules by going throughtoFile(file).createDirectories()access.
Fixed
- Copyright dates have been outdated throughout the codebase. (see #108)
7.0.5 - 2023-04-17
Fixed
- Various typos and style issues in the documentation (PDF and website). Thanks to @muzimuzhi for spotting and fixing most of these. (see !38, !39, !40, !43, !44, !46, #100, #102)
- A vulnerable (but in arara not realistically dangerous) log4j version caused errors in some screening tools and has been updated. (see #107)
7.0.4 - 2022-06-28
Fixed
copyandmoverules were fixed to properly normalise relative paths. (see #91)
7.0.3 - 2022-05-12
Fixed
- arara did not use the correct file separator on Windows. (see #84)
7.0.2 - 2022-05-05
Fixed
- arara used Java File objects in rules instead of the new path API in nearly
all cases except when using the
filesparameter. It is now again compliant with documented behavior and rules have been adjusted.
7.0.1 - 2022-05-03
Fixed
- arara failed to load rules on Windows due to path problems when resolving the application's path. (see #83)
- CTAN demands source files for the PDF which we did not provide since having the HTML-based PDF. Now they are included.
- The CTAN zip missed the sources for the Lua DSL component.
7.0.0 - 2022-05-01
Added
- arara now accepts
.luafiles as input files. These are treated as project specification and will let arara run all files specified in the project(s). When run asarara project.yamlyou cannot run on multiple files. If you run Lua files with arara directives they will continue to work as before. (see #11)
Changed
- The MVEL API now uses our
MPPPathobject instead ofjava.io.File. That way we are in control of the actual methods called which makes maintenance easier. There are substitutes for the most common file operations. Users of thetoFile()method are safe as this is properly casted. (breaking change) - The error message for IO errors has been changed to indicate potential encoding problems. (see #68)
- Use header-mode by default instead of scanning the whole document for
directives. The
-Hflag has been removed, to get the old behavior back usearara -w. This change is experimental, and we might return to the old behavior based on user feedback. (see #63; breaking change) - arara's manual is now built from the markdown sources powering the website using the weasyprint converter. Hence, all TeX files related to documentation and quickstart guide have been removed from the repository. (see #60)
Fixed
- The manual on the website now offers scrolling on long table of contents. (see #80)
6.1.7 - 2022-04-16
Added
- Documentation is now available on arara's homepage in addition to the PDF manual.
Changed
xelatexandxetexrules were updated to include theunsafeexecution branch. (see #79)
Fixed
- Fix shell script permissions for CTAN-distributed shell scripts.
6.1.6 - 2022-02-27
Changed
- Updated dependencies.
6.1.5 - 2021-12-21
Fixed
- Fix shipping a vulnerable
log4jversion. (see #78)
6.1.4 - 2021-12-14
Fixed
- Fix shipping a vulnerable
log4jversion. (see #77)
6.1.3 - 2021-11-17
Fixed
- The
indentrule did not honour subdirectories. Only file names were used (paths were stripped) and thus the system command failed on such scenarios. (see #76)
6.1.2 - 2021-10-17
Added
- The
indentrule was updated to include three new switches. (see #73)
6.1.1 - 2021-06-26
Changed
- Updated dependencies.
Fixed
- The arara logo has been printed into the completion script output. This caused failures when sourcing directly. The logo has been removed from the completion script output. (see #70)
- Configuration files have been loaded after files have been resolved which conflicts with the configuration options for file resolution. (see #71)
6.1.0 - 2021-04-04
Added
- The CLI now supports generating shell completions for bash, zsh and fish using
--generate-completions.
Fixed
ararawould raise a null pointer exception when running from the root directory in the underlying file system hierarchy. (see #69)
6.0.2 - 2021-03-31
Fixed
- The
cleanrule did not use the list size property as required by v6. (see https://chat.stackexchange.com/transcript/message/57489291#57489291) - Documentation for
Pairnow refers to its values asfirstandsecondproperty accessors.
6.0.1 - 2021-03-30
Added
- The quickstart guide has been integrated in the website as a first step towards providing web based documentation.
Fixed
- The help message did not mention the tool's purpose. (see #65)
- The
makeindexrule did not use the list access syntax as required by v6. (see https://chat.stackexchange.com/transcript/message/57484552#57484552)
6.0.0 - 2021-02-26
Added
araranow features an API and a library to ease developing an own TeX compilation workflow.- The new command line parameter
-Pallows specifying command-line options to be passed to arara's session map. In a rule, you may now retrievevalueby callinggetSession().get('arg:key')if you called arara witharara -P key=value myfile.tex. (see #38) - Configuration files now honor an option
defaultPreamblewhich allows to specify a preamble forararato use even if there are no directives in the file nor preambles specified on the command-line. Preambles are resolved at execution time meaning preambles from local configurations will take precedence over global preambles. (see #55) - The new configuration option
prependPreambleIfDirectivesGivenallows you to specify a boolean value indicating whether preambles should be applied to all files or only those without directives. It defaults totrueto avoid breaking existing workflows. araranow expands@{}orb tags withinoptionsparameter to directives. Supported methods aregetBasename,getSessionandgetOriginalReferencewith their documented meanings. (see #38, #46)- The methods above (
getBasename,getSessionandgetOriginalReference) have also been added to the conditional context, i.e. you may use them in conditional expressions in directives. - A new safe mode (
-Sor--safe-run) protects the system by disallowing certain user actions. (see #18) Currently, the following features are restricted:- file lookup will only perform explicit file resolution
unsafelyExecuteSystemCommandwill raise an exception and abort the run (although rules are still allowed to construct arbitrary commands using areturn getCommand(…)approach so this only disallows arbitrary system commands that would not get logged and are thus invisible to the user)- the
optionsparameter does not expand orb tags in any directive.
-devformats are now available within thelatexmkrule. (see #48)- The rule context has now a
getOrNull(…)method, which attempts to retrieve a list element based on an index (default is zero). If the index is out of bounds, anullvalue is returned instead. - Multiple rules have been added. Most of them are untested and we are open for
feedback and enhancements:
ghostscript,copy,move,ltx2any,llmk,spix,pdfcrop,sage. (see #47 and https://github.com/cereda/arara/issues/83) - A new quickstart guide has been written to complement to the reference manual. (see #9 and #59)
- A new website at https://islandoftex.gitlab.io/arara/ presents arara briefly and is to be extended with future releases.
Changed
ararais now split into an API, a core implementation (library) and the implementation of the executable (cli). Projects relying on code in theararaJAR distributions have to be updated. (breaking change)- Rules included in the core distribution have been renamed to have a unique prefix in the texmf tree. File names should not be relied upon (see deprecation notice in v5). (see #32)
- Languages have to be passed as IETF BCP 47 codes. The old system has been
removed. Hence, please use
en-QNinstead ofqnetc. - Localization is provided by classes as library instead of property files in arara's resources.
- If you pass an invalid language code, arara will now run in English and issue a log warning but not fail anymore. Failing due to the wrong language in a helper tool's (that is what arara is) output was considered inappropriate. (breaking change)
- The log file may now be specified as path anywhere on the file system. Warning: This behavior may be altered for a future safe mode. (see https://github.com/cereda/arara/issues/133).
- The method signatures of
loadObjectandloadClasshave been altered to return aPair<ClassLoading.ClassLoadingStatus, Object>instead of aPair<Integer, Object>. You can now access the status values as enumeration. - The implementation of methods available within rules has been moved to Kotlin
causing
nullvalues to be handled differently. Previously undefined behavior will now cause an error. (breaking change) - Preambles are now a client-only feature. This feature will neither make it to core nor to the mvel library because libraries should not deal with prepending content to a file which is what the preambles feature does.
- All
flags are consistently transformed into aList<String>. If aListis returned, it will be flattened and all values will be turned into string. If a string is returned, a single list with only that string will be returned. Other values are not encouraged but if returned transformed into a string. If you need interoperability of complexcommandcode with older versions, useisList(variable) ? variable[0] : variableto get the value of previously non-List values. (breaking change) defaultvalues now are treated as values like user input. This means, no orb tags are interpreted within this field anymore. Thedefaultvalue will be processed by theflagif specified, just as user input would be. If no flag is present, it will be returned as a (list of; cf. previous item) string. Previous rules have to be rewritten if they make use of orb tags. (breaking change)- The
dvisvgmrule now supportsdvi,xdv,epsandpdfextensions as input, as well as the inclusion of a page range. (see #53) - The
xdvipdfmxrule now supports bothdviandxdvextensions as input. (see #53)
Fixed
- The exit status handling now conforms to the documentation. We only differentiate the exit values 0, 1 and 2 as detailed in the docs.
- The correct behavior of
currentFileandgetOriginalReferencehas been restored as version 5 incorrectly used the same object for both. (see #45)
Removed
- Removed the
<arara>shorthand notation which has been deprecated in version 5.0.0. (see #26; breaking change)
5.1.3 - 2020-04-23
Added
- New rule for the authorindex package/perl script). (see this StackExchange post)
Fixed
- In version 5.1.2, we introduced a different loading order for configuration files. This has fixed the loading of preambles but broke the loading of other settings. We accounted for that in v5.1.3. (see #44)
5.1.2 - 2020-04-19
Added
- New rules for PythonTeX and PerlTeX have been added on user request. (see #42)
Fixed
- The configuration file has been loaded too late. That's why preambles did not work any longer. (see #43)
5.1.1 - 2020-04-14
Fixed
- TeX-related rules were updated to use
reference.getName()instead ofreferencedue to some issues when using absolute paths.
5.1.0 - 2020-04-03
Added
- New rules for ConTeXt, fig2dev, qpdf, convert, texcount and detex. (see #10)
Fixed
unsafelyExecuteSystemCommandfailed to execute in the current directory.
5.0.2 - 2020-03-07
Fixed
- Running
ararafailed on Windows due to wrong path encodings. (see #35)
5.0.1 - 2020-03-05
Changed
- The CI builds now produce a CTAN-ready zip file instead of running the documentation build separately
Fixed
- Multiple rules did use a
filereference where it should have usedreferenceinstead. - Documentation still mentioned
filealthough it should have been marked removed since version 5.0.0.
5.0.0 - 2020-03-03
Added
- Working directory support has been added. Users may now specify their working directory by passing a command-line option. (see #13)
ararafeatures support for processing multiple files. Prerequisite: They are located within the same working directory.- The most important update release notes are shown when calling arara with the version flag. (see #25)
- Multiple rules have been added. All of them are untested and we are open for
feedback and enhancements:
asymptote,luahbtex,metapost,pbibtex,platex,ptex,upbibtex,uplatex,uptex,xindex. (see #10)
Changed
- The build process is now based on Gradle instead of Maven. This includes new tasks providing all necessary tooling to create CTAN uploads. (see #8)
- The application has been rewritten in Kotlin and the code has been streamlined to its use cases. That includes we now run a test suite (which is far from exhaustive).
- The application is now hosted on GitLab. From now on, support will be provided there.
- The file lookup now performs an additional lookup step. File names ending on a
period will ignore the period (use case: command-line completion by various
shells) in the second lookup. So
arara file.will resolvefile..texetc. first and then (if no luck yet) try to resolvefile.tex. araradoes not use a XML database anymore. File changes are recorded in a YAML database instead.- The
biberrule is now aware of the biber optiontool. (see https://github.com/cereda/arara/issues/136)
Deprecated
- The
<arara>shorthand notation will be removed in the next major release. (see #26) - The file names of distributed rules being public should not be relied upon anymore because there are plans to rename them. (see #32)
Removed
- Removed triggers and introduced session namespaces as a replacement (see #15, #2, #17; breaking change)
- Removed velocity and with it all support for templating languages for now. It is not planned to reintroduce such a dependency to the core. But rules supporting templating tools are welcome. (see #8; breaking change)
- Removed string-based commands. Guessing the intention of a string is a strong kind of opinionating syntax which will not be followed further. (see #2; breaking change)
- Removed support for
user.dir; no lookup will be performed on this variable. (see #16; breaking change) - Removed auxiliary tools such as the separate CTAN packager, language checker and rule converter. They have been merged into the test suite or build process or lost relevance.
- Removed
filereference. The replacementreferenceis correctly typed and available since version 4.0.
Fixed
unsafelyExecuteSystemCommandnow respectsgetCommandWithWorkingDirectory(previously, working directories have been ignored; see #21).
4.0.0 - 2018-07-10
Added
- Support for multiline directives was added.
- The exit status checking can be adjusted.
- Partial directive extraction mode has been added (only scan until the first non-comment line is encountered).
- The user may define preambles to share common preambles between files that require the same compilation setup.
- Support for running code from
classandjarfiles has been added. Commands andTriggers have been introduced as abstraction layers.
Changed
- arara follows a REPL workflow (rule evaluation on demand as opposed to prior to execution).
- The rule format has been reworked, e.g.
commandhas becomecommands(breaking change). - The lookup strategy for configuration files has been altered and extended.
Deprecated
- String-based commands require guesswork and opinionated syntax. Hence, they will be removed in version 5.0.
Removed
- Cross-platform installers have been retired.
ararais available in all major TeX distributions.
3.0 - 2013-02-07
Added
- Localized messages in English, Brazilian Portuguese, German, Italian, Spanish, French, Turkish and Russian.
- Friendly and very detailed messages instead of generic ones.
- An optional configuration file is now available in order to customize and enhance the application behaviour.
- Now rules are unified in a plain format. No more compiled rules.
- Rules can allow an arbitrary number of commands instead of just one.
- Built-in functions in the rule context to ease the writing process.
Fixed
- Improved error analysis for rules and directives.
- Improved rule syntax, new keys added.
- Improved expansion mechanism.
2.0 - 2012-07-24
Added
- Added the
--timeout nflag to allow setting a timeout for every task. If the timeout is reached before the task ends,ararawill kill it and interrupt the processing. Thenvalue is expressed in milliseconds. - There's no need of noninteractive commands anymore.
araracan now handle user input through the--verbosetag. If the flag is not set and the command requires user interaction, the task execution is interrupted. - Added the
@{SystemUtils}orb tag to provide specific operating system checks. The orb tag maps theSystemUtilsclass from the amazing Apache Commons Lang library and all of its methods and properties.
Fixed
- Fixed the
--verboseflag to behave as a realtime output. - Fixed the execution of some script-based system commands to ensure cross-platform compatibility.
1.0.1 - 2012-04-24
Added
- Added support for
.tex,.dtxand.ltxfiles. When no extension is provided,ararawill automatically look for these extensions in this specific order. - Added the
--verboseflag to allow printing the complete log in the terminal. A short-vtag is also available. Bothstdoutandstderrare printed. - Fixed exit status when an exception is thrown. Now
araraalso returns a non-zero exit status when something wrong happened. Note that this behaviour happens only whenararais processing a file.
1.0 - 2012-04-24
- Initial release
For versions previous to version 5.0.0, there has not been any persistent record of changes. Please refer to the commit history for details.