Setting Up LWJGL with Maven

From LWJGL
Jump to: navigation, search

This is a semi-tutorial including a complete POM. To get just the POM snippets, go here: LWJGL use in Maven

Introduction

This tutorial assumes you have no familiarity with Maven, but it is not a Maven tutorial. For that, I recommend Maven in Five Minutes for a lightning tour, and Maven: The Complete Reference for a more comprehensive guide (despite "reference" in the name, it's an excellent intro to Maven).

All commands should work equally well in Windows or Unix (Linux, Solaris, OSX) operating systems, except where I otherwise give separate examples.

Step 1: Install Maven

If you don't have maven installed already, download the latest version from http://maven.apache.org/download.html and install it anywhere you like (I like C:\devel\maven on windows and /opt/maven or ~/opt/maven on unix). Make sure that wherever you install it, you have maven's bin/ directory on your PATH; in other words, just typing "mvn" on the command line results in running maven.

Linux users: you might have maven in your package manager, but if it's not Maven 3, you should go ahead and install it from maven.apache.org anyway.

Step 2: Creating a project

First off, if you have a favorite IDE already, whether it's Eclipse, NetBeans, or IDEA, you should use its maven features to create a project instead of following this step. Assuming you want to continue using maven as a "command line IDE" and possibly import it as a new IDE project later, then read on..

First, change to the parent directory your project will be. I tend to use C:\proj or ~/proj so that's where I assume you are. Your first maven command will be a doozy:

mvn archetype:generate -DarchetypeArtifactId=maven-archetype-quickstart -DgroupId=myproject -DartifactId=mygame -Dversion=1.0-SNAPSHOT 

If this is the first time you've run maven, you'll wait while maven downloads the entire internet -- or at least several dozen libraries -- before it runs anything else. You'll only have to sit through this once when you run new maven commands, and after that they're cached. At the end, it'll ask you to confirm, so go ahead and hit Enter, or fix the settings however you want.

Step 3: Edit the POM

Maven creates a directory named for your artifactId (which I'll assume here is "mygame"). Change to that directory. Under this directory, Maven has created a src directory tree structure, and another file called pom.xml. Open that file up in your favorite editor or your IDE (if you're in Eclipse, change to the "source" tab at the bottom of the editor pane). What this file contains is an uninteresting project definition, so just replace the entire contents of the file with this (click the 'view source' button on the upper right of the xml below to get something you can copy/paste).

<?xml version="1.0" encoding="UTF-8"?>
<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/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>myProject</groupId>
    <artifactId>myGame</artifactId>
    <version>1.0-SNAPSHOT</version>

    <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <natives.version>0.0.6</natives.version>
        <lwjgl.version>2.8.2</lwjgl.version>
        <slick.version>274</slick.version>
        <junit.version>4.10</junit.version>
    </properties>

    <repositories>
        <repository>
            <id>mavenNatives</id>
            <name>Maven Natives Repository</name>
            <url>http://mavennatives.googlecode.com/svn/repo</url>
            <snapshots>
                <enabled>true</enabled>
            </snapshots>
        </repository>

        <repository>
            <id>slick</id>
            <name>slick</name>
            <url>http://slick.cokeandcode.com/mavenrepo</url>
        </repository>
    </repositories>

    <dependencies>
        <dependency>
            <groupId>org.lwjgl.lwjgl</groupId>
            <artifactId>lwjgl</artifactId>
            <version>${lwjgl.version}</version>
        </dependency>
        <dependency>
            <groupId>slick</groupId>
            <artifactId>slick</artifactId>
            <version>${slick.version}</version>
        </dependency>
        <dependency>
            <groupId>java3d</groupId>
            <artifactId>vecmath</artifactId>
            <version>1.3.1</version>
        </dependency>
        <dependency>
            <groupId>junit</groupId>
            <artifactId>junit</artifactId>
            <version>${junit.version}</version>
            <scope>test</scope>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <configuration>
                    <source>1.6</source>
                    <target>1.6</target>
                </configuration>
            </plugin>

            <plugin>
                <groupId>com.googlecode.mavennatives</groupId>
                <artifactId>maven-nativedependencies-plugin</artifactId>
                <version>${natives.version}</version>
                <executions>
                    <execution>
                        <id>unpacknatives</id>
                        <phase>generate-resources</phase>
                        <goals>
                            <!--suppress MavenModelInspection (this line is for IDEA)-->
                            <goal>copy</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>
</project>

You'll notice I've added some extra dependencies like Slick2D and java3d's vecmath package. If you don't want or need them, feel free to delete them. There's also a plugin defintion for "mavennatives", which is really handy for LWJGL projects, so you'll want to keep it there.

Step 4: Edit and Run

At this point, edit your source files, which should live under src/main/java. Add unit tests under src/test/java if desired. For executing from the command line, you need one last setup item, and that's to set the MAVEN_OPTS environment variable:

windows: set MAVEN_OPTS="-Djava.library.path=target/natives"   
   unix: export MAVEN_OPTS=-Djava.library.path=target/natives

When you've done that, you can run your example:

mvn compile exec:java -Dexec.mainClass=my.package.MainClass

In your IDE, you need to set your java.library.path variable the same as you would for an LWJGL project without maven. Just set it to target/natives under your project root.

Troubleshooting

Native Libraries can't be found

Make sure the target/natives directory exists! If it doesn't, run mvn package which should create it.

Make sure you set your java.library.path as given above. If you're using an IDE, you need to add it to your launch settings as described in the setup guides on this wiki. If you're launching from the command line, make sure you set MAVEN_OPTS as given in Step 4 (note that -Djava.library.path does not work as a normal vm argument in maven's exec:java goal, and you must use MAVEN_OPTS instead).