Moxie

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

name Name of the project
description description of the project
organization organization sponsoring development of the project
organizationUrl url of the organization sponsoring the project
issuesUrl url of the issue tracker for the project
forumUrl url of the forum or discussion group for the project
blogUrl url of the blog for the project
socialNetworkUrl url of the social network profile for the project
ciUrl url of the continuous integration server for the project
url url of the project web site
inceptionYear year the project was founded
releaseVersion current stable release
releaseDate current 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/moxie.git'
  developerConnection: 'scm:git:https://github.com/gitblit/moxie.git'
  url: 'http://gitblit.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: 'http://repo1.maven.org/maven2' }
- { id: 'mavencentral', url: 'http://repo1.maven.org/maven2' }
- { id: 'codehaus', url: 'http://repository.codehaus.org' }
- {
    id: 'sonatype-oss'
    url: 'https://oss.sonatype.org/content/groups/public'
    # Snapshot Purge Policy
    revisionRetentionCount: 1
    revisionPurgeAfterDays: 0
  }
- { 
    id: 'restlet'
    url: 'http://maven.restlet.org'
    # 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'
    }
}

name	Name of the project
description	description of the project
organization	organization sponsoring development of the project
organizationUrl	url of the organization sponsoring the project
issuesUrl	url of the issue tracker for the project
forumUrl	url of the forum or discussion group for the project
blogUrl	url of the blog for the project
socialNetworkUrl	url of the social network profile for the project
ciUrl	url of the continuous integration server for the project
url	url of the project web site
inceptionYear	year the project was founded
releaseVersion	current stable release
releaseDate	current stable release date