ANTLR 4 安装与 CLASSPATH 配置完全指南：从 grun 报错到环境就绪

ANTLR 4 安装与 CLASSPATH 配置完全指南从 grun 报错到环境就绪【免费下载链接】antlr4ANTLR (ANother Tool for Language Recognition) is a powerful parser generator for reading, processing, executing, or translating structured text or binary files.项目地址: https://gitcode.com/gh_mirrors/an/antlr4本篇指南围绕 ANTLR 4 FAQ 中的安装类问题展开系统讲解 ANTLR 工具Tool与运行时runtime的安装、CLASSPATH的正确配置以及安装后最常见的三类报错——Cant load Hello as lexer or parser、NoClassDefFoundError: org/antlr/v4/Tool、package org.antlr.v4.runtime does not exist——的成因与解决办法。读完本文你将能在 UNIX/macOS 与 Windows 上完整搭建 ANTLR 4 开发环境并学会用grunTestRig验证安装与调试语法。理解 ANTLR 的两部分工具与运行时要正确配置安装环境首先需要明确 ANTLR 的构成。正如仓库文档 doc/getting-started.md 所强调的ANTLR 实际上是两个东西工具Tool一个用 Java 编写的命令行程序负责把.g4语法文件翻译成目标语言Java、C、Python、Go、JavaScript、C#、Swift、Dart、PHP、TypeScript 等的 lexer/parser 代码运行时runtime生成出来的 parser/lexer 运行时所依赖的库org.antlr.v4.runtime包。哪怕你使用 IntelliJ 插件或 ANTLRWorks 来驱动工具本身生成的代码依然需要运行时库才能编译和运行。因此安装的完整目标是把同时包含工具和运行时的antlr-4.13.2-complete.jar即 complete jar工具 运行时 其他支持库合一放到CLASSPATH中并配置好antlr4与grun两个命令别名。官方推荐的最省事路径是使用antlr4-tools只需 Python3执行pip install antlr4-tools后即获得antlr4与antlr4-parse两个可执行程序它们会在需要时自动下载 Java 11 与最新版 ANTLR jar见 doc/getting-started.md 的 Getting started the easy way 一节。本文后续将聚焦于手工安装 jar 的方式因为它能让你透彻理解CLASSPATH的运作机制——这也是本 FAQ 的核心。常见错误一grun 找不到你的 lexer 或 parser这是安装完成后第一个高频问题。错误表现如下$ grun Hello r -tree Cant load Hello as lexer or parser根因当前目录.不在CLASSPATH中Java 在加载Hello、HelloLexer、HelloParser这些由你编译生成的类时根本找不到它们。grun即 TestRig运行时不看当前目录只看CLASSPATH。从仓库源码可以精确印证这一点在 tool/src/org/antlr/v4/gui/TestRig.java 的process()方法中TestRig 依次尝试加载GrammarNameLexer和GrammarName两个类两次都抛出ClassNotFoundException时就会输出这句错误System.err.println(Cant load lexerName as lexer or parser);也就是说这条信息不是语法错误而是类加载失败几乎总是CLASSPATH配置问题。解决办法把当前目录.加入CLASSPATH。macOS/Linuxexport CLASSPATH.:/usr/local/lib/antlr-4.13.2-complete.jar:$CLASSPATHWindowscmdSET CLASSPATH.;C:\Javalib\antlr4-complete.jar;%CLASSPATH%注意开头的那个点.它至关重要——很多人的CLASSPATH里只有 jar 的路径漏掉了表示当前目录的.就会反复踩到这个错误。FAQ 原文为此专门用加粗强调See the dot at the beginning? Its critical.常见错误二无法运行 ANTLR 工具本身如果你直接调用工具主类却得到如下堆栈$ java org.antlr.v4.Tool Hello.g4 Exception in thread main java.lang.NoClassDefFoundError: org/antlr/v4/Tool Caused by: java.lang.ClassNotFoundException: org.antlr.v4.Tool at java.net.URLClassLoader$1.run(URLClassLoader.java:202) ...根因org.antlr.v4.Tool类没有被加载到。原因通常是两类CLASSPATH里根本没有 ANTLR 的 jarCLASSPATH里只有运行时 jarantlr4-runtime而没有完整 jarantlr4-complete——org.antlr.v4.Tool这个类只存在于完整 jar 中。在仓库源码中工具入口类位于 tool/src/org/antlr/v4/Tool.java其package声明为org.antlr.v4main方法创建Tool实例并调用processGrammarsOnCommandLine()处理命令行中的语法文件。如果你只下载了antlr4-runtime-*.jar运行时里面只有org.antlr.v4.runtime.*包自然找不到org.antlr.v4.Tool。解决办法确保CLASSPATH指向complete jar。例如export CLASSPATH/usr/local/lib/antlr-4.13.2-complete.jar再验证$ java org.antlr.v4.Tool ANTLR Parser Generator Version 4.13.2 -o ___ specify output directory where all output is generated -lib ___ specify location of grammars, tokens files ...输出帮助信息即代表工具已可正常加载。常见错误三生成的 parser 编译失败在antlr4 Hello.g4成功生成代码后javac Hello*.java报出类似错误$ javac Hello*.java HelloBaseListener.java:3: package org.antlr.v4.runtime does not exist import org.antlr.v4.runtime.ParserRuleContext; ^ ...根因生成的代码引用了运行时包org.antlr.v4.runtime但你的CLASSPATH里没有运行时库或者连 complete jar 都没有。这与错误二的本质相同——CLASSPATH缺失。解决办法把完整 jar 加入CLASSPATH后重新编译export CLASSPATH.:/usr/local/lib/antlr-4.13.2-complete.jar:$CLASSPATH javac Hello*.java一个值得注意的细节这条错误信息也可能在只设置了工具 jar 而忘记让编译期看到运行时时出现。由于 complete jar 同时包含工具与运行时使用它即可一次覆盖工具运行、代码编译、TestRig 执行三个阶段的需求。UNIX/macOS 上的完整安装步骤结合 doc/getting-started.md 的 Installation → UNIX 一节手工安装的完整流程如下第 0 步安装 Java版本 11 或更高第 1 步下载完整 jar$ cd /usr/local/lib $ curl -O https://www.antlr.org/download/antlr-4.13.2-complete.jar也可在浏览器中从 ANTLR 官网下载页获取并放置到/usr/local/lib这类合理位置。注意4.13.2 之前的版本支持 JDK 1.8。第 2 步将 jar 加入CLASSPATH$ export CLASSPATH.:/usr/local/lib/antlr-4.13.2-complete.jar:$CLASSPATH建议把这一行写入~/.bash_profile或对应的 shell 启动脚本避免每次打开终端都要重新设置。第 3 步为工具和 TestRig 创建别名$ alias antlr4java -Xmx500M -cp /usr/local/lib/antlr-4.13.2-complete.jar:$CLASSPATH org.antlr.v4.Tool $ alias grunjava -Xmx500M -cp /usr/local/lib/antlr-4.13.2-complete.jar:$CLASSPATH org.antlr.v4.gui.TestRig说明两点-Xmx500M为 JVM 预留 500MB 堆内存处理大型语法时更稳妥FAQ 文档中的历史示例将 TestRig 类写为org.antlr.v4.runtime.misc.TestRig这是 ANTLR 4.2.2 时代的路径当前仓库源码中 TestRig 位于org.antlr.v4.gui包见 tool/src/org/antlr/v4/gui/TestRig.java请以org.antlr.v4.gui.TestRig为准。Windows 上的完整安装与配置第 0 步安装 Java1.7 或更高建议 JDK 11第 1 步下载antlr-4.13.2-complete.jar并保存到第三方 Java 库目录例如C:\Javalib。第 2 步把 jar 加入CLASSPATH二选一永久生效系统属性 → 环境变量 → 新建或追加CLASSPATH变量临时生效命令行SET CLASSPATH.;C:\Javalib\antlr-4.13.2-complete.jar;%CLASSPATH%第 3 步创建便捷命令。方式一编写放在系统PATH目录下的批处理文件antlr4.batjava org.antlr.v4.Tool %*grun.bat注意先确保CLASSPATH中包含当前目录.ECHO OFF SET TEST_CURRENT_DIR%CLASSPATH:.;% if %TEST_CURRENT_DIR% %CLASSPATH% ( SET CLASSPATH.;%CLASSPATH% ) ECHO ON java org.antlr.v4.gui.TestRig %*方式二使用 doskey 命令doskey antlr4java org.antlr.v4.Tool $* doskey grunjava org.antlr.v4.gui.TestRig $*Windows 下还需留意若使用 pip 安装antlr4-tools可能需要把 Python 的Scripts目录加入PATH使用 WSL 则与 Linux 配置方式一致详见 doc/getting-started.md 的 Windows 章节。验证安装跑通第一个 Hello 语法配置完成后用经典的 Hello 语法做端到端验证。创建Hello.g4// Define a grammar called Hello grammar Hello; r : hello ID ; // match keyword hello followed by an identifier ID : [a-z] ; // match lower-case identifiers WS : [ \t\r\n] - skip ; // skip spaces, tabs, newlines依次执行$ antlr4 Hello.g4 $ javac Hello*.java $ grun Hello r -tree hello parrt ^D (r hello parrt)^D表示 Unix 上的 EOFWindows 用^Z。-tree以 LISP 记法打印语法分析树改用-gui则会弹出可视化窗口展示规则r匹配关键字hello后跟标识符parrt的树形结构成功时效果类似下图值得说明的是-tree、-gui、-tokens、-trace、-ps file.ps、-encoding、-diagnostics、-SLL等选项全部由 TestRig 在 tool/src/org/antlr/v4/gui/TestRig.java 中逐一解析例如-tree对应printTree true最终在process()中通过tree.toStringTree(parser)输出-gui调用Trees.inspect(tree, parser)弹出窗口而-ps file.ps则调用Trees.save(tree, parser, psFile)导出 PostScript。省略输入文件名时TestRig 从标准输入读取CharStreams.fromStream(System.in, charset)。进阶排查了解 grun 背后的类加载逻辑理解 grun 的工作原理能帮你更快定位 CLASSPATH 类问题。在 tool/src/org/antlr/v4/gui/TestRig.java 的process()方法中TestRig 的加载顺序是尝试加载GrammarNameLexer如HelloLexer作为Lexer子类若失败尝试加载GrammarName本身适用于纯 lexer 语法此时起始规则名固定为tokens若再次失败打印Cant load name as lexer or parser若起始规则不是tokens再加载GrammarNameParser如HelloParser作为Parser子类。所有加载都经由Thread.currentThread().getContextClassLoader()完成而应用类加载器只认CLASSPATH——所以类找不到≈路径不在 CLASSPATH。javac Hello*.java成功但grun失败的场景通常就是编译期用了完整类路径、而运行 grun 的 shell 里CLASSPATH缺了.。补充antlr4 命令行的其他常用选项CLASSPATH就绪后工具本身的常用命令行选项也能显著提升使用体验完整清单见 doc/tool-options.md。与安装调试最相关的几个选项作用-o outdir指定输出目录默认当前目录-lib libdir指定查找.tokens文件和被import语法文件的目录-DlanguageX覆盖语法级选项如-DlanguageJava、-DlanguageCpp-package pkg为生成的代码指定包名/命名空间-listener/-no-listener是否生成 parse tree listener默认生成-visitor/-no-visitor是否生成 parse tree visitor默认不生成-Werror把警告当作错误-Xexact-output-dir所有输出严格落入-o目录忽略语法文件自身的相对路径例如生成 C 代码antlr4 -DlanguageCpp Expr.g4生成带 visitor 的 Java 代码antlr4 -visitor Expr.g4。若语法用到import或tokenVocab记得配合-lib指定依赖查找目录——仓库中的 Maven 插件测试工程如 antlr4-maven-plugin/src/test/projects/importsStandard、importTokens展示了这类跨文件语法依赖的实际布局可作为参考。总结一张环境自检清单遇到任何ANTLR 装不上 / 跑不起来的问题按此顺序自查确认 Java 已安装JDK 11java -version可用确认CLASSPATH包含 complete jarecho $CLASSPATHWindows 用echo %CLASSPATH%必须能看到antlr-4.13.2-complete.jar的路径确认CLASSPATH以.开头或包含.——这是 grun 加载你编译出的类的关键确认别名指向当前包路径工具为org.antlr.v4.ToolTestRig 为org.antlr.v4.gui.TestRig端到端验证antlr4 Hello.g4→javac Hello*.java→grun Hello r -tree输入hello parrt后按^D看到(r hello parrt)即代表安装完全成功。FAQ 中其余安装相关问题如如何安装并运行一个简单的语法为什么我的 parser 测试程序会挂起可参阅 doc/faq/getting-started.md完整 FAQ 目录见 doc/faq/index.md。【免费下载链接】antlr4ANTLR (ANother Tool for Language Recognition) is a powerful parser generator for reading, processing, executing, or translating structured text or binary files.项目地址: https://gitcode.com/gh_mirrors/an/antlr4创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考