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:

Section Description
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.

Running Maven

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.

Command Description
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.

Common Issues

As questions arise, we will update this section.

Issue Solution
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.

Further Information

If you're interested in learning more about Maven, you can read about it on their website.

Other build tools not used in this class

Apache Ant
GNU Make
Gradle