Update the readme to explain more about ANTLR4 and the vendoring process

SciTools · Oct 4, 2024 · 0a0fc02 · 0a0fc02
1 parent b9413c9
commit 0a0fc02
Showing 1 changed file with 16 additions and 4 deletions.
diff --git 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