Debian Codegraph @

doc/building-antlr.md

raw
1 # Building ANTLR
2
3 Most programmers do not need the information on this page because they will simply download the appropriate jar(s) or use ANTLR through maven (via ANTLR's antlr4-maven-plugin). If you would like to fork the project and fix bugs or tweak the runtime code generation, then you will almost certainly need to build ANTLR itself. There are two components:
4
5 1. the tool that compiles grammars down into parsers and lexers in one of the target languages
6 1. the runtime used by those generated parsers and lexers.
7
8 I will assume that the root directory is `/tmp` for the purposes of explaining how to build ANTLR in this document.
9
10 *As of 4.6, ANTLR tool and Java-target runtime requires Java 7.*
11
12 # Get the source
13
14 The first step is to get the Java source code from the ANTLR 4 repository at github. You can download the repository from github, but the easiest thing to do is simply clone the repository on your local disk:
15
16 ```bash
17 $ cd /tmp
18 /tmp $ git clone https://github.com/antlr/antlr4.git
19 Cloning into 'antlr4'...
20 remote: Counting objects: 61480, done.
21 remote: Total 61480 (delta 0), reused 0 (delta 0), pack-reused 61480
22 Receiving objects: 100% (61480/61480), 31.24 MiB | 7.18 MiB/s, done.
23 Resolving deltas: 100% (32970/32970), done.
24 Checking connectivity... done.
25 Checking out files: 100% (1427/1427), done.
26 ```
27
28 # Check your environment
29
30 If you are starting from a clean, minimum Ubuntu OS, check your environment.
31
32
33 ```bash
34 $ sudo apt-get update
35 $ # Get Java
36 $ java > /dev/null 2>&1
37 $ if [[ "$?" != "0" ]]; then sudo apt install -y openjdk-11-jre-headless; fi
38 $ # Get Mvn
39 $ mvn > /dev/null 2>&1
40 $ if [[ "$?" != "0" ]]; then sudo apt install -y maven; fi
41
42 ```
43
44 # Compile
45
46 ```bash
47 $ cd /tmp/antlr4
48 $ export MAVEN_OPTS="-Xmx1G" # don't forget this on linux
49 $ mvn clean # must be separate, not part of install/compile
50 $ mvn -DskipTests install
51 ...
52 [INFO] ------------------------------------------------------------------------
53 [INFO] Reactor Summary:
54 [INFO]
55 [INFO] ANTLR 4 ............................................ SUCCESS [ 0.287 s]
56 [INFO] ANTLR 4 Runtime .................................... SUCCESS [ 4.915 s]
57 [INFO] ANTLR 4 Tool ....................................... SUCCESS [ 1.315 s]
58 [INFO] ANTLR 4 Maven plugin ............................... SUCCESS [ 2.393 s]
59 [INFO] ANTLR 4 Runtime Test Annotations ................... SUCCESS [ 0.078 s]
60 [INFO] ANTLR 4 Runtime Test Processors .................... SUCCESS [ 0.019 s]
61 [INFO] ANTLR 4 Runtime Tests (2nd generation) ............. SUCCESS [ 1.986 s]
62 [INFO] ANTLR 4 Tool Tests ................................. SUCCESS [ 0.513 s]
63 [INFO] ------------------------------------------------------------------------
64 [INFO] BUILD SUCCESS
65 [INFO] ------------------------------------------------------------------------
66 [INFO] Total time: 12.005 s
67 [INFO] Finished at: 2016-11-21T11:42:42-08:00
68 [INFO] Final Memory: 52M/434M
69 [INFO] ------------------------------------------------------------------------
70 ```
71
72 **NOTE:** We do `install` not `compile` as tool tests and such refer to modules that must be pulled from the maven install local cache.
73
74 # Installing libs to mvn cache locally
75
76 To skip the tests (which require all the target languages be installed) and **install into local repository** `~/.m2/repository/org/antlr`, do this:
77
78 ```bash
79 $ export MAVEN_OPTS="-Xmx1G" # don't forget this on linux
80 $ mvn install -DskipTests=true # make sure all artifacts are visible on this machine
81 ```
82
83 You should see these jars (when building 4.6-SNAPSHOT):
84
85 ```bash
86 /Users/parrt/.m2/repository/org/antlr $ find antlr4* -name '*.jar'
87 antlr4-maven-plugin/4.6-SNAPSHOT/antlr4-maven-plugin-4.6-SNAPSHOT.jar
88 antlr4-runtime-test-annotation-processors/4.6-SNAPSHOT/antlr4-runtime-test-annotation-processors-4.6-SNAPSHOT.jar
89 antlr4-runtime-test-annotations/4.6-SNAPSHOT/antlr4-runtime-test-annotations-4.6-SNAPSHOT.jar
90 antlr4-runtime-testsuite/4.6-SNAPSHOT/antlr4-runtime-testsuite-4.6-SNAPSHOT-tests.jar
91 antlr4-runtime-testsuite/4.6-SNAPSHOT/antlr4-runtime-testsuite-4.6-SNAPSHOT.jar
92 antlr4-runtime/4.6-SNAPSHOT/antlr4-runtime-4.6-SNAPSHOT.jar
93 antlr4-tool-testsuite/4.6-SNAPSHOT/antlr4-tool-testsuite-4.6-SNAPSHOT.jar
94 antlr4/4.6-SNAPSHOT/antlr4-4.6-SNAPSHOT-tests.jar
95 antlr4/4.6-SNAPSHOT/antlr4-4.6-SNAPSHOT.jar
96 ```
97
98 Note that ANTLR is written in itself, which is why maven downloads antlr4-4.5.jar for boostrapping 4.6-SNAPSHOT purposes.
99
100 # Testing tool and targets
101
102 See [ANTLR project unit tests](antlr-project-testing.md).
103
104
105 # Building without testing
106
107 To build without running the tests (saves a lot of time), do this:
108
109 ```bash
110 $ mvn -DskipTests install
111 ```
112
113 ## Building ANTLR in Intellij IDE
114
115 After download ANTLR source, just "import project from existing sources" and click on the "Maven Projects" tab in right gutter of IDE. It should build stuff in the background automatically and look like:
116
117 <img src=images/intellij-maven.png width=200>