Maven: The Complete Reference

13.2. Configuring Build Environment for Flexmojos

Before you attempt to compile Flex libraries and applications with Maven, you will need to complete two configuration tasks:

  • Configure your Maven settings to reference a repository which contains the Flex framework
  • Add the Flash Player to your PATH to support Flex unit testing
  • (Optional) Configure your Maven Settings to include the Sonatype plugin group

13.2.1. Referencing a Repository with the Flex Framework

To setup your Maven environment for Flexmojos, you have two options: you can reference the Sonatype Flexmojos repository directly in a pom.xml, or you can install Nexus and add the Sonatype Flexmojos repository as a proxy repository in your own repository manager. While the most straightforward option is to reference the repository directly, downloading and installing Nexus will give you the control and flexibility you need to cache and manage artifacts generated by your own build. If you are just interested in getting up and running with Flexmojos, read the section called “Referencing Sonatype’s Flexmojos Repository in a POM” next. If you are interested in a long-term solution which can be deployed to support a development team, continue to the section called “Proxying Sonatype’s Flexmojos Repository with Nexus”.

Note

If your organization is already using Sonatype Nexus to proxy remote repositories, you may already have customized your ~/.m2/settings.xml file to point to a single Nexus group. If this is your situation, you should add a Proxy repository for the Sonatype Flexmojos repository group at ${flexmojos.repository}[${flexmojos.repository}]. Add this new repository to the Nexus Repository Group that is referenced by your development team. Adding a proxy repository for this remote group and then adding this group to your Nexus installation’s public repository group will give clients of your Nexus instance access to the artifacts from the Sonatype repository.sonatype.org Nexus instance.

Referencing Sonatype’s Flexmojos Repository in a POM

Flexmojos depends on a few artifacts which are not currently available from the Central Maven repository. These artifacts are available from a Repository hosted by Sonatype. To use Flexmojos, you will need to reference this repository from your project’s pom.xml. To do this, add the repositories element shown in Adding a Reference to Sonatype’s FlexMojos Repository in a POM to your project’s pom.xml.

Adding a Reference to Sonatype’s FlexMojos Repository in a POM. 

<project>
    <modelVersion>4.0.0</modelVersion>
    <groupId>test</groupId>
    <artifactId>test</artifactId>
    <version>1.0-SNAPSHOT</version>
    <packaging>pom</packaging>

    <modules>
        <module>swc</module>
        <module>swf</module>
        <module>war</module>
    </modules>

    *<repositories>
        <repository>
            <id>flexmojos</id>
            <url>${flexmojos.repository}</url>
        </repository>
    </repositories>*

</project>

The XML shown in Adding a Reference to Sonatype’s FlexMojos Repository in a POM, will add this repository to the list of repositories Maven will consult when it attempts to download artifacts and plugins.

Proxying Sonatype’s Flexmojos Repository with Nexus

Instead of pointing directly at the Sonatype Flexmojos repository, Sonatype recommends that you install a repository manager and proxy the Sonatype public repository. When you proxy a remote repository with a repository manager such as Nexus, you gain a level of control and stability not possible when your build relies directly on external resources. In addition to this control and stability, a repository manager also provides you with an deployment target for binary artifacts generated by your own builds. For instructions on downloading, installing, and configuring Nexus, refer to the Installation chapter in Repository Management with Nexus.

13.2.2. Configure a Flexmojos Proxy Repository in Nexus

Once Nexus is installed and started, complete the following steps to add a proxy repository for the Sonatype public repository. To add a new proxy repository:

  1. Click on the Repositories link under Views/Repositories in the Nexus menu on the left-hand side of the Nexus user interface.
  2. Click on Repositories to load the Repositories panel.
  3. In the Repositories panel, click on the Add.. button and select Proxy Repository as shown in Figure 13.1, “Adding a Proxy Repository to Sonatype Nexus”.
figs/web/flex-dev-nexus-add-proxy.png

Figure 13.1. Adding a Proxy Repository to Sonatype Nexus


Once you’ve created a new Proxy repository, you will need to configure it to point to the Sonatype Flexmojos repository.

  1. Select the new repository, and then
  2. Select the Configuration tab in the lower half of the window.
  3. Populate the following field with the values shown in Figure 13.2, “Configuring the Sonatype Flexmojos Proxy Repository”.

    1. <itemizedlist> Repository ID is "sonatype-flexmojos"
    2. Repository Name is "Sonatype Flexmojos Proxy"
    3. The Remote Storage Location is ${flexmojos.repository}[${flexmojos.repository}]
figs/web/flex-dev-nexus-sonatype-proxy.png

Figure 13.2. Configuring the Sonatype Flexmojos Proxy Repository


Once you have populated the fields shown in Figure 13.2, “Configuring the Sonatype Flexmojos Proxy Repository” click the Save button to save the proxy repository and start proxying the Sonatype Flexmojos repository.

Add the Flexmojos Proxy Repository to a Group

Nexus ships with a public repository group, which combines several repositories into a single URL for Maven clients. Add this new Flexmojos proxy repository to the Nexus public group. To do this:

  1. Return to the list of repositories which should now be visible in the upper half of the Repositories panel as shown in Figure 13.2, “Configuring the Sonatype Flexmojos Proxy Repository”.
  2. Click on the Public Repositories group, and then
  3. Click on the Configuration tab in the lower half of the Repository panel. Clicking the Configuration tab will expose the Group configuration form shown in Figure 13.3, “Adding the Sonatype Flexmojos Proxy to the Public Repositories Group”.
figs/web/flex-dev-nexus-sonatype-to-group.png

