Menu
▾
▴
[Maven-plugins-cvs] cvs commit: maven-plugins/uberdist/xdocs changes.xml faq.fml goals.xml index.xml navigation.xml properties.xml tags.xml
|
From: Eric G. <ri...@us...> - 2005-03-02 17:46:54
|
rikgig 05/03/02 09:46:46
Added: uberdist/xdocs changes.xml faq.fml goals.xml index.xml
navigation.xml properties.xml tags.xml
Log:
First commit.
Moved from uber-dist sf project.
Revision Changes Path
1.1 maven-plugins/uberdist/xdocs/changes.xml
Index: changes.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!--
/*
* Copyright 2001-2004 The Apache Software Foundation.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
-->
<document>
<properties>
<title>Uberdist plugin changes</title>
<author email="ri...@us...">Eric Giguere</author>
</properties>
<body>
<release version="1.0.10" date="2005-01-03">
<action dev="rikgig" type="add">First public version of the plugin</action>
</release>
<!-- -->
<release version="1.0.4" date="2004-09-10">
<action dev="rikgig" type="add">Starting from this one, uber-dist now take full control on dependencies deployment.
Including, renaming the jar (to remove version if necessary), customizable output directory,
all from the project.xml entries.</action>
</release>
</body>
</document>
1.1 maven-plugins/uberdist/xdocs/faq.fml
Index: faq.fml
===================================================================
<?xml version="1.0" encoding="ISO-8859-1"?>
<faqs title="Frequently Asked Questions">
<part id="General">
<title>General</title>
<faq id="register-project">
<question>How do I register my project with UberDist to get my distribution goal called?</question>
<answer>
Until a custom tag is integrated in the plugin (like report plugin for example), you must call
the registerProject tag from the UberDist taglib. The snippit below shows an example:<br/>
Note that the property gets are "optionnal" at this point but doing it there allows you to use them freely in your maven script while building
your distribution.<br/>
<source>
<![CDATA[
<postGoal name="uber-dist:init">
<udist:registerProject name="${pom.id}" description="My distribution"/>
<maven:get plugin="maven-uberdist-plugin"
property="maven.uber.dist.assembly.dir" var="dist.assembly.dir" />
<maven:get plugin="maven-uberdist-plugin"
property="maven.uber.dist.dir" var="distribution_dir" />
</postGoal>]]>
</source><br/>
Using the ${pom.id} is a very good practice. This is the value that will be used as default when the tag will be available.
This name is then used as
</answer>
</faq>
<faq id="create-distribution">
<question>How do I create my distribution with UberDist?</question>
<answer>
You have to add a goal in your project named: [registered_name]:prepare-dist-filesystem.
where [registered_name] is the name you supplied when registering with the plugin.
</answer>
</faq>
</part>
</faqs>
1.1 maven-plugins/uberdist/xdocs/goals.xml
Index: goals.xml
===================================================================
<?xml version="1.0" encoding="ISO-8859-1"?>
<document>
<properties>
<title>uberdist Plugin Goals</title>
<author email="ri...@ya...">dIon Gillard</author>
</properties>
<body>
<goals>
<goal>
<name>uber-dist:init</name>
<description>
This goal is provided to give a hook on project developpers to add a preGoal so that<br/>
the project registers itself with the plugin.<br/>
It also checks for make an OS check to to customize the tar call so that<br/>
file access rights are kept in the tarball if building un Unix or Solaris<br/>
</description>
</goal>
<goal>
<name>uber-dist:make</name>
<description>
This goal make a distribution. It starts from the existing target files
and from the existing distribution assembly. Some files may be out of date but its way
faster that a complete rebuild.
</description>
</goal>
<goal>
<name>uber-dist:build</name>
<description>
This goal is used to create from scratch a binary distribution. Like make, it will build
the distribution assembly in the dist-assembly dir (under target) but unlike uber-dist:make, this goal
calls the goal clean-dist-filesystem before any other goal.
</description>
</goal>
<goal>
<name>uber-dist:prepare-dist-filesystem</name>
<description>
TBD
</description>
</goal>
<goal>
<name>uber-dist:clean-dist-filesystem</name>
<description>
TBD
</description>
</goal>
<goal>
<name>uber-dist:create-distrib</name>
<description>
TBD
</description>
</goal>
<goal>
<name>uber-dist:dist-setup</name>
<description>
TBD
</description>
</goal>
<goal>
<name>uber-dist:clean-dist</name>
<description>
TBD
</description>
</goal>
<goal>
<name>uber-dist:copy-deps</name>
<description>
TBD
</description>
</goal>
<goal>
<name>uber-dist:make-executable</name>
<description>
TBD
</description>
</goal>
<goal>
<name>uber-dist:copy-scripts</name>
<description>
TBD
</description>
</goal>
</goals>
</body>
</document>
1.1 maven-plugins/uberdist/xdocs/index.xml
Index: index.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<title>Overview</title>
</properties>
<body>
<section name="Maven UberDist Plugin ">
<subsection name="Plugin Overview and Documentation map">
<p>
Why another distribution plugin?
</p>
<p>
Some software systems are made of many artifacts and may require an aggregation of many <br/>
"external" components or third parties to have a complete distribution.<br/>
In a production environment, deployment rules may be very strict and software teams may have<br/>
to follow script prescribe procedures on how and where their system should be installed, especially<br/>
on Unix environments where proper file rights attribution are crutial.<br/>
This work environment being very specific in nature, the one fits all rule doesn't apply here and building<br/>
the distribution becomes an complex task in itself.<br/>
</p>
<p>
The goal of the UberDist plugin is to integrate the basic mechanism of having a custom goal called to<br/>
build this specific complex distribution. But, it also automates some recurring tasks and most of all leverages<br/>
the enormous amout of available facilities provided by the Maven build environment to give better control<br/>
on the deployment file structure.
</p>
<table>
<tr><th>Document</th><th>Description</th></tr>
<tr><td><a href="goals.html">Goals</a></td>
<td>
Document listing all callable and internal goals of the UberDist maven plugin.
</td>
</tr>
<tr><td><a href="tags.html">Tags</a></td>
<td>
The UberDist plugin defines Jelly tags to perform some basic
operations. These tags are listed and explained in this document.
</td>
</tr>
<tr><td><a href="properties.html">Properties</a></td>
<td>
The behavior of the Maven UberDist Plugin can be altered as many plugins
via several properties. This document describes each property
available, and the default values used if none are supplied in the project.
</td>
</tr>
<tr><td><a href="faq.html">FAQs</a></td>
<td>
Question and answers to get you up and running in no time!
</td>
</tr>
</table>
</subsection>
<subsection name="UberDist Process">
<p>
UberDist with results of maven a project compilation but not in the location they are generated at.<br/>
The plugin uses 2 directories that are defined by properties:
<ul>
<li>Distribution-assembly directory: Where the distribution is built: <a href="./properties.html#maven.uber.dist.assembly.dir">maven.uber.dist.assembly.dir</a></li>
<li>Distribution directory: Where final distribution (tar or zip) file is produced: <a href="./properties.html#maven.uber.dist.dir">maven.uber.dist.dir</a></li>
</ul>
</p>
<p>
When one of the distribution building goal is called (either one of <a href="./goals.html#uber-dist:make">uber-dist:make</a>, <a href="./goals.html#uber-dist:build">build</a> or <a href="./goals.html#uber-dist:prepare-dist-filesystem">prepare-dist-filesystem</a>),
the plugin will call its internal init goal ( uber-dist:init ). Util a custom tag is supplied, writing a postGaol to this one is the prefered way to register
a distribution to be built with the plugin. Its very similar to the xdoc plugin in behavior. It allows building many seperate distribution from a same project.
</p>
<p>
Once your project is registered, UberDist prepares the necessary directories, based on its property values.<br/>
Now comes the time to copy all necessary files in the distribution assembly. UberDist will first call YOUR
distribution goal. To do this, it uses the name your registered with (typically ${pom.artifactId} makes a perfect name)
appended with ':prepare-dist-filesystem'.<br/>
Ex.: For a a maven project with id: <strong>myproject</strong>, the goal <strong>myproject:prepare-dist-filesystem</strong> will be called.
</p>
<p>
Then, the plugin will call a list of internal goals designed to help you building your distribution with minimum
jelly code added in your project.<br/>
<ol>
<li><a href="./goals.html#uber-dist:copy-deps">uber-dist:copy-deps</a> : to copy project dependencies like artifact does but with a little more control</li>
<li><a href="./goals.html#uber-dist:copy-scripts">uber-dist:copy-scripts</a> : to copy launch scripts (batch file, bash,etc) with filtering</li>
<li><a href="./goals.html#uber-dist:make-executable">uber-dist:make-executable</a> : For Unix platforms, to make some files executable</li>
</ol>
And final step, creating the tarball (Unix) or the zip file (Windows).<br/>
For more details, please see the Goals, Properties and FAQ pages.<br/>
Happy Distributing!
</p>
</subsection>
</section>
</body>
</document>
1.1 maven-plugins/uberdist/xdocs/navigation.xml
Index: navigation.xml
===================================================================
<?xml version="1.0" encoding="ISO-8859-1"?>
<project name="Maven uberdist Plugin">
<title>Maven uberdist Plugin</title>
<body>
<links>
<item name="Maven" href="http://maven.apache.org/"/>
</links>
<menu name="Overview">
<item name="Goals" href="/goals.html"/>
<item name="Tags" href="/tags.html" />
<item name="Properties" href="/properties.html"/>
<item name="FAQs" href="/faq.html"/>
</menu>
</body>
</project>
1.1 maven-plugins/uberdist/xdocs/properties.xml
Index: properties.xml
===================================================================
<?xml version="1.0" encoding="ISO-8859-1"?>
<document>
<properties>
<title>Properties</title>
</properties>
<body>
<section name="Maven UberDist Plugin Properties">
<table>
<tr>
<th>Property name</th>
<th>Description</th>
<th>Optional?</th>
</tr>
<tr>
<td>maven.uber.dist.assembly.root</td>
<td>
The directory under the project's target dir under which the files that builds
up the distribution should be copied to. It is also called the distribution assembly dir.<br/>
<i>maven.uber.dist.assembly.root=${maven.build.dir}/dist-assembly</i>
<br/>
</td>
<td>No</td>
</tr>
<tr>
<td>maven.uber.dist.dir</td>
<td>
The directory under the project's target dir
where the plugin puts the final distribution: tarball or zip
files based on the OS under which it is created.
<br/>
<i>maven.uber.dist.dir=${maven.build.dir}/distributions</i>
<br/>
</td>
<td>No</td>
</tr>
<tr>
<td>maven.uber.dist.proj.subdir</td>
<td>
Specifies the sub-directory under the distribution assembly
dir where the files for this project should be kept.
This is necessary only if you are in a multiproject
environment with seperate distributions.
<br/>
See the <a href="protocols.html">the list</a> of supported protocols.
<br/>
</td>
<td>No</td>
</tr>
<tr>
<td><a name="maven.uber.dist.assembly.dir">maven.uber.dist.assembly.dir</a></td>
<td>
This property holds the directory where the distribution assembly is.
By default, it is made of the concatenation of root dir followed
by project sub-dir if any.
<i>maven.uber.dist.assembly.dir=${maven.uber.dist.assembly.root}/${maven.uber.dist.proj.subdir}</i>
</td>
<td>No</td>
</tr>
<tr><td>Autres a finir:</td>
<td>maven.uber.dist.assembly.dep.subdir=
maven.uber.dist.executable.permission=gu+x
maven.uber.dist.executable.includes=**/*.sh,**/*.so
maven.uber.dist.launch.scripts=*.sh,*.cmd,*.bat
</td></tr>
</table>
</section>
<section name="Other properties used">
<p>
If you are behind firewall and need to use proxy server see
<a href="http://maven.apache.org/reference/user-guide.html#Using Proxies">following</a>
section from the <b>Maven User Guide</b> .
</p>
</section>
</body>
</document>
1.1 maven-plugins/uberdist/xdocs/tags.xml
Index: tags.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<title>Tags</title>
<author email="ri...@ya...">Eric Giguere</author>
</properties>
<body>
<section name="Overview">
<p>
This document describes the
<a href="http://jakarta.apache.org/commons/jelly/tags.html">tags</a>
that are available when using the Maven Uberdist Plug-in.
</p>
</section>
<section name="Tags">
<table>
<tr><th>Name</th><th>Description</th></tr>
<tr>
<td><a href="#uber-dist:copyScripts">uber-dist:copyScripts</a></td>
<td>Copies launch scripts to a specified directory</td>
</tr>
<tr>
<td><a href="#uber-dist:registerProject">artifact:deploy-snapshot</a></td>
<td>Add a project to the distribution list to be built.</td>
</tr>
<tr>
<td><a href="#uber-dist:deregisterProject">uber-dist:deregisterProject</a></td>
<td>Removes a project from the distribution list to build</td>
</tr>
</table>
<subsection name="uber-dist:copyScripts">
<p>
Copies launch scripts to a specified directory.
<br/>
The files located in directory with matching pattern as described by
property <a href="./properties.html#maven.uber.dist.launch.scripts">
maven.uber.dist.launch.scripts</a> are copied<br/>
using Ant filtering mechanism with default @artifact_id@ token replaced<br/>
by the current's project artifact id.<br/>
The default value for the file pattern is: <code>*.sh,*.cmd,*.bat</code>
</p>
<table>
<tr>
<th>Attribute Name</th><th>Description</th><th>Optional?</th>
</tr>
<tr>
<td>scriptsDirectory</td>
<td>The path to the destination directory under the distribution assembly root</td>
<td>No</td>
</tr>
</table>
</subsection>
<subsection name="uber-dist:registerProject">
<p>
Register a project with uberdist plugin to get the complex distribution built.
<br/>
NOTE: It is necessary to use this tag before calling any distribution goal so that<br/>
the plugin will be able to call the custom file copy goal in your project.<br/>
</p>
<table>
<tr>
<th>Attribute Name</th><th>Description</th><th>Optional?</th>
</tr>
<tr>
<td>name</td>
<td>The name of the distribution to build</td>
<td>No</td>
</tr>
</table>
</subsection>
<subsection name="uber-dist:deregisterProject">
<p>
Removes a project from the list of distribution to be built.
<br/>
</p>
<table>
<tr>
<th>Attribute Name</th><th>Description</th><th>Optional?</th>
</tr>
<tr>
<td>name</td>
<td>The name of the distribution to remove from build list</td>
<td>No</td>
</tr>
</table>
</subsection>
</section>
</body>
</document>
|
