commons-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From nia...@apache.org
Subject svn commit: r922302 - /commons/proper/commons-site/src/site/xdoc/commons-parent-pom.xml
Date Fri, 12 Mar 2010 15:56:37 GMT
Author: niallp
Date: Fri Mar 12 15:56:37 2010
New Revision: 922302

URL: http://svn.apache.org/viewvc?rev=922302&view=rev
Log:
Add a page about the commons-parent pom.xml

Added:
    commons/proper/commons-site/src/site/xdoc/commons-parent-pom.xml   (with props)

Added: commons/proper/commons-site/src/site/xdoc/commons-parent-pom.xml
URL: http://svn.apache.org/viewvc/commons/proper/commons-site/src/site/xdoc/commons-parent-pom.xml?rev=922302&view=auto
==============================================================================
--- commons/proper/commons-site/src/site/xdoc/commons-parent-pom.xml (added)
+++ commons/proper/commons-site/src/site/xdoc/commons-parent-pom.xml Fri Mar 12 15:56:37 2010
@@ -0,0 +1,427 @@
+<?xml version="1.0"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements.  See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You 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>Commons Parent pom.xml</title>
+ </properties>
+
+  <body>
+
+    <section name="commons-parent">
+
+      <p>
+        This page provides information about the
+        <a href="http://svn.apache.org/repos/asf/commons/proper/commons-parent/trunk/pom.xml">commons-parent</a>
+        <code>pom.xml</code>
+      </p>
+
+      <p>
+        Commons <a href="/components.html">components</a> use <a href="http://maven.apache.org/">Maven</a>
as their primary build
+        system and <a href="http://svn.apache.org/repos/asf/commons/proper/commons-parent/trunk/pom.xml">commons-parent</a>
+        is the <i>parent pom</i> for the components' <a href="http://maven.apache.org/">Maven</a>
build.
+      </p>
+
+      <p>
+        Using a <i>parent pom</i> reduces the build configuration required for
each individual
+        component and <i>standardizes</i> the builds accross commons components.
+      </p>
+
+      <subsection name="Build">
+        <p>
+          The following is a list of the main <i>build</i> features provided
by
+          <a href="http://svn.apache.org/repos/asf/commons/proper/commons-parent/trunk/pom.xml">commons-parent</a>:
+        </p>
+        <ul>
+          <li>
+            <strong>Reproducable Build</strong> - It is important that builds
are consistently <i>reproducible</i>
+            and in order to achieve this with Maven the same <a href="http://maven.apache.org/plugins/">Plugin</a>
+            versions need to be used each time.
+            <a href="http://svn.apache.org/repos/asf/commons/proper/commons-parent/trunk/pom.xml">commons-parent</a>
+            specifies the Plugin versions to be used in the <code>&lt;pluginManagement&gt;</code>
section.
+            <ul>
+              <li>
+                (<b>N.B.</b> the <code>&lt;reporting&gt;</code>
section ignores whats specified in the
+                <code>&lt;pluginManagement&gt;</code> section and component
pom.xml's should specify the version of
+                additional reports they specify).
+              </li>
+            </ul>
+          </li>
+          <li>
+            <strong><code>LICENSE</code> and <code>NOTICE</code>
files</strong> - automatically added to the jar files
+            produced by the build to conform with the <a href="http://www.apache.org/dev/release.html#license">ASF
License Policy</a>.
+          </li>
+          <li>
+            <strong><code>MANIFEST.MF</code> files</strong> - The
information is automatically included in the componentjar's manifest file:
+            <ul>
+              <li><code>Implementation-Title</code> - set to the component's
name</li>
+              <li><code>Implementation-Vendor</code> - set to <i>The
Apache Software Foundation</i></li>
+              <li><code>Implementation-Vendor-Id</code> - set to <code>org.apache</code></li>
+              <li><code>Implementation-Version</code> - set to the component
version</li>
+              <li><code>Specification-Title</code> - set to the component's
name</li>
+              <li><code>Specification-Vendor</code> - set to <i>The
Apache Software Foundation</i></li>
+              <li><code>Specification-Version</code> - set to the component
version</li>
+              <li><code>X-Compile-Source-JDK</code> - set to the <i>source</i>
option used by the compiler</li>
+              <li><code>X-Compile-Target-JDK</code> - set to the <i>target</i>
option used by the compiler</li>
+            </ul>
+          </li>
+          <li>
+            <strong><a href="#OSGi_Information">OSGi Enabled</a></strong>
- OSGi <i>metadata</i> is automatically
+            included in the component jar's manifest file enabling commons components to
be used in an
+            <a href="http://felix.apache.org/">OSGi container</a>. The following
manifest entries are generated by
+            default:
+            <ul>
+              <li><code>Bundle-Name</code> - set to the component's name</li>
+              <li><code>Bundle-Vendor</code> - set to <i>The Apache
Software Foundation</i></li>
+              <li><code>Bundle-Version</code> - set to the component version</li>
+              <li><code>Bundle-ManifestVersion</code> - set to <b>2</b></li>
+              <li><code>Bundle-License</code> - set to <code>http://www.apache.org/licenses/LICENSE-2.0.txt</code></li>
+              <li><code>Bundle-Description</code> - set to the component's
description</li>
+              <li><code>Bundle-SymbolicName</code> - set to the component's
package name (e.g. <code>org.apache.commons.beanutils</code>)</li>
+              <li><code>Bundle-DocURL</code> - set to the component's website
URL</li>
+              <li><code>Export-Package</code> - set to the component's
package names (can be overriden)</li>
+              <li><code>Import-Package</code> - set to the package names
of the component's dependencies</li>
+            </ul>
+          </li>
+          <li>
+            <strong><a href="#Java_Version">Java Version</a></strong>
- <code>source</code> and <code>target</code>
+            options can be configured through <i>properties</i> and <i>profiles</i>
are provided to test on
+            different Java versions.
+          </li>
+        </ul>
+      </subsection>
+
+      <subsection name="Release">
+        <p>
+          The following is a list of the main <i>release</i> features provided
by
+          <a href="http://svn.apache.org/repos/asf/commons/proper/commons-parent/trunk/pom.xml">commons-parent</a>
+          through the <a href="#rc_profile">rc</a> and <a href="#release_profile">release</a>
profiles.
+        </p>
+        <ul>
+          <li>
+            <strong>Binary and Source distributions</strong>
+          </li>
+          <li>
+            <strong>Signatures and Checksums</strong>
+          </li>
+          <li>
+            <strong>javadoc and source jars</strong>
+          </li>
+        </ul>
+
+        <p>
+          Additionally the <a href="http://incubator.apache.org/rat/">RAT</a>
(release audit) report is automatically
+          produced when  generating a component's site. The <a href="http://incubator.apache.org/rat/">RAT</a>
report
+          checks the source files for appropriate <a href="http://www.apache.org/legal/src-headers.html">License
Headers</a>.
+        </p>
+      </subsection>
+
+      <subsection name="Site Generation">
+        <p>
+          The following is a list of the main <i>site</i> features provided by
+          <a href="http://svn.apache.org/repos/asf/commons/proper/commons-parent/trunk/pom.xml">commons-parent</a>:
+        </p>
+        <ul>
+          <li>
+            <strong>Standard Style and Navigation</strong> - commons-parent has
a
+            <a href="http://svn.apache.org/repos/asf/commons/proper/commons-parent/trunk/src/site/site.xml">site.xml</a>
+            which is <i>inherited</i> by each component's site and provides standard
<i>Menu/Navigation</i> and <i>styling</i>.
+            <ul>
+              <li><strong>Menu/Navigation</strong> - The menu and breadcrumb
options specified in the commons-parent's
+                  <code>site.xml</code> are included in the component's site.
+              </li>
+              <li><strong>Style</strong> - The commons-parent's <code>site.xml</code>
specifies the
+                  <a href="http://svn.apache.org/repos/asf/commons/proper/commons-skin/trunk/">commons-skin</a>
+                  so that component's sites use a standard style and commons logo.
+              </li>
+            </ul>
+          </li>
+          <li>
+            <strong>Common Information</strong>
+            <ul>
+              <li><strong>Mailing Lists</strong> - Mailing list information
is specified in commons-parent and maven automatically
+                  generates a standard <a href="mail-list.html">Mailing List page</a>
for each compoenent.</li>
+              <li><strong>Organization Name</strong> - <i>The Apache
Software Foundation</i> (inherited from the Apache Parent pom).</li>
+            </ul>
+          </li>
+          <li>
+            <strong>Standard Reports</strong> - The following reports are configured
+            <ul>
+              <li><strong><a href="http://incubator.apache.org/rat/">RAT</a>
(release audit) Report</strong> - reports on the
+                  presence/absence of appropriate <a href="http://www.apache.org/legal/src-headers.html">License
Headers</a> in
+                  source files.
+              </li>
+              <li><strong>Surefire Report</strong></li>
+              <li><strong>Javadocs</strong></li>
+              <li><strong>Source Cross Reference</strong></li>
+            </ul>
+          </li>
+          <li>
+            <strong>Custom Issue Tracking Page</strong> - The
+            <a href="http://commons.apache.org/commons-build-plugin/">commons-build-plugin</a>
provides a mechanism to
+            generate a <i>custom</i> issue tracking page for commons components.
See 
+            <a href="http://commons.apache.org/commons-build-plugin/jira-page.html">here</a>
for details of
+            how to configure the component's pom and generate the page.
+          </li>
+          <li>
+            <strong>Download Page</strong> - The
+            <a href="http://commons.apache.org/commons-build-plugin/">commons-build-plugin</a>
provides a mechanism to
+            generate a <i>download page</i> for the latest release of a component.
See
+            <a href="http://commons.apache.org/commons-build-plugin/download-page.html">here</a>
+            for details of how to configure the component's pom and generate the page.
+          </li>
+        </ul>
+      </subsection>
+
+    </section>
+
+    <section name="Java Version">
+
+      <subsection name="Configuring the Java Source/Target options">
+        <p>
+          <a href="http://svn.apache.org/repos/asf/commons/proper/commons-parent/trunk/pom.xml">commons-parent</a>
+          configures the <code>source</code> and <code>target</code>
options in the 
+          <a href="http://maven.apache.org/plugins/maven-compiler-plugin/">maven-compiler-plugin</a>
to use the
+          <code>${maven.compiler.source}</code> and <code>${maven.compiler.target}</code>
properties
+          respectively.
+        </p>
+        <p>
+          So, for example, to configure a component to have <i>source/target</i>
set to <i>1.4</i> add the following
+          lines to the component's <code>pom.xml</code>:
+        </p>
+        <source><![CDATA[
+          <properties>
+              <maven.compiler.source>1.4</maven.compiler.source>
+              <maven.compiler.target>1.4</maven.compiler.target>
+          </properties> 
+        ]]></source>
+      </subsection>
+
+      <subsection name="MANIFEST.MF">
+        <p>
+          In order to help check what source/target options were used when building a release,
the property values used to
+          configure the <i>source/target</i> options in the 
+          <a href="http://maven.apache.org/plugins/maven-compiler-plugin/">maven-compiler-plugin</a>
+          (i.e. <code>${maven.compiler.source}</code> and <code>${maven.compiler.target}</code>)
are also written
+          out to the component jar's <code>MANIFEST.MF</code> file with the following
values:
+        </p>
+        <source>
+            X-Compile-Source-JDK: 1.4
+            X-Compile-Target-JDK: 1.4
+        </source>
+      </subsection>
+
+      <subsection name="Testing with different Java versions">
+        <p>
+          Using the <i>target</i> option ensures that the <code>.class</code>
file format is compatible with
+          the required Java version - but it doesn't not prevent/catch the use of methods/classes
which were
+          introduced in later Java versions. The only way to do that is to compile and test
using actual
+          Java versions.
+        </p>
+        <p>
+          <a href="http://svn.apache.org/repos/asf/commons/proper/commons-parent/trunk/pom.xml">commons-parent</a>
+          provides <i>profiles</i> for compiling/testing under different Java
versions:
+        </p>
+        <ul>
+            <li><code>java-1.3</code> for testing using Java 1.3</li>
+            <li><code>java-1.4</code> for testing using Java 1.4</li>
+            <li><code>java-1.5</code> for testing using Java 1.5</li>
+            <li><code>java-1.6</code> for testing using Java 1.6</li>
+        </ul>
+        <p>
+          In order for these profiles to work, you need to configure the <code>JAVA_1_3_HOME</code>,
+          <code>JAVA_1_4_HOME</code>, <code>JAVA_1_5_HOME</code>
and <code>JAVA_1_6_HOME</code>
+          properties in your <code>settings.xml</code> file (or as environment
variables). See
+          <a href="http://maven.apache.org/plugins/maven-compiler-plugin/examples/compile-using-different-jdk.html">here</a>
for details.
+        </p>
+        <p>
+          Once you have configured those properties you can, for example, test using Java
1.4 using the following command:
+        </p>
+        <source>
+            mvn -Pjava-1.4 clean test
+        </source>
+      </subsection>
+
+    </section>
+
+    <section name="OSGi Information">
+
+      <subsection name="OSGi Metadata">
+        <p>
+          In order to use a Commons component (or any libaray) in an 
+          <a href="http://www.osgi.org/">OSGi</a> conatiner (for example
+          <a href="http://felix.apache.org/">Apache Felix</a>) then OSGi
+          <i>metadata</i> needs to be included in the <code>MANIFEST.MF</code>
+          file of the component's <i>jar</i>.
+        </p>
+      </subsection>
+
+      <subsection name="Generating the OSGi Metadata">
+        <p>
+          <a href="http://svn.apache.org/repos/asf/commons/proper/commons-parent/trunk/pom.xml">commons-parent</a>
+          is configured to automatically add the OSGi <i>metadata</i> to the
component jar's <code>MANIFEST.MF</code>
+          using the <a href="http://felix.apache.org/site/apache-felix-maven-bundle-plugin-bnd.html">
+          maven-bundle-plugin</a> when the <i>package</i> phase is executed:
+        </p>
+
+        <source>mvn package</source>
+
+        <p>
+          Most components only need to configure the <code>&lt;commons.componentid&gt;</code>
+          property in their <code>pom.xml</code> in the following way:
+        </p>
+
+        <source><![CDATA[
+          <properties>
+              <commons.componentid>beanutils</commons.componentid>
+          </properties> 
+        ]]></source>
+
+      </subsection>
+
+      <subsection name="Custom OSGi configuration">
+        <p>
+          There are a number of other <i>OSGi</i> properties in the commons-parent
+          <code>pom.xml</code> which are used to configure the <code>maven-bundle-plugin</code>.
+          These have sensible defaults, but can be <i>overriden</i> in a component's
+          <code>pom.xml</code> if required. These are:
+          <ul>
+             <li>The <b><code>&lt;commons.osgi.symbolicName&gt;</code></b>
property configures the
+                <b><code>&lt;Bundle-SymbolicName&gt;</code></b>
instruction</li>
+             <li>The <b><code>&lt;commons.osgi.export&gt;</code></b>
property configures the
+                <b><code>&lt;Export-Package&gt;</code></b>
instruction</li>
+             <li>The <b><code>&lt;commons.osgi.private&gt;</code></b>
property configures the
+                <b><code>&lt;Private-Package&gt;</code></b>
instruction</li>
+             <li>The <b><code>&lt;commons.osgi.import&gt;</code></b>
property configures the
+                <b><code>&lt;Import-Package&gt;</code></b>
instruction</li>
+             <li>The <b><code>&lt;commons.osgi.dynamicImport&gt;</code></b>
property configures the
+                <b><code>&lt;DynamicImport-Package&gt;</code></b>
instruction</li>
+          </ul>
+        </p>
+      </subsection>
+
+    </section>
+
+    <section name="Profiles">
+
+      <subsection name="Java profiles">
+        <p>
+          <a href="http://svn.apache.org/repos/asf/commons/proper/commons-parent/trunk/pom.xml">commons-parent</a>
+          contains some java profiles to compile/test using different versions of Java.
+          See <a href="#Testing_with_different_Java_versions">here</a> for details
of using the Java profiles.
+        </p>
+      </subsection>
+
+      <subsection name="rc profile">
+        <p>
+          <a href="http://svn.apache.org/repos/asf/commons/proper/commons-parent/trunk/pom.xml">commons-parent</a>
+          contains an <code>rc</code> profile for producing <i>release
candidates</i>.
+        </p>
+
+        <p>
+          Running the following command will, in addition to creating the jar as normal,
will also:
+        </p>
+        <ul>
+          <li>produce the source and binary distributions</li>
+          <li>produce the javadoc and sources jars</li>
+        </ul>
+
+        <source>mvn -Prc package</source>
+
+        <p>
+          Running the following command will, as well as doing producing everything specified
above for
+          the <i>package</i> command, also sign the artifacts and create checksums
(in local m2 repo):
+        </p>
+
+        <source>mvn -Prc install</source>
+
+      </subsection>
+
+      <subsection name="release profile">
+        <p>
+          <a href="http://svn.apache.org/repos/asf/commons/proper/commons-parent/trunk/pom.xml">commons-parent</a>
+          contains an <code>release</code> profile for producing <i>releases</i>.
This is the same as the
+          <a href="#rc_profile">rc profile</a> except the <i>repository</i>
and <i>snapshotRepository</i> locations
+          are different.
+        </p>
+
+        <p>
+          Running the following command will, in addition to creating the jar as normal,
will also:
+        </p>
+        <ul>
+          <li>produce the source and binary distributions</li>
+          <li>produce the javadoc and sources jars</li>
+        </ul>
+
+        <source>mvn -Prelease package</source>
+
+      </subsection>
+
+      <subsection name="trunks-proper profile">
+        <p>
+          <a href="http://svn.apache.org/repos/asf/commons/proper/commons-parent/trunk/pom.xml">commons-parent</a>
+          contains a <code>trunks-proper</code> profile with the <a href="components.html">components</a>
set up
+          as <code>&lt;modules&gt;</code>. This is a <i>convenience</i>
profile so that maven commands can be run
+          for all <a href="components.html">components</a>.
+        </p>
+
+        <p>
+          For example, if the template for the 
+          <a href="http://commons.apache.org/commons-build-plugin/download-page.html">download
page</a>
+          was changed, you could re-generate the download pages for all <a href="components.html">components</a>
+          using the following command:
+        </p>
+
+        <source>mvn -Ptrunks-proper commons:download-page</source>
+
+        <p>
+          ...or to test all components:
+        </p>
+
+        <source>mvn -Ptrunks-proper clean test</source>
+      </subsection>
+
+      <subsection name="trunks-sandbox profile">
+        <p>
+          <a href="http://svn.apache.org/repos/asf/commons/proper/commons-sandbox-parent/trunk/pom.xml">commons-sandbox-parent</a>
+          contains a <code>trunks-sandbox</code> profile with the <a href="sandbox/index.html">sandbox
components</a> set up
+          as <code>&lt;modules&gt;</code>. This is a <i>convenience</i>
profile so that maven commands can be run
+          for all <a href="sandbox/index.html">sandbox components</a>.
+        </p>
+
+        <p>
+          For example, if the template for the 
+          <a href="http://commons.apache.org/commons-build-plugin/sandbox-jira-page.html">sandbox
issue tracking page</a>
+          was changed, you could re-generate the issue tracking pages for all <a href="sandbox/index.html">sandbox
components</a>
+          using the following command:
+        </p>
+
+        <source>mvn -Ptrunks-sandbox commons:sandbox-jira-page</source>
+
+        <p>
+          ...or to test all sandbox components:
+        </p>
+
+        <source>mvn -Ptrunks-sandbox clean test</source>
+      </subsection>
+
+    </section>
+
+  </body>
+</document>

Propchange: commons/proper/commons-site/src/site/xdoc/commons-parent-pom.xml
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: commons/proper/commons-site/src/site/xdoc/commons-parent-pom.xml
------------------------------------------------------------------------------
    svn:keywords = Date Author Id Revision HeadURL



Mime
View raw message