Moxie Project Descriptor

The Moxie project descriptor defines the structure, metadata, and dependencies of your project. It is the heart of Moxie and is used by all Moxie Extension tasks.

Project Artifact Data

groupId
artifactId
version

Project Metadata

nameName of the project
descriptiondescription of the project
organizationorganization sponsoring development of the project
organizationUrlurl of the organization sponsoring the project
issuesUrlurl of the issue tracker for the project
forumUrlurl of the forum or discussion group for the project
blogUrlurl of the blog for the project
socialNetworkUrlurl of the social network profile for the project
ciUrlurl of the continuous integration server for the project
urlurl of the project web site
inceptionYearyear the project was founded
releaseVersioncurrent stable release
releaseDatecurrent stable release date


Packaging

Packaging defines the target binary output of the project. This field defaults to jar, if not manually specified. The value here mostly has relevance for the mx:package task.

Valid Packaging Types

pom
jar
generates a jar file for the project
war
generates a webapp war file for the project
zip
generates a zip file of the jar, sources, and javadoc for the project
tgz
generates a tar.gz of the jar, sources, and javadoc for the project
tar.gz
generates a tar.gz of the jar, sources, and javadoc for the project
You may also append +format to the packaging to create secondary packaging for your project.
packaging: jar
packaging: jar+zip
packaging: jar+zip+tgz

Apply

Apply is used to define extra project features.
pom
creates a Maven pom.xml file
eclipse
creates and maintains Eclipse .project and .classpath files
intellij
creates and maintains IntelliJ IDEA .iml files
apply: eclipse, intellij, pom

Apply: eclipse

The Eclipse apply function supports a few switches to control Eclipse .project and .classpath file generation.
var
Creates .classpath using the MX_ROOT workspace variable. This allows you to version-control .classpath but does require the user to define an MX_ROOT workspace variable pointing to ~/.moxie or wherever they would like to establish their Moxie root.
groovy
Adds the Groovy plugin reference to .classpath and the Groovy Nature to .project.
apply: 'eclipse:+var+groovy'

Parent

In a mutl-module project setup, a module may inherit settings from a parent build.moxie descriptor by specifying it's relative location.
parent: ../build.moxie 

Licenses

You can specify the project licenses in the licenses setting. This setting is currently only used during POM generation.

licenses:
- {
    name: 'Apache ASL v2.0'
    url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
  }


Developers

You can specify the project developers in the developers setting. This setting is currently only used during POM generation.

developers:
- {
  id: james
  name: 'James Moger'
  url: 'https://plus.google.com/u/0/116428776452027956920'
  organization: 'James Moger'
  organizationUrl: 'http://www.jamesmoger.com'
  roles: developer
  }


SCM

You can specify the project SCM information in the scm setting. This setting is currently only used during POM generation.

scm: {
  connection: 'scm:git:git://github.com/gitblit-org/moxie.git'
  developerConnection: 'scm:git:https://github.com/gitblit-org/moxie.git'
  url: 'https://gitblit-org.github.com/moxie'
  tag: HEAD
  }


Registered Repositories

This section is used to define remote artifact repositories. Currently only http/https repositories are supported.

The default connectTimeout is 20 seconds.
The default readTimeout is 1800 seconds (30 mins).

Affinities

If a repository specifies one or more affinities and a dependency matches one of those affinities, that repository will be used first during dependency or metadata resolution of that artifact. This allows you to control the efficiency of the resolution process by boosting the importance of a specific repository.

In the following example, the Restlet repository has an affinity for all artifacts belonging to the org.restlet groupId. During resolution, the Restlet repository is checked first for all org.restlet.

registeredRepositories:
- { id: 'central', url: 'https://repo1.maven.org/maven2' }
- { id: 'mavencentral', url: 'https://repo1.maven.org/maven2' }
- {
    id: 'sonatype-oss'
    url: 'https://oss.sonatype.org/content/groups/public'
    # Snapshot Purge Policy
    revisionRetentionCount: 1
    revisionPurgeAfterDays: 0
  }
- { 
    id: 'restlet'
    url: 'https://maven.restlet.talend.com'
    # Snapshot Purge Policy
    revisionRetentionCount: 1
    revisionPurgeAfterDays: 0
    # Artifact affinitities
    affinity: [ 'org.restlet' ]
    # seconds to wait till connected
    connectTimeout: 20
    # seconds to wait on read
    readTimeout: 1800
    # authentication credentials
    username: 'someuser'
    password: 'mypassword'
  }


Repositories

The repositories settings defines the list of registeredRepositories from which to source artifacts. By default, only MavenCentral is specified, however Moxie ships with several other registeredRepositories including sonatype-oss, codehaus, & restlet.
repositories: 'central'

Modules

Standard Project
If the project has valid source directories, then the modules section is used to define referenced source projects. The source directories from these referenced projects are included on the sourcepath of the current project. Likewise, the dependencies of those referenced projects are included on the compile classpath of the current project.

The projects are assumed to be located relative to the current project. You may use an Ant or enviromental property as part of the module reference.

All referenced modules must have a build.moxie descriptor unless a different descriptor is manually specified with the @file syntax.

Parent Project
If the project has no source directories then the modules section is used only for IDE settings generation.
modules: 
- 'project1'
- 'project2'
- '${myprojects}/project3' @build2.moxie

Source Directories

Source directories define where to find your source code. Each source folder must specify a scope.

