What is Maven
Maven is a project management tool developed by the Apache Foundation. It is designed for use in projects that are primarily written in Java. Maven keeps track of key information about a project, including its name, version, and dependencies.
Why use Maven
Maven allows us to quickly organize and build projects by automating tasks such as including libraries and packaging projects into a finalized version. Among other things, this enables us to quickly and reliably transfer projects between computers.
Maven File Structure
The default structure for a Maven project is your project directory which contains a pom.xml file and a src directory. Inside src you can find a src/main/ directory and a src/test/ directory. Inside the main directory you can find a src/main/java/ directory and src/main/resources directory. The java directory can be expanded further to find your classes and the resources directory contains files used the build the frontend portions of your projects for this class. Unit tests can be found in /src/tests/.
|-- pom.xml // pom for maven `-- src // upper level src directory |-- main | `-- java | `-- edu | `-- brown | `-- cs | `-- <your username> // contains your classes and packages | `-- <project name> | `-- Main.java `-- test // contains unit tests, same directory structure as main `-- java `-- edu `-- brown `-- cs `-- <your username> `-- <project name> `-- AppTest.java
How to use Maven
Maven uses a file named pom.xml to get instructions on dependencies and building. A detailed breakdown of an example pom.xml can be found in the comments of the pom.xml provided in the Stars project. A basic section-by-section overview for the purposes of this class can be found below:
|Properties||Items listed here are similar to constants in Java. They are essentially configuration points that can be referenced in other parts of your pom.xml, or by Maven plugins.|
|Dependencies||A list of other libraries, projects, files, etc. that are used in the project defined by the POM. Each dependency is composed of a groupId, artifactId, and a version tag. These act as an address to the dependency and allows Maven to select the correct files. Some great resources to find dependencies can be found at MVNRepository, Apache Maven Repository, and Maven Search.|
|Build||This configures how your project will build. Most likely, the only subsection you will use is the one with the plugins tag. This subsection defines plugins that augment the build process of your project. Plugin functionality might include checking your project for stylistic mistakes.|
|Reporting||The reporting section contains information on plugins that allow Maven to generate sites containing detailed information about the project. Each plugin contains a groupId, artifactId, and version which act just like addresses to the file. Examples of reports used in this class include the SpotBugs and Checkstyle plugins.|
While there are many more sections that might be found in a pom.xml, these are the ones we are going to be using. For a full list of sections and their uses, see the official POM reference.
Maven is used via the mvn command, which is already installed on department machines. Maven commands take the form of mvn <command> <arguments>. The most commonly used commands are listed below.
|compile||Compiles project but does not run unit tests.|
|package||Compiles project, runs tests, and creates a JAR file to be run.|
|test||Compiles test sources and runs units tests.|
|clean||Removes the target directory containing build data.|
|site||Generates pages in /target/site/ directory where you can see reports from plugins such as checkstyle.|
After building your project with Maven, a .jar file will be generated in the target directory of your project. This is the compiled version of your code, ready to be run. The best way to run this code is with the run shell script, which is already included in the Stars project. For a description of how it works, see its in-line comments.
As questions arise, we will update this section.
|Unknown Build Issues||If you're ever stuck, the first thing you should do is a complete rebuild of your project. This can be accomplished by running mvn clean before you run mvn package.|
|Invalid Target Release: 1.8||Visit the "Setting Up" section of the Boggle project and ensure that you've properly followed the given instructions.|
If you're interested in learning more about Maven, you can read about it on their website.