Thoughts?
-- Graham
Hi Graham,
I’ve used #1 and #2 since ANTLR 3, and added #3 since version 4, and have been extremely happy with the results.
1. Include and enforce the required ANTLR version as part of your build. Maven allows you to do this easily. For Ant or other systems, you’ll have to find another way. I know the NetBeans build (Ant-based) automatically downloads the correct version of dependencies from a NetBeans server at build time.
2. Always build your grammars as part of the compile process. Again Maven makes this easy. Among other things, this ensures that if you switch branches in a VCS like Git and recompile, the result will be correct.
3. I use the rule versioning mechanism described in issue antlr/antlr4#35 (in particular the rule annotations method described first). I use an annotation processor to verify all dependencies at compile time (GoWorks currently has 690, ANTLRWorks 2 currently has ~250). NetBeans evaluates the annotation processor in the IDE, providing feedback about mismatched dependencies even before the build. This feature is not available in the reference distribution of ANTLR 4, but has truly been instrumental in allowing me to rapidly build applications like GoWorks with dramatically reduced likelihood of regression bugs as I update the grammar over time.
a. Even though the C# compiler doesn’t support annotation processors like javac, I’ll be implementing this feature as a Visual Studio extension plus a static verifier for .NET assemblies that can be used through MSBuild.
--
Sam Harwell
Owner, Lead Developer
--
In general, I approach this entire issue asking “How can I ensure that changes to my code base do not introduce regression bugs or unexpected behavior?” Traditional “informational” version numbers are almost useless in this regard, which is why the rule versioning I’m using allows for tight control over dependencies and includes a static verifier. If you have specific suggestions for altering the build or generated code related to this topic, be prepared to explain how that particular method is best suited for ensuring correct behavior in a team development environment.
For part B:
For file-level versioning, you have the unique commit hashes or version numbers in the version control system.
For part A:
The Maven plugin for ANTLR 4 will automatically download the correct version of the tool in order to build the parsers from a .g4 file at compile time, even if the person does not have ANTLR 4 tool in advance (or has a different version of it). If the parsers are generated as an integrated part of the compilation process, then you have absolute control over which version of the tool is used to generate the parsers. The only question becomes which version of the v4 runtime is in the classpath when they run their program, so for that we have…
For parts A and C:
The ATN serializer/deserializer does not currently put a “format” version number in the encoded string. I’ll definitely be adding that before we release v4. Any truly breaking change in the runtime after the v4 release that would cause a grammar to become non-functional will likely result in a change to the serialization format, so you’ll get an exception when such a grammar is loaded if the runtime library is mismatched.
I updated the Maven build to include the following in the MANIFEST.MF for all of the upcoming ANTLR jars, which you can access as described in the following link:
http://stackoverflow.com/questions/5204297/put-version-to-my-java-application-netbeans
Implementation-Title: ANTLR 4 Tool
Implementation-Version: 4.0-SNAPSHOT
Implementation-Vendor-Id: org.antlr
I’d like to include the @Generated annotation in the generated code and include the version of the tool that produced it, but that annotation is marked with the SOURCE retention policy so I think that means you won’t have access to it at runtime.
--
Unfortunately I can’t change the retention policy since the @Generated annotation is included since Java SE 6 as javax.annotation.Generated (I hyperlinked it in the last email).
You should know I’m not here to shoot down your ideas. If you come up with any other specific suggestions to address your needs in this area, please let us know. :)
--
Sam Harwell
Owner, Lead Developer
From: antlr-di...@googlegroups.com [mailto:antlr-di...@googlegroups.com]
On Behalf Of Graham Wideman
Sent: Wednesday, November 28, 2012 11:58 PM
To: antlr-di...@googlegroups.com
Subject: Re: [antlr-discussion] Version info API?
Hi Sam,
--
It could be applied to the following:
· The top level lexer and parser classes
· The generated listener and visitor interfaces and base class implementations
This should cover the complete contents of those files, including the nested context classes in the parser.
I strongly feel that a fixed version of a code generator with identical input on two runs should produce the same result, so there definitely won’t be a timestamp included in the @Generated annotation.
--
Sam Harwell
Owner, Lead Developer
From: antlr-di...@googlegroups.com [mailto:antlr-di...@googlegroups.com]
On Behalf Of Graham Wideman
Sent: Thursday, November 29, 2012 5:51 AM
To: antlr-di...@googlegroups.com
Subject: Re: [antlr-discussion] Version info API?
Sam, yes I realize that Java SE 6 defines @Generated, but I mistakenly thought that Java allowed you to override annotation default parameters by applying an annotation @Retention(RetentionPolicy.RUNTIME) to the @Generated annotation where
it is used. Evidently not. And I also see there's no subclassing of annotations.
--
1. Yes, it would be appropriate to include the version number of the tool used to generate the code in the @Generated annotation.
2. I hope to modify this notice to include the ANTLR version used to generate code, but not include a timestamp.
From: antlr-di...@googlegroups.com [mailto:antlr-di...@googlegroups.com]
On Behalf Of Graham Wideman
Sent: Thursday, November 29, 2012 4:32 PM
To: antlr-di...@googlegroups.com
Subject: Re: [antlr-discussion] Version info API?
Hi Sam,
--
Item 1 cannot happen if the grammar generation process is part of the build itself.
In dealing with item 2, I force regeneration of all grammars after certain changes to the ANTLR tool itself to verify items which were intended to not affect the code. If a time stamp is included in the output, then the tools always report that changes occurred forcing me to manually verify the output of every grammar, every time. The timestamp causes false positives to reach 100% when the tool is working correctly.
Item 3 on your list is a bit misleading. If the generated code is in source control, then simply switching branches will touch the files so the last modified time will never be “stable”.
If after all this you still want to keep the generated parsers in source control, you have the additional consideration that most developers do not hand-edit files before committing them to ensure that only essential changes are committed in order to reduce commit sizes and complexity for reviewers. If each developer is getting new time stamps for the generated code even when nothing changed, these files will have a high rate of resubmission without actual changes which makes it much harder to look through the file history if necessary.
--
Sam Harwell
Owner, Lead Developer
From: antlr-di...@googlegroups.com [mailto:antlr-di...@googlegroups.com]
On Behalf Of Graham Wideman
Sent: Friday, November 30, 2012 12:39 AM
To: antlr-di...@googlegroups.com
Subject: Re: [antlr-discussion] Version info API?
Hi Sam,
--