From 0a0fc02edfc1224455c56f7011f4d48bb84e06d7 Mon Sep 17 00:00:00 2001 From: Phil Elson Date: Fri, 4 Oct 2024 05:47:40 +0200 Subject: [PATCH] Update the readme to explain more about ANTLR4 and the vendoring process --- cf_units/_udunits2_parser/README.md | 20 ++++++++++++++++---- 1 file changed, 16 insertions(+), 4 deletions(-) diff --git a/cf_units/_udunits2_parser/README.md b/cf_units/_udunits2_parser/README.md index a746f3ed..fd6adf47 100644 --- a/cf_units/_udunits2_parser/README.md +++ b/cf_units/_udunits2_parser/README.md @@ -13,9 +13,10 @@ a number of convenient lexical elements. Once the Jinja2 template has been expanded, the [ANTLR Java library](https://github.com/antlr/antlr4) is used to -compile the grammar into the targetted runtime language. +compile the grammar into the targeted runtime language. [A script](compile.py) is provided to automate this as much as possible. +It has a dependency on pip, Jinja2, Java and ruff. The compiled parser is committed to the repository for ease of deployment and testing (we know it isn't ideal, but it really does make things easier). @@ -24,9 +25,20 @@ changes to the grammar being proposed so that the two can remain in synch. ### Updating the ANTLR version -The above script downloads a Java Jar which needs updating to the same version -as antlr4-python3-runtime specified in the python requirements. Once these have -been updated, run [the script](compile.py) to regenerate the parser. +The [compile.py script](compile.py) copies the ANTLR4 runtime into the _antlr4_runtime +directory, and this should be commited to the repository. This means that we do not +have a runtime dependency on ANTLR4 (which was found to be challenging due to the +fact that you need to pin to a specific version of the ANTLR4 runtime, and aligning +this version with other libraries which also have an ANTLR4 dependency is impractical). + +Given that the ANTRL4 runtime is vendored into this project, we have little need +to upgrade the version unless new features of the parser/lexer generators are needed. +Upgrading the version is a simple matter of changing the version in the compile.py +script, and then re-running it. This should re-generate the parser/lexer, and update +the content in the _antlr4_runtime directory. One complexity may be that the imports +of the ANTRL4 runtime need to be rewritten to support vendoring, and the code needed +to do so may change from version to version. This topic is being followed upstream +with the ANTRL4 project with the hope of making this easier and/or built-in to ANTLR4. ### Testing the grammar