-
Notifications
You must be signed in to change notification settings - Fork 1
Tutorial: Quick Maven Guide
For a brief overview of Maven, see Apache's Maven in Five Minutes guide. For a more in-depth resource, see this tutorialspoint page or Maven's Getting Started Guide.
Maven is a versatile build platform and software management system. Consider it a robust Makefile or as an Eclipse for the command line. Maven can perform builds, tests, dependency management and more. The following will explain how the Interface SDK uses Maven, and how you can benefit from the tools it provides. As with any outside resource, not all information on Maven will be listed here- this simply provides a starting point for using Maven's capabilities.
Although Maven is a convention over configuration-driven tool (based on the configuration-driven tool Ant), all of the default settings can be overridden. This is done in the top level pom.xml file of any Maven project. A basic pom file might look like this:
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>com.mycompany.module</groupId>
<artifactId>my-module</artifactId>
<packaging>jar</packaging>
<version>1.0-SNAPSHOT</version>
<name>my-module</name>
<url>http://maven.apache.org</url>
<dependencies>
<dependency>
<groupId>junit</groupId>
<artifactId>junit</artifactId>
<version>3.8.1</version>
<scope>test</scope>
</dependency>
</dependencies>
</project>
```
Besides the xml meta information at the top, the most important information is the `groupId`, `artifactId` and `version` tags. These declare the package name, the project name and the version of your project respectively. When creating a new project, you will want to start with a structure similar to this. Fortunately, Maven provides a scaffolding tool to get you started. Here is an example command to use Maven to generate a project:
```
mvn archetype:generate \
-DgroupId=com.mycompany.module \
-DartifactId=my-module \
-DarchetypeArtifactId=maven-archetype-quickstart \
-DinteractiveMode=false
```
See [Creating a Module Using Maven](https://github.com/ColoradoSchoolOfMines/interface_sdk/wiki/Tutorial:-Creating-a-Module-Using-Maven) for more specific implementation on how to use Maven to make a module.
Maven Directory Structure
--------
By default, Maven will build a project with:
1. The pom.xml file, explained above
2. A src/ folder
This src folder will contain a main/ and test/ folder, both of which contain a java/GROUP_ID set of folders, where GROUP_ID is the groupId specified in the generation stage. For example, with the parameters shown above, the directory structure would appear as follows:
```
my-module
|-- pom.xml
`-- src
|-- main
| `-- java
| `-- com
| `-- mycompany
| `-- module
| `-- App.java
|
`-- test
`-- java
`-- com
`-- mycompany
`-- module
`-- AppTest.java
```
If you need to use resources in your project, create a new folder in main or test titled resources/. Any files or folders in this resources folder will be moved into the base level directory (in this example, my-module) once 'mvn package' is used to build the JAR. If resources are included, the structure changes to this:
```
my-module
|-- pom.xml
`-- src
|-- main
| |-- java
| | `-- com
| | `-- mycompany
| | `-- module
| | `-- Module.java
| `-- resources
|
`-- test
|-- java
| `-- com
| `-- mycompany
| `-- module
| `-- ModuleTest.java
`-- resources
```
Note that any test resources should only be used for testing. They will not be moved into the JAR when packaged.
Maven Dependencies
------
Another key feature of Maven is its ability to manage the dependencies for Maven projects. Maven has a large repository of libraries you can use in your project called the [Maven Central Repository](http://search.maven.org/). To add a dependency to your project, modify your pom.xml file's `dependencies` and add a `dependency` tag similar to this:
By adding this dependency tag, this includes the core Processing 1.5.1 library into the project, and by using the correct imports, any functions in the library can be used as soon as the pom is saved. Maven automatically downloads the proper jar files the first time a build or test command is called.
NOTE: If your project's pom references a Maven project that is also on your machine, and the version numbers match, Maven will favor the local project's files over files in the Maven Central Repository or other locations. This may cause errors when moving your project to another machine.
When adding a dependency, Maven downloads the jar files you referenced into a directory on your machine. This directory defaults to $HOME/.m2. If you have third party jars, you can manually install them into this directory and still reference them in your pom as before, making sure to get the correct information for groupId and artifactId. To install your own jar you can use the following maven command:
mvn install:install-file -Dfile=<path-to-file> -DgroupId=<group-id> \
-DartifactId=<artifact-id> -Dversion=<version> -Dpackaging=<packaging>
Now you can reference this library as before in your pom and include the correct packages in your code.
Maven will automatically run JUnit tests specified in the src/test/java/GROUP_ID path. To run these tests using Maven, call mvn test. To guarantee a clean test, use mvn clean test. Maven will also run tests with the mvn package command, and if any tests fail, the build process will be halted. To disable this functionality, call mvn package -Dmaven.test.skip=true.
Once Maven has a valid pom file to reference, many different commands can be run from the pom's directory. Here are a few basic commands Maven supports:
-
mvn archetype:generate- Creates a new project, and takes multiple different parameters. See Creating a Project using Maven for more detailed information. -
mvn compile- Tries to compile the project. Does not build the JAR. -
mvn clean- Cleans the current project. -
mvn test- Runs all JUnit tests as specified above. -
mvn package- Runs all JUnit tests, and if no tests fail or build errors occur, creates a JAR file in the target/ folder.-
mvn package -Dmaven.test.skip=true- Same as above, but skips all tests. Useful when you need the JAR, but know that some tests don't pass.
-
NOTE: Many of these commands can be strung together to execute in series, i.e. mvn clean test or mvn clean package. You do not need to call mvn compile before mvn package, as the former is done automatically by the latter.
- Apache Maven Project - The main homepage for the Maven project.
- Java Forums - An unofficial forum for asking questions about Maven. Search first to see if someone else has asked your question.