Figure 13.3. Adding the Sonatype Flexmojos Proxy to the Public Repositories Group


  1. To add the Sonatype Public Proxy to the Public Repositories group simply drag and drop the Sonatype Public Proxy repository from the Available Repositories list to the Ordered Group Repositories list.
  2. Click Save, and you have successfully added a proxy of the Sonatype Flexmojos repository to your Nexus installation.

Whenever a client requests an artifact from this repository group, if Nexus has not already cached a matching artifact, it will query the Sonatype Flexmojos repository at ${flexmojos.repository}[${flexmojos.repository}]. Your Nexus installation will maintain a local cache of all artifacts retrieved from the Sonatype Flexmojos repository. This local cache gives you more control and contributes to a more stable build environment. If you are setting up a group of developers to rely upon artifacts from the Sonatype public repository, you’ll have a completely self-contained build environment that won’t be subject to the availability of the Sonatype repository once the necessary artifacts have been cached by your Nexus instance.

Configure Your Development Environment for Nexus

The final step is connecting your Maven installation to the Nexus instance you just configured. You will need to update your Maven Settings to use your Nexus repository group as a mirror for all repositories. To do this, you need to put the following XML in your ~/.m2/settings.xml file.

Settings XML for Local Nexus Instance. 

<settings>
    <mirrors>
        <mirror>
            <!--This sends everything else to /public -->
            <id>nexus</id>
            <mirrorOf>*</mirrorOf>
            <url>http://localhost:8081/nexus/content/groups/public</url>
        </mirror>
    </mirrors>
    <profiles>
        <profile>
            <id>nexus</id>
            <!--all requests to nexus via the mirror -->
            <repositories>
                <repository>
                    <id>central</id>
                    <url>http://central</url>
                    <releases><enabled>true</enabled></releases>
                    <snapshots><enabled>true</enabled></snapshots>
                </repository>
            </repositories>
            <pluginRepositories>
                <pluginRepository>
                    <id>central</id>
                    <url>http://central</url>
                    <releases><enabled>true</enabled></releases>
                    <snapshots><enabled>true</enabled></snapshots>
                </pluginRepository>
            </pluginRepositories>
        </profile>
    </profiles>
    <activeProfiles>
        <activeProfile>nexus</activeProfile>
    </activeProfiles>
</settings>

This XML file configures Maven to consult a single public repository group for all configured repositories and plugin repositories. It is a simple way to guarantee that every request for an artifact is made through your Nexus installation.

13.2.3. Configuring Environment to Support Flex Unit Tests

Flexmojos expects to be able to launch the stand-alone Flash Player to execute unit tests. In order for this to work, you will need to add the stand-alone Flash Player to your PATH, or you will need to pass the location of the Flash Player executable to your build using the -DflashPlayer.command options. When executing a unit test, Flex Mojos expects to launch the following platform-specific executables for the stand-alone Flash Player:

Microsoft Windows
FlexMojos will attempt to launch the FlashPlayer.exe binary. To support execution of unit tests, add the directory containing FlashPlayer.exe to your PATH or pass in the location of the FlashPlayer.exe binary to Maven using the
Macintosh OSX
FlexMojos will attempt to launch the "Flash Player" application. To support the execution of unit tests, add the directory containing "Flash Player" to your PATH or pass the path to the executable to option.
Unix (Linux, Solaris, etc.)
FlexMojos will attempt to launch the flashplayer executable. To support the execution of unit tests, add the directory containing flashplayer to your PATH or pass the path to the executable to option.

Note

On a Linux machine, you will need to have X virtual framebuffer (Xvfb) installed to run unit tests in a headless build. For more information about Xvfb, click here.

If you have been developing Flash Applications with Adobe Flash CS4 or Adobe Flex Builder or if you have been viewing flash content in a browser, you probably have the Flash Player installed somewhere on your workstation. While it is possible to configure Maven to use one of these players for Flex unit tests, you’ll want to make sure that you are running the debug version of the Flash Player. To minimize the potential for incompatibility, you should download one of the Flash Player’s listed below and install it on your local workstation. To download the standalone Flash Player for you environment:

To install this player and add it to your PATH on an OSX machine, run the following commands:

$ wget http://download.macromedia.com/pub/flashplayer/updaters/10/\
       flashplayer_10_sa_debug.app.zip
$ unzip flashplayer_10_sa_debug.app.zip
$ sudo cp -r Flash\ Player.app /Applications/
$ export PATH=/Applications/Flash\ Player.app/Contents/MacOS:${PATH}

Instead of adding the path for the Flash Player to your PATH on the command-line, you should configure your environment to automatically configure these variables. If you are using bash, you would add the last export command to your ~/.bash_profile.

13.2.4. Adding FlexMojos to Your Maven Settings' Plugin Groups

If you need to run FlexMojos goals from the command-line, it will be more convenient if you add the Sonatype Plugin groups to your Maven Settings. To do this, open up ~/.m2/settings.xml and add the following plugin groups:

Adding Sonatype Plugins to Maven Settings. 

<pluginGroups>
    <pluginGroup>com.sonatype.maven.plugins</pluginGroup>
    <pluginGroup>org.sonatype.plugins</pluginGroup>
</pluginGroups>

Once you’ve added these plugin groups to your Maven Settings you can invoke a FlexMojos goal using the plugin prefix flexmojos. Without this configuration, calling the flexbuilder goal would involve the following command-line:

$ mvn org.sonatype.flexmojos:flexmojos-maven-plugin:${flexmojos.version}:flexbuilder

With the org.sonatype.plugins group in your Maven settings, the same goal can be invoked with:

$ mvn flexmojos:flexbuilder