Valid Scopes

compile
test
site
Dependencies, source directories, and resource directories may also be tagged as belonging to a group by using the :tag syntax. Several mx tasks support these tagged subsets.
Note: Moxie only supports a single site scoped source directory.
sourceDirectories: 
- compile 'src/main/core' :mytag
- compile 'src/main/pro'
- compile 'src/main/all'
- compile 'src/client/java' :mytag
- { scope: 'test', dir: 'src/test/java' }

Resource Directories

Resource directories define where to find your resource files (images, css, etc). Each resource directory must specify a scope.

Valid Scopes

compile
test
site
Dependencies, source directories, and resource directories may also be tagged as belonging to a group by using the :tag syntax. Several mx tasks support these tagged subsets.
Note: Moxie only supports a single site scoped resource directory.
resourceDirectories: 
- compile 'src/main/resources'
- compile 'src/client/resources' :mytag
- test 'src/test/resources'
- site 'src/site/resources'

Properties

Properties can be used in the dependencyManagement and dependencies section. They are also exported to Ant as properties.
properties: {
  jgit.version : 1.3.0.201202151440-r
}

Dependency Management

Managed dependencies are used to specify versions of dependencies if those versions are not specified in the dependencies list.
dependencyManagement:
- 'org.apache.ant:ant:1.8.3'
- 'junit:junit:4.11'

Dependencies

Dependencies can be defined using Gradle-style coordinates.
groupId:artifactId:version
Each dependency must also have an assigned scope.

Valid Scopes

compile
added to the compile classpath
provided
added to the compile classpath but not distributed with project
runtime
added to the runtime classpath
test
added to the test classpath
system
added to all classpaths
build
added to Moxie's runtime classpath
Dependencies, source directories, and resource directories may also be tagged as belonging to a group by using the :tag syntax. Several mx tasks support these tagged subsets.
dependencies:
- compile 'org.apache.ant:ant'
- compile 'com.acme:widget:1.2.3' :mytag
- test 'junit'

Classifiers

Moxie supports resolution by classifier by appending the classifier to the standard artifact coordinates.
- compile 'org.apache.ant:ant.1.8.4:jdk14'

Exclusions

Sometimes it is desirable to specify exclusions from a dependency's graph. There are two ways to exclude dependencies.

@ext
The `@ext` syntax will exclude all dependencies of a dependency. To use this syntax you must specify the extension of the artifact to retrieve.
- compile 'org.apache.ant:ant.1.8.4' @jar
Discrete Exclusions
You may also specify exclusions by groupId and groupId:artifactId.
- compile 'org.apache.ant:ant.1.8.4' !commons-logging

GoogleCode Dependencies

Sometimes useful artifacts are not available from a Maven repository. Moxie supports artifact retrieval from GoogleCode using a syntax similar to Gradle-style Maven coordinates.
<googlecode>:projectName:filename
repositories: central, googlecode
dependencies:
- compile '<googlecode>:iciql:iciql-0.7.0.jar'

Dependency Directory

You may optionally specify a project-relative directory to copy dependencies to. If you decide to do this AND you are generating Eclipse or IntelliJ IDEA project files, your project files will reference these relatively located jar files.
dependencyDirectory: ext

Dependency Name Pattern

When you are using the dependencyDirectory setting you may also control the destination name of the project-relative artifacts.

dependencyNamePattern: [artifactId]-[version](-[classifier]).[ext]


Advanced Settings

These settings can be used to manipulate released POMs and/or to enable clever dependency tricks. Both of these features are used internally by Moxie.

Dependency Aliases

Dependency aliases allow you to specify shorthand notation for a dependency which will be resolved at runtime to the full coordinates.

dependencyAliases: {
	junit: 'junit:junit'
	testng: 'org.testng:testng'
	cobertura: 'net.sourceforge.cobertura:cobertura'
	emma: 'emma:emma'
	jacoco: 'org.jacoco:org.jacoco.ant'
	'mx:jgit' : 'org.eclipse.jgit:org.eclipse.jgit'
	'mx:markdownpapers' : 'org.tautua.markdownpapers:markdownpapers-core'
	'mx:rhino' : 'org.mozilla:rhino'
}

Dependency Overrides

Dependency overrides are used to redefine the dependencies of released/published POMs from other projects. The most common use case would be to add undeclared dependencies for old POMs or to purposefully exclude dependencies from specific scopes.

Moxie uses this feature to simplify specification of "build" scope dependencies so that enabling Cobertura, Emma, or TestNG is as easy as adding a single build dependency.

You must declare the full coordinates of the dependency to tweak. Property substitution is prohibited. You may specify the scopes for which your override applies. If no scope is specified ALL scopes are assumed.

Be very careful when using dependency overrides!

dependencyOverrides: {

    # cobertura: redefine ant as optional for build scope
    'net.sourceforge.cobertura:cobertura:1.9.4.1' : {
        scope: build
        dependencies:
        - compile 'oro:oro:2.0.8'
        - compile 'asm:asm:3.0'
        - compile 'asm:asm-tree:3.0'
        - compile 'log4j:log4j:1.2.9'
        - compile 'org.apache.ant:ant:1.7.0' optional
    }

    # emma: add emma_ant dependency for build scope
    'emma:emma:2.1.5320' : {
        scope: build
        dependencies:
        - compile 'emma:emma_ant:2.1.5320'
    }
}