Compiler ~ Maven Plugin

Maven Plugin

About Maven

Maven is a build tool from the Java world, but can also be used to build Flex applications or in fact any application type you want. Maven is extensible through plugins, and we provide such a plugin for Jangaroo. Using Maven is the recommended way to build your Jangaroo project.

Instead of a build.xml as known from Ant, Maven uses a file called pom.xml that contains the build information.

Jangaroo Maven Plugin

The Jangaroo Maven plugin (jangaroo-maven-plugin) calls the Jangaroo compiler and defines a Jangaroo-specific Maven packaging and dependency type. In a simple project, you will usually use war packaging (as provided by Maven) and configure the Jangaroo Maven plugin so that Jangaroo code is compiled and dependencies of type jangaroo are handled correctly.

jangaroo-maven-plugin defines several so-called Mojos (comparable to Ant's tasks) or goals. When used in a war packaging scenario, you have to execute at least the goals compile and war-package. The first compiles the ActionScript 3 sources of your module to JavaScript, the latter extracts all dependent Jangaroo libraries (at minimum the Jangaroo runtime) to the Web application output directory. The compile Mojo provides configuration options that correspond to Jangaroo's compiler command line options.

For your convenience, we repeat the pom.xml of the HelloWorld tutorial here:

<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>net.jangaroo.examples</groupId>
  <artifactId>hello-world</artifactId>
  <version>0.1.0-SNAPSHOT</version>
  <packaging>war</packaging>
  <name>hello-world</name>
  <description>A Hello World Jangaroo Application</description>

  <properties>
    <jangaroo_version>0.8.3</jangaroo_version>
    <jangaroo_libs_version>0.8.5</jangaroo_libs_version>
  </properties>

  <build>
    <sourceDirectory>src/main/joo</sourceDirectory>
    <plugins>
      <plugin>
        <groupId>net.jangaroo</groupId>
        <artifactId>jangaroo-maven-plugin</artifactId>
        <extensions>true</extensions>
        <version>${jangaroo_version}</version>
        <executions>
          <execution>
            <goals>
              <goal>compile</goal>
              <goal>war-package</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-war-plugin</artifactId>
        <version>2.1.1</version>
        <configuration>
          <failOnMissingWebXml>false</failOnMissingWebXml>
        </configuration>
      </plugin>
    </plugins>
  </build>

  <dependencies>
    <dependency>
      <groupId>net.jangaroo</groupId>
      <artifactId>jangaroo-browser</artifactId>
      <version>${jangaroo_libs_version}</version>
      <type>jangaroo</type>
    </dependency>
  </dependencies>
</project>

Let me walk you through this file:

Besides the usual Maven settings, we define properties for the Jangaroo tools and libraries versions. This makes it easier to update the POM when you want to move to a newer version. Note that these versions are similar, but should not be confused! The first version is for the compiler, the Maven plugin and the Runtime, while the second version is for all other Jangaroo libraries, like jangaroo-browser or jooflash.

Then, you have to configure the special Jangaroo source directory. While the compiler knows about it by default, you should still tell Maven about it, so that e.g. the plugin that creates a -sources.jar artifact also works.

Next is the declaration of the Jangaroo Maven plugin. Maven plugins, like every Maven artifact, are referenced by a groudId together with an artifactId and a version. Mind to set extensions to true for the Jangaroo lifecycle extension and dependency type to be effective! The plugin is supposed to execute the goals compile and war-package.

The second plugin configuration of maven-war-plugin is unfortunately necessary to avoid complaints about a missing web.xml file.

Then we have exactly one dependency, namely jangaroo-browser, which provides an ActionScript 3 view of the browser DOM and BOM APIs. This library is needed by almost every Jangaroo project and also provides an implicit dependency on jangaroo-runtime, which is always needed. So if you do not use jangaroo-browser, be sure to replace it by a dependency to jangaroo-runtime. Note that jangaroo-runtime must be used in version ${jangaroo_version}, not ${jangaroo_libs_version}, since it is released together with the compiler, not with the libraries!

To build the project, run mvn package in the directory containing pom.xml. Obviously, a working Maven 3 installation is required to do so. This compiles the *.as files into *.js files and assembles these and all Web resources in the folder target/hello-world-0.1.0-SNAPSHOT. Open index.html in any browser and be exited about the beautiful line of text that appears as by magic!

The Web application is also packaged into a *.war file in the target folder, which is just a zip archive of the folders and files to deploy to your Web space.