 |
CC's Build System
Other Information
| Maven Definitions |
| Jelly Scripting Hints |
Repository Building
Now that we have covered some of the basics of Maven, I'll describe the way the Maven creates repositories. When I refer to Maven repositories, I am generally refering to the output of a Maven deployment, of which there are a few different types. Since CC is an open source company, we have a publically accessible repository of documentation, source, and binary distributions, as well as jnlp distributions and custom Maven plugins.Repository Structure
Repositories have a very specific directory structure that requires naming conventions for artifacts to be strictly adhered to. Basically, source, binary, plugin, and pom distributions, as well as CC's jnlp distributions, are deployed to <RepoRoot>/groupId on a remote server in their own directory, so if you had a project that did all of those deployments, you would end up with the following directory structure:[eblack@ubuntu eblack]$ ls -al repository/test/
total 24
drwxr-sr-x 6 maven maven 4096 May 23 16:57 .
drwxr-sr-x 9 maven maven 4096 May 31 16:55 ..
drwxr-sr-x 2 maven maven 4096 May 28 16:59 distributions
drwxr-sr-x 2 maven maven 4096 May 28 16:59 jars
drwxr-sr-x 2 maven maven 4096 May 28 16:59 jnlp
drwxr-sr-x 2 maven maven 8192 May 28 16:59 plugins
drwxr-sr-x 2 maven maven 4096 May 28 16:59 poms
[eblack@ubuntu eblack]$
In the above listing, the groupId is 'test'. Normally, the groupId would be something like the organization name, so if CC's repository would be distributed through the Maven repository on Ibiblio, the groupId should most likely be 'concord' for CC projects. We currently have the groupId the same as the project name to retain the legacy directory structure that was used in earlier CC projects. Changing the groupId is not any more difficult than changing the project.xml files for the artifact being built and for any projects that depend on it.
The directory structure will be created below the <RepoRoot> directory level if the user has permissions to do so. The 'jars', 'jnlp', and 'plugins' directory names are derived from the deployment plugin that you used: jar:deploy, ccjnlp:deploy, or plugin:repository-deploy respectively. The 'distributions' directory name is for the source code distribution using the dist:deploy-src goal. The end result of these deployments are files in the form:
<RepoRoot>/groupId/artifactType/artifactId-{currentVersion/SNAPSHOT}.extension
In the above file name format, I have already described what groupId and artifactType are. The artifactId is essentially the output filename without the version. GroupId, artifactId, and currentVersion are specified in the POM (project.xml) file. ArtifactType, and extension are determined by the goal that is run against the POM. To get a version of 'SNAPSHOT', you would specify the snapshot version of the deploy goal, such as dist:deploy-src-snapshot or jar:deploy-snapshot. Snapshot means the latest version of the source files, and in the case of dependencies, snapshot versions will be downloaded everytime Maven is run, whereas specific versions will be downloaded only when the version is not in the local repository.
There are required properties or pom elements that need to be set for the deployment goals. For the dist plugin, <distributionSite> and <distributionDirectory> pom elements must be set. For the jar deployment, the following properties must be set:
For the downloading of dependencies:
maven.repo.remote=http://www.ibiblio.org/maven/,http://source.concord.org/repository/
For the uploading of jar files, this is the new form of properties:
maven.repo.list=LOCAL
maven.repo.LOCAL=scpexe://source.concord.org
maven.repo.LOCAL.username=maven
maven.repo.LOCAL.directory=/web/source.concord.org/html/software/repository
In the above example, 'LOCAL' is a special name that allows the dereferencing of the associated variables shown. maven.repo.list is a list of qualifying names seperated with a comma. If this form is not used, the old type of deployment is used and the md5 files are not created in the repository.
For ccJnlp:
serverDir=/web/source.concord.org/html/software/repository
ccJnlp.remote.path=${serverDir}/${pom.groupId}/jnlp
serverDir is not used by the plugin, but allowed me to change the ccJnlp.remote.path property without having to know the groupId for all projects when running multiproject goals.
Site Documentation
The site documentation is deployed from running the site:deploy goal. The pom directives and project properties are slightly different for the site documentation. Where the other deploy goals use the <distributionSite> and <distributionDirectory> pom elements, <siteAddress> and <siteDirectory> are used for the site goals.Our project site documentation is the default output. The only customization was the <organization> tags that I added to the inherited project.xml file:
<organization>
<name>The Concord Consortium</name>
<url>http://www.concord.org</url>
<logo>http://www.concord.org/global-images/small_trans_logo_75.gif</logo>
</organization>
And the mailing list info stubs, that can be overridden in the child projects.
<mailingLists>
<mailingList>
<name>${pom.name} Dev List</name>
</mailingList>
<mailingList>
<name>${pom.name} User List</name>
</mailingList>
</mailingLists>
Putting the organization information provides a linked image at the top left of the web pages and a copyright label in the bottom right.
The site documents are xhtml generated from xml documentation. The customization information is very limited at the moment, but it is helpful to view the XDoc plugin FAQ's and the Site plugin docs for basic info. The basic site generation will include a blank index page, a header, and a framework of menus on the left. Stub pages will be created for the mailing lists, member lists, and dependencies. A number of reports are also generated, including JDepend metrics pages and a Java programing checkstyle report that checks against a specified coding styles(the default is Sun's code style) or a new code style can be defined. The most useful documents are, of course, the JavaDocs.
The site can be customized through xml docs, as I stated above, that are transferred to xhtml. See the Maven site usage page for some basic hints. I think the reason that much of the Maven documents and plugin docs might be scarce on content is unenjoyable aspect of coding web docs in xml. I don't know of any WYSIWYG editors that output xml, but I'm sure some do export xml. Anyway, Maven provides the framework, the developers have to add the details.