Debian Codegraph @

doc/java-target.md

raw
1 # Java
2
3 ## Development environments
4
5 ### Intellij
6
7 There is a very complete and useful plug-in for intellij 12-14, you can grab at the [download page](https://plugins.jetbrains.com/plugin/7358?pr=). Check the [plugin readme](https://github.com/antlr/intellij-plugin-v4) for feature set. Just go to the preferences and click on the "Install plug-in from disk..." button from this dialog box:
8
9 <img src="images/idea-prefs.png">
10
11 Select the intellij-plugin-1.x.zip (or whatever version) file and hit okay or apply. It will ask you to restart the IDE. If you look at the plug-ins again, you will see:
12
13 <img src="images/idea-prefs-after-install.png">
14
15 Also, I have prepared a [video](https://youtu.be/eW4WFgRtFeY) that will help you generate grammars and so on using ANTLR v4 in Intellij (w/o the plugin).
16
17 ### Eclipse
18
19 Edgar Espina has created an [eclipse plugin for ANTLR v4](https://marketplace.eclipse.org/content/antlr-ide). Features: Advanced Syntax Highlighting, Automatic Code Generation (on save), Manual Code Generation (through External Tools menu), Code Formatter (Ctrl+Shift+F), Syntax Diagrams, Advanced Rule Navigation between files (F3), Quick fixes.
20
21 ### NetBeans
22
23 Sam Harwell's [ANTLRWorks2](http://tunnelvisionlabs.com/products/demo/antlrworks) works also as a plug-in, not just a stand-alone tool built on top of NetBeans.
24
25 ## Build systems
26
27 ### ant
28
29 ### mvn
30
31 *Maven Plugin Reference*
32
33 The reference pages for the latest version of the Maven plugin for ANTLR 4 can be found here:
34
35 [http://www.antlr.org/api/maven-plugin/latest/index.html](http://www.antlr.org/api/maven-plugin/latest/index.html)
36
37 *Walkthrough*
38
39 This section describes how to create a simple Antlr 4 project and build it using maven. We are going to use the ArrayInit.g4 example from chapter 3 of the book, and bring it under maven. We will need to rename files and modify them. We will conclude by building a portable stand alone application.
40
41 Generate the skeleton. To generate the maven skeleton, type these commands:
42
43 ```bash
44 mkdir SimpleAntlrMavenProject
45 cd SimpleAntlrMavenProject
46 mvn archetype:generate -DgroupId=org.abcd.examples -DartifactId=array-example -Dpackage=org.abcd.examples.ArrayInit -Dversion=1.0
47 # Accept all the default values
48 cd array-example
49 ```
50
51 Maven will ask a series of questions, simply accept the default answers by hitting enter.
52
53 Move into the directory created by maven:
54
55 ```bash
56 cd array-example
57 ```
58
59 We can use the find command to see the files created by maven:
60
61 ```bash
62 $ find . -type f
63 ./pom.xml
64 ./src/test/java/org/abcd/examples/ArrayInit/AppTest.java
65 ./src/main/java/org/abcd/examples/ArrayInit/App.java
66 ```
67
68 We need to edit the pom.xml file extensively. The App.java will be renamed to ArrayInit.java and will contain the main ANTLR java program which we will download from the book examples. The AppTest.java file will be renamed ArrayInitTest.java but will remain the empty test as created by maven. We will also be adding the grammar file ArrayInit.g4 from the book examples in there.
69
70 Get the examples for the book and put them in the Downloads folder. To obtain the ArrayInit.g4 grammar from the book, simply download it:
71
72 ```bash
73 pushd ~/Downloads
74 wget http://media.pragprog.com/titles/tpantlr2/code/tpantlr2-code.tgz
75 tar xvfz tpantlr2-code.tgz
76 popd
77 ```
78
79 Copy the grammar to the maven project. The grammar file goes into a special folder under the src/ directory. The folder name must match the maven package name org.abcd.examples.ArrayInit.
80
81 ```bash
82 mkdir -p src/main/antlr4/org/abcd/examples/ArrayInit
83 cp ~/Downloads/code/starter/ArrayInit.g4 src/main/antlr4/org/abcd/examples/ArrayInit
84 ```
85
86 Copy the main program to the maven project. We replace the maven App.java file with the main java program from the book. In the book, that main program is called Test.java, we rename it to ArrayInit.java:
87
88 ```bash
89 # Remove the maven file
90 rm ./src/main/java/org/abcd/examples/ArrayInit/App.java
91 # Copy and rename the example from the book
92 cp ~/Downloads/code/starter/Test.java ./src/main/java/org/abcd/examples/ArrayInit/ArrayInit.java
93 ```
94
95 Spend a few minutes to read the main program. Notice that it reads the standard input stream. We need to remember this when we run the application.
96
97 Edit the ArrayInit.java file. We need to add a package declaration and to rename the class. Edit the file ./src/main/java/org/abcd/examples/ArrayInit/ArrayInit.java in your favorite editor. The head of the file should look like this when you are done:
98
99 ```java
100 package org.abcd.examples.ArrayInit;
101 import org.antlr.v4.runtime.*;
102 import org.antlr.v4.runtime.tree.*;
103
104 public class ArrayInit {
105 ...
106 ```
107
108 Edit the ArrayInitTest.java file. Maven creates a test file called AppTest.java, we need to rename it to match the name of our application:
109
110 ```bash
111 pushd src/test/java/org/abcd/examples/ArrayInit
112 mv AppTest.java ArrayInitTest.java
113 sed 's/App/ArrayInit/g' ArrayInitTest.java >ArrayInitTest.java.tmp
114 mv ArrayInitTest.java.tmp ArrayInitTest.java
115 popd
116 ```
117
118 Edit the pom.xml file. Now we need to extensively modify the pom.xml file. The final product looks like this:
119
120 ```xml
121 <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
122 xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
123 <modelVersion>4.0.0</modelVersion>
124 <groupId>org.abcd.examples</groupId>
125 <artifactId>array-init</artifactId>
126 <version>1.0</version>
127 <packaging>jar</packaging>
128 <name>array-init</name>
129 <url>http://maven.apache.org</url>
130 <properties>
131 <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
132 </properties>
133 <dependencies>
134 <dependency>
135 <groupId>org.antlr</groupId>
136 <artifactId>antlr4-runtime</artifactId>
137 <version>4.5</version>
138 </dependency>
139 <dependency>
140 <groupId>junit</groupId>
141 <artifactId>junit</artifactId>
142 <version>4.13.1</version>
143 </dependency>
144 </dependencies>
145 <build>
146 <plugins>
147 <!-- This plugin sets up maven to use Java 7 -->
148 <plugin>
149 <groupId>org.apache.maven.plugins</groupId>
150 <artifactId>maven-compiler-plugin</artifactId>
151 <version>3.1</version>
152 <configuration>
153 <source>1.7</source>
154 <target>1.7</target>
155 </configuration>
156 </plugin>
157 <!-- Plugin to compile the g4 files ahead of the java files
158 See https://github.com/antlr/antlr4/blob/master/antlr4-maven-plugin/src/site/apt/examples/simple.apt.vm
159 Except that the grammar does not need to contain the package declaration as stated in the documentation (I do not know why)
160 To use this plugin, type:
161 mvn antlr4:antlr4
162 In any case, Maven will invoke this plugin before the Java source is compiled
163 -->
164 <plugin>
165 <groupId>org.antlr</groupId>
166 <artifactId>antlr4-maven-plugin</artifactId>
167 <version>4.5</version>
168 <executions>
169 <execution>
170 <goals>
171 <goal>antlr4</goal>
172 </goals>
173 </execution>
174 </executions>
175 </plugin>
176 <!-- plugin to create a self-contained portable package
177 This allows us to execute our application like this:
178 java -cp target/array-init-1.0-jar-with-dependencies.jar org.abcd.examples.ArrayInit.ArrayInit
179 -->
180 <plugin>
181 <artifactId>maven-assembly-plugin</artifactId>
182 <configuration>
183 <descriptorRefs>
184 <descriptorRef>jar-with-dependencies</descriptorRef>
185 </descriptorRefs>
186 </configuration>
187 <executions>
188 <execution>
189 <id>simple-command</id>
190 <phase>package</phase>
191 <goals>
192 <goal>attached</goal>
193 </goals>
194 </execution>
195 </executions>
196 </plugin>
197 </plugins>
198 </build>
199 </project>
200 ```
201
202 This concludes the changes we had to make. We can look at the list of files we have with the find command:
203
204 ```bash
205 $ find . -type f
206 ./pom.xml
207 ./src/test/java/org/abcd/examples/ArrayInit/ArrayInitTest.java
208 ./src/main/antlr4/org/abcd/examples/ArrayInit/ArrayInit.g4
209 ./src/main/java/org/abcd/examples/ArrayInit/ArrayInit.java
210 ```
211
212 Building a stand alone application. With all the files now in place, we can ask maven to create a standalone application. The following command does this:
213
214 ```bash
215 mvn package
216 ```
217
218 Maven creates a self-contained jar file called target/array-init-1.0-jar-with-dependencies.jar. We can execute the jar file, but remember that it expects some input on the command line, which means the command will hang on the command line until we feed it some input:
219
220 ```bash
221 java -cp target/array-init-1.0-jar-with-dependencies.jar org.abcd.examples.ArrayInit.ArrayInit
222 ```
223
224 And let's feed it the following input:
225
226 ```bash
227 {1,2,3}
228 ^D
229 ```
230
231 The ^D signals the end of the input to the standard input stream and gets the rest of the application going. You should see the following output:
232
233 ```bash
234 (init { (value 1) , (value 2) , (value 3) })
235 ```
236
237 You can also build a jar file without the dependencies, and execute it with a maven command instead:
238
239 ```bash
240 mvn install
241 mvn exec:java -Dexec.mainClass=org.abcd.examples.ArrayInit.ArrayInit
242 {1,2,3}
243 ^D
244 ```