maven-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From raf...@apache.org
Subject svn commit: r620351 - in /maven/archetype/trunk/archetype-plugin/src/site/apt: ./ examples/ specification/
Date Sun, 10 Feb 2008 22:33:04 GMT
Author: rafale
Date: Sun Feb 10 14:33:02 2008
New Revision: 620351

URL: http://svn.apache.org/viewvc?rev=620351&view=rev
Log:
Documentation enhancement

Added:
    maven/archetype/trunk/archetype-plugin/src/site/apt/advanced-usage.apt   (with props)
    maven/archetype/trunk/archetype-plugin/src/site/apt/examples/create-alternative-catalog.apt   (with props)
    maven/archetype/trunk/archetype-plugin/src/site/apt/examples/create-basic.apt   (with props)
    maven/archetype/trunk/archetype-plugin/src/site/apt/examples/create-batch.apt
      - copied unchanged from r620150, maven/archetype/trunk/archetype-plugin/src/site/apt/examples/create-project-in-batch-mode.apt
    maven/archetype/trunk/archetype-plugin/src/site/apt/examples/create-from-project-basic.apt   (with props)
    maven/archetype/trunk/archetype-plugin/src/site/apt/examples/create-from-project-deploy.apt   (with props)
    maven/archetype/trunk/archetype-plugin/src/site/apt/specification/
    maven/archetype/trunk/archetype-plugin/src/site/apt/specification/archetype-catalog.apt   (with props)
    maven/archetype/trunk/archetype-plugin/src/site/apt/specification/archetype-metadata.apt   (with props)
    maven/archetype/trunk/archetype-plugin/src/site/apt/specification/archetype.apt   (with props)
    maven/archetype/trunk/archetype-plugin/src/site/apt/specification/crawl-repository.apt   (with props)
    maven/archetype/trunk/archetype-plugin/src/site/apt/specification/create-from-project.apt   (with props)
    maven/archetype/trunk/archetype-plugin/src/site/apt/specification/create.apt   (with props)
    maven/archetype/trunk/archetype-plugin/src/site/apt/specification/specification.apt   (with props)
    maven/archetype/trunk/archetype-plugin/src/site/apt/specification/update-catalog.apt   (with props)
Removed:
    maven/archetype/trunk/archetype-plugin/src/site/apt/examples/create-project-in-batch-mode.apt
Modified:
    maven/archetype/trunk/archetype-plugin/src/site/apt/index.apt
    maven/archetype/trunk/archetype-plugin/src/site/apt/usage.apt

Added: maven/archetype/trunk/archetype-plugin/src/site/apt/advanced-usage.apt
URL: http://svn.apache.org/viewvc/maven/archetype/trunk/archetype-plugin/src/site/apt/advanced-usage.apt?rev=620351&view=auto
==============================================================================
--- maven/archetype/trunk/archetype-plugin/src/site/apt/advanced-usage.apt (added)
+++ maven/archetype/trunk/archetype-plugin/src/site/apt/advanced-usage.apt Sun Feb 10 14:33:02 2008
@@ -0,0 +1,32 @@
+ ------
+ Advanced Usage
+ ------
+ Raphaël Piéroni
+ ------
+ 2008
+ ------
+
+~~ 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.
+
+~~ NOTE: For help with the syntax of this file, see:
+~~ http://maven.apache.org/guides/mini/guide-apt-format.html
+
+
+Archetype creation
+
+~~TODO: add content
\ No newline at end of file

Propchange: maven/archetype/trunk/archetype-plugin/src/site/apt/advanced-usage.apt
------------------------------------------------------------------------------
    svn:eol-style = native

Added: maven/archetype/trunk/archetype-plugin/src/site/apt/examples/create-alternative-catalog.apt
URL: http://svn.apache.org/viewvc/maven/archetype/trunk/archetype-plugin/src/site/apt/examples/create-alternative-catalog.apt?rev=620351&view=auto
==============================================================================
--- maven/archetype/trunk/archetype-plugin/src/site/apt/examples/create-alternative-catalog.apt (added)
+++ maven/archetype/trunk/archetype-plugin/src/site/apt/examples/create-alternative-catalog.apt Sun Feb 10 14:33:02 2008
@@ -0,0 +1,28 @@
+ ------
+ XXXXXXX
+ ------
+ Raphaël Piéroni
+ ------
+ 2008
+ ------
+
+~~ 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.
+
+~~ NOTE: For help with the syntax of this file, see:
+~~ http://maven.apache.org/guides/mini/guide-apt-format.html
+

Propchange: maven/archetype/trunk/archetype-plugin/src/site/apt/examples/create-alternative-catalog.apt
------------------------------------------------------------------------------
    svn:eol-style = native

Added: maven/archetype/trunk/archetype-plugin/src/site/apt/examples/create-basic.apt
URL: http://svn.apache.org/viewvc/maven/archetype/trunk/archetype-plugin/src/site/apt/examples/create-basic.apt?rev=620351&view=auto
==============================================================================
--- maven/archetype/trunk/archetype-plugin/src/site/apt/examples/create-basic.apt (added)
+++ maven/archetype/trunk/archetype-plugin/src/site/apt/examples/create-basic.apt Sun Feb 10 14:33:02 2008
@@ -0,0 +1,28 @@
+ ------
+ XXXXXXX
+ ------
+ Raphaël Piéroni
+ ------
+ 2008
+ ------
+
+~~ 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.
+
+~~ NOTE: For help with the syntax of this file, see:
+~~ http://maven.apache.org/guides/mini/guide-apt-format.html
+

Propchange: maven/archetype/trunk/archetype-plugin/src/site/apt/examples/create-basic.apt
------------------------------------------------------------------------------
    svn:eol-style = native

Added: maven/archetype/trunk/archetype-plugin/src/site/apt/examples/create-from-project-basic.apt
URL: http://svn.apache.org/viewvc/maven/archetype/trunk/archetype-plugin/src/site/apt/examples/create-from-project-basic.apt?rev=620351&view=auto
==============================================================================
--- maven/archetype/trunk/archetype-plugin/src/site/apt/examples/create-from-project-basic.apt (added)
+++ maven/archetype/trunk/archetype-plugin/src/site/apt/examples/create-from-project-basic.apt Sun Feb 10 14:33:02 2008
@@ -0,0 +1,30 @@
+ ------
+ XXXXXXX
+ ------
+ Raphaël Piéroni
+ ------
+ 2008
+ ------
+
+~~ 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.
+
+~~ NOTE: For help with the syntax of this file, see:
+~~ http://maven.apache.org/guides/mini/guide-apt-format.html
+
+
+

Propchange: maven/archetype/trunk/archetype-plugin/src/site/apt/examples/create-from-project-basic.apt
------------------------------------------------------------------------------
    svn:eol-style = native

Added: maven/archetype/trunk/archetype-plugin/src/site/apt/examples/create-from-project-deploy.apt
URL: http://svn.apache.org/viewvc/maven/archetype/trunk/archetype-plugin/src/site/apt/examples/create-from-project-deploy.apt?rev=620351&view=auto
==============================================================================
--- maven/archetype/trunk/archetype-plugin/src/site/apt/examples/create-from-project-deploy.apt (added)
+++ maven/archetype/trunk/archetype-plugin/src/site/apt/examples/create-from-project-deploy.apt Sun Feb 10 14:33:02 2008
@@ -0,0 +1,29 @@
+ ------
+ XXXXXXX
+ ------
+ Raphaël Piéroni
+ ------
+ 2008
+ ------
+
+~~ 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.
+
+~~ NOTE: For help with the syntax of this file, see:
+~~ http://maven.apache.org/guides/mini/guide-apt-format.html
+
+

Propchange: maven/archetype/trunk/archetype-plugin/src/site/apt/examples/create-from-project-deploy.apt
------------------------------------------------------------------------------
    svn:eol-style = native

Modified: maven/archetype/trunk/archetype-plugin/src/site/apt/index.apt
URL: http://svn.apache.org/viewvc/maven/archetype/trunk/archetype-plugin/src/site/apt/index.apt?rev=620351&r1=620350&r2=620351&view=diff
==============================================================================
--- maven/archetype/trunk/archetype-plugin/src/site/apt/index.apt (original)
+++ maven/archetype/trunk/archetype-plugin/src/site/apt/index.apt Sun Feb 10 14:33:02 2008
@@ -29,7 +29,7 @@
 
 Maven 2 Archetype Plugin
 
- The archetype plugin allows the user to create a Maven 2 project
+ The Archetype Plugin allows the user to create a Maven 2 project
  from an existing template called an archetype.
 
  It also allows the user to create an archetype from an existing project. 
@@ -38,12 +38,15 @@
 
 * Usage
 
-  Instructions on how to use the Archetype Plugin can be found on the
-  {{{usage.html}usage}} page.
+  {{{usage.html}Instructions on how to use the Archetype Plugin to create a project}}
+  can be found on the usage page.
 
   The Archetype Plugin is embedded in IDE {{{#}eclipse}}, {{{#}netbeans}}, 
   {{{#}idea}}.
 
+  {{{advanced-usage.html}Instruction on how to use the Archetype Plugin to create an archetype from an existing project}} 
+  can be found  on the advanced usage page.
+
 
 * Goals Overview
 
@@ -53,9 +56,12 @@
     from the archetype catalog, and retrieves it from the remote repository.
     Once retrieved, it is processed to create a working Maven project.
 
-  * {{{create-from-project-mojo.html}archetype:create-from-project}}  creates
+  * {{{create-from-project-mojo.html}archetype:create-from-project}} creates
     an archetype from an existing project.
 
+  * {{{crawl-repository.html}archetype:crawl-repository}} search a repository 
+    for archetype and updates a catalog.
+
   []
 
 
@@ -71,4 +77,10 @@
    * {{{#}select the archetype from another catalog}}
 
   []
+
+
+* Specification
+
+   The specification page contains 
+   {{{specification/specification.html}the specification of the main parts of the Archetype Plugin}}.
 

Added: maven/archetype/trunk/archetype-plugin/src/site/apt/specification/archetype-catalog.apt
URL: http://svn.apache.org/viewvc/maven/archetype/trunk/archetype-plugin/src/site/apt/specification/archetype-catalog.apt?rev=620351&view=auto
==============================================================================
--- maven/archetype/trunk/archetype-plugin/src/site/apt/specification/archetype-catalog.apt (added)
+++ maven/archetype/trunk/archetype-plugin/src/site/apt/specification/archetype-catalog.apt Sun Feb 10 14:33:02 2008
@@ -0,0 +1,239 @@
+ ------
+ Archetype Catalog
+ ------
+ Raphaël Piéroni
+ ------
+ 10 February 2008
+ ------
+
+~~ 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.
+
+~~ NOTE: For help with the syntax of this file, see:
+~~ http://maven.apache.org/guides/mini/guide-apt-format.html
+
+
+How the Archetype Plugin know about archetype?
+
+~~TODO: add content
+
++---
+Content of a catalog file
+    an xml file commonly named archetype-catalog.xml
+    <?xml ?> 
+
+ <archetype-catalog> 
+
+ 
+
+ <archetype> 
+
+ <groupId/> 
+
+ <artifactId/> 
+
+ 
+
+ <repositoryUrl/> 
+
+ <!-- optional when the file resides in a remote repository --> 
+
+ 
+
+ <goals> 
+
+ <!-- list of goals called on a project after its generation from an archetype --> 
+
+ <!-- optional they whould reside in the archetype metadata file --> 
+
+ <goal>clean:clean</goal> 
+
+ </goals> 
+
+ 
+
+ <properties> 
+
+ <!-- properties used in combination with the goals --> 
+
+ <!-- should also reside in the archetype metadata --> 
+
+ <property.name>property value</property.name> 
+
+ </properties> 
+
+ </archetype> 
+
+ ... 
+
+ </archetype-catalog>
+
+
+
++---
+
+
+
+
+
++---
+Selection behaviour
+    1. default behaviour 
+
+ 
+
+ prompt to select archetype from the internal catalog 
+
+ check repository for latest RELEASE 
+
+ use that release 
+
+ 
+
+ act as if -Darchetype.catalog=internal
+        case archetype is defined 
+
+ group artifact and version of archetype has values
+            if repository is defined
+                if archetype exists in repository
+                    use IT
+                else
+                    if interactive
+                        same as groupId and artifactId
+                    else FAIL
+            else
+                if archetype exist in one catalog
+                    use IT
+                if archetpe exists in more than one catalog
+                    use FIRST
+                else
+                    same as groupId and artifactId
+        case archetype is partially defined 
+
+ group and artifact has values
+            if repository is defined
+                if archetype exists in repository
+                    select LATEST
+                else
+                    same as archetype not defined
+            else
+                if archetype exist in one catalog
+                    select LATEST
+                if archetype exist in more than one catalog
+                    select LATEST
+                esle
+                    same as archetype not defined
+        case archetype is not defined
+            get archetypes from defined catalogs 
+
+ ask for one
+                select LATEST
+    2. choose version 
+
+ 
+
+ prompt to select archetype from internal catalog 
+
+ check repository for all versions 
+
+ prompt to select the version (one of the retrieved release versions(latest first), LATEST or SNAPSHOT is allowed) 
+
+ if SNAPSHOT is selected reprompt to select one of the retrieved snapshot versions (latest first) 
+
+ if LATEST is selected take the latest release version 
+
+ use the selected archetype and version 
+
+ 
+
+ activated with -Darchetype.selectVersion=true or -Da.sv=true (for shorter)
+        any select LATEST
+            if interactive and selectVersion 
+
+ get versions fromall repositories 
+
+ ask for one version
+    3. use another catalog 
+
+ 
+
+ load the catalog from the remote source 
+
+ then same behaviour as basic 
+
+ 
+
+ activated with -Darchetype.catalog=http://ip:port/path/file.xml 
+
+ or with -Darchetype.catalog=http://ip:port/path (defauls to archetype-catalog.xml) 
+
+ or with -Darchetype.catalog=remote (defaults to http://repo1.maven.org/maven2/archetype-catalog.xml) 
+
+ or with -Darchetype.catalog=file:///absolute/path/to/archetype-catalog.xml (no default file) 
+
+ 
+
+ possible to combine with the -Darchetype.selectVersion property 
+
+ 
+
+ usage of proxy: handled by Maven in command line and in the IDE so all wagon download are transparent to the archetype plugin 
+
+ 
+
+ alternative activation in combination with the ~/.m2/archetype-catalog.properties file 
+
+ activation -Darchetype.catalog=name (name different from internal, remote or wiki) 
+
+ then the catalog properties file must contains a line with name=http://ip:port/path (same defaulting) 
+
+ 
+
+ remote catalogs and local catalog do not define repositoryUrls 
+
+ in their archetypes' definition as this is obviously implied
+    4. use multiple catalogs 
+
+ 
+
+ load all defined catalogs separately 
+
+ prompt to select archetype from those catalogs (without duplicates) 
+
+ check in each repositories for versions and select the LATEST 
+
+ 
+
+ activated with -Darchetype.catalog=internal,remote,wiki,http://ip:port/path (same defaulting) 
+
+ 
+
+ possible to combine with -Darchetype.selectVersion
+    Archetype cataloger has methods 
+
+ - getInternalCatalog/0 
+
+ ------ getWikiCatalog/0 
+
+ - getRemoteCatalog/0 /1(url) 
+
+ - getLocalCatalog/0 /1(path) 
+
+ - updateLocalCatalog/2(achetype, path) 
+
+ - updateRemoteCatalog/3 (archetype, url, credentials)
++---
\ No newline at end of file

Propchange: maven/archetype/trunk/archetype-plugin/src/site/apt/specification/archetype-catalog.apt
------------------------------------------------------------------------------
    svn:eol-style = native

Added: maven/archetype/trunk/archetype-plugin/src/site/apt/specification/archetype-metadata.apt
URL: http://svn.apache.org/viewvc/maven/archetype/trunk/archetype-plugin/src/site/apt/specification/archetype-metadata.apt?rev=620351&view=auto
==============================================================================
--- maven/archetype/trunk/archetype-plugin/src/site/apt/specification/archetype-metadata.apt (added)
+++ maven/archetype/trunk/archetype-plugin/src/site/apt/specification/archetype-metadata.apt Sun Feb 10 14:33:02 2008
@@ -0,0 +1,210 @@
+ ------
+ Archetype Metadata
+ ------
+ Raphaël Piéroni
+ ------
+ 10 February 2008
+ ------
+
+~~ 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.
+
+~~ NOTE: For help with the syntax of this file, see:
+~~ http://maven.apache.org/guides/mini/guide-apt-format.html
+
+
+How metadata on an archetype is stored?
+
+    The metadata about an archetype is stored in the archetype-metadata.xml file
+    located in the directory META-INF/maven of it's jar file.
+
+    The metadata file stores the additionnal properties, with corresponding 
+    default values.
+
+    It also stores the project's files generation in filesets.
+
+    Finnaly it also stores inner modules of the archetype, which enable the 
+    creation of multi-modules projects with a single archetype.
+
+    A minimal archetype-metadata.xml file looks like:
+
++---
+<?xml version="1.0" encoding="UTF-8"?>
+<archetype-descriptor name="basic">
+  <fileSets>
+    <fileSet filtered="true" packaged="true">
+      <directory>src/main/java</directory>
+      <includes>
+        <include>**/*.java</include>
+      </includes>
+    </fileSet>
+  </fileSets>
+</archetype-descriptor>
++---
+
+    This example above shows:
+    
+    * the archetype name is <<<basic>>>
+
+    * the archetype defines a single fileset: 
+    
+      * the fileset will take all the files in archetype-resources/src/main/java
+        that match the <<<**/*.java>>> pattern
+
+      * the selected files will be generated using the velocity engine 
+        (<<<filtered=true>>>)
+
+      * the files will be generated in the src/main/java directory of the 
+        generated project in the same directory as in the jar file, but with 
+        that directory prepended by the package property.
+      
+      []
+
+    []
+
+
+ * Defining additional properties
+
+    The main properties that are used by the velocity engine during project's file generation are groupId, artifactId, version, package.
+
+    It is possible to define additionnal properties that must be valued before the file generation. 
+
+    These additionnal properties can be provided with default values, which enable not to ask the user for there values.
+
+    Additionnal properties are defined in the archetype-metadata.xml file with:
+
++---
+<archetype-descriptor name="basic">
+  <requiredProperties>
+    <requiredProperty key="property-with-default">
+      <defaultValue>default-value</defaultValue>
+    </requiredProperty>
+    <requiredProperty key="property-without-default"/>
+  </requiredProperties>
+...
+</archetype-descriptor>
++---
+    
+    Here two additionnal properties are defined: <<<property-without-default>>>
+    and <<<property-with-default>>>.
+
+    Be aware that the property keys can not contain any dot as there are 
+    velocity properties.
+
+
+* Defining specific filesets
+
+    The filesets contained in the archetype-metadata.xml file defines the way
+    the project's files located in the jar file are used by the Archetype Plugin 
+    to generate a project.
+
+    Filesets must define the directory where the files will be searched for 
+    which is also the directory where the project's files will be generated. 
+    The first is the directory inside the archetype jar file, the second is the 
+    directory in the generated project's tree.
+
+    Filesets also defines the inclusion/exclusion of files "à la " ant. 
+    This provide a powerfull way to describe a large set of files to be selected 
+    for the generation process.
+
+    Filesets can be filtered, which means the selected files will be used 
+    as Velocity templates. They can be non-filtered, which means the selected 
+    files will be binary copied.
+
+    Filesets can be packaged, which means the selected files will be 
+    generated/copied in a directory structure that is prepended by the package 
+    property. They can be non-packaged, which means that the selected files 
+    will be generated/copied without that prepend.
+
+    A fileset is defined in the archetype-metadata.xml with this fragment:
+
++---
+...
+  <fileSets>
+    <fileSet filtered="true" packaged="true">
+      <directory>src/test/java</directory>
+      <includes>
+        <include>**/*.java</include>
+      </includes>
+      <excludes>
+        <excludeAllTest.java</include>
+      </excludes>
+    </fileSet>
+  </fileSets>
+...
++---
+
+    This example shows a fileset that will select all the java files in the 
+    <<<src/test/java>>> directory of the archetype resources, but the 
+    <<<AllTest.java>>> file that is located at the root of this directory.
+
+    This filset also is packaged and filtered.
+
+
+* Defining multi module in the archetype metadata
+
+    Inner modules of an archetype are used to create a multi module Maven 2 
+    project from a single archetype.
+
+    Modules in the archetype-metadata.xml file are defined like:
+
++---
+<archetype-descriptor name="multi-module">
+  <fileSets>
+    ...
+  </fileSets>
+  <modules>
+    <module name="SubProject" id="subproject" dir="sub-project">
+      <fileSets>
+        ...
+      </fileSets>
+    </module>
+  </modules>
+</archetype-descriptor>
++---
+
+    In the example above, the archetype <<<multi-module>>> contains a module 
+    named <<<SubProject>>>. This module is located in the <<<sub-project>>> 
+    directory of the archetype. It also has the artifactId <<<subproject>>>.
+
+    The attributes name, id and dir of the module are used to determine the 
+    directory where togenerated that module files, they also are used to 
+    determine the artifactId of the Maven 2 project corresponding to this 
+    module.
+
+
+* Putting all together
+
+    The <<<requiredProperties>>> is only allowed as a child of 
+    archetype-descriptor.
+
+    Modules are allowed in archetype-descriptor and in modules (no limit is 
+    given).
+
+    archetype-descriptor and modules must define at least one fileset each to 
+    be valid.
+
+    It is possible to define default values to main required properties by 
+    defining say the groupId and giving it a default:
+
++---
+...
+  <requiredProperties>
+    <requiredProperty key="groupId">
+      <defaultValue>com.company.department</defaultValue>
+    </requiredProperty>
++---

Propchange: maven/archetype/trunk/archetype-plugin/src/site/apt/specification/archetype-metadata.apt
------------------------------------------------------------------------------
    svn:eol-style = native

Added: maven/archetype/trunk/archetype-plugin/src/site/apt/specification/archetype.apt
URL: http://svn.apache.org/viewvc/maven/archetype/trunk/archetype-plugin/src/site/apt/specification/archetype.apt?rev=620351&view=auto
==============================================================================
--- maven/archetype/trunk/archetype-plugin/src/site/apt/specification/archetype.apt (added)
+++ maven/archetype/trunk/archetype-plugin/src/site/apt/specification/archetype.apt Sun Feb 10 14:33:02 2008
@@ -0,0 +1,90 @@
+ ------
+ Archetype
+ ------
+ Raphaël Piéroni
+ ------
+ 10 February 2008
+ ------
+
+~~ 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.
+
+~~ NOTE: For help with the syntax of this file, see:
+~~ http://maven.apache.org/guides/mini/guide-apt-format.html
+
+
+What is an archetype?
+
+* A Maven 2 project 'en devenir'  
+
+    I.e. a abstract representation of a kind of project 
+    that can be instanciated into a concrete customised 
+    Maven 2 project. 
+
+    An archetype knows which files will be part of the 
+    instanciated project and which properties to fill 
+    to properly customise the project. 
+ 
+    Each archetype defines a set of common properties: 
+
+    * groupId which will be the groupId of the project 
+
+    * artifactId which will be the artifactId of the project 
+
+    * version which will be the version of the project 
+
+    * package which will be the base package of all source files of the project
+
+    []
+
+
+
+* A jar file
+
+    The minimal content of the jar file: 
+
++---
+.
+|-- META-INF
+|   `-- maven
+|       `-- archetype-metadata.xml  [1]
+`-- archetype-resources
+    |-- ...                         [2]
+    `-- pom.xml                     [3]
++---
+
+    [[1]] The metadata file that defines:  
+
+        * the default values of the common properties, 
+
+        * a set of additional properties with their default values, 
+
+        * a set of archetype resources;
+        
+        []
+
+    [[2]] The resources files defined by the archetype metadata,
+
+    [[3]] The pom file of a Maven 2 project.
+
+    []
+
+
+* Note
+
+    The common properties should be renamed to ${target.groupId}, ...
+    to avoid name clash.
\ No newline at end of file

Propchange: maven/archetype/trunk/archetype-plugin/src/site/apt/specification/archetype.apt
------------------------------------------------------------------------------
    svn:eol-style = native

Added: maven/archetype/trunk/archetype-plugin/src/site/apt/specification/crawl-repository.apt
URL: http://svn.apache.org/viewvc/maven/archetype/trunk/archetype-plugin/src/site/apt/specification/crawl-repository.apt?rev=620351&view=auto
==============================================================================
--- maven/archetype/trunk/archetype-plugin/src/site/apt/specification/crawl-repository.apt (added)
+++ maven/archetype/trunk/archetype-plugin/src/site/apt/specification/crawl-repository.apt Sun Feb 10 14:33:02 2008
@@ -0,0 +1,53 @@
+ ------
+ Crawl Repository
+ ------
+ Raphaël Piéroni
+ ------
+ 10 February 2008
+ ------
+
+~~ 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.
+
+~~ NOTE: For help with the syntax of this file, see:
+~~ http://maven.apache.org/guides/mini/guide-apt-format.html
+
+
+How archetype lists are created?
+
+~~TODO: add content
+
++---
+
+Component that parse an FS repository  
+
+ 
+
+ for each artifact **/*.pom and for each associated jar 
+
+ check the presence of metadata descriptor 
+
+ and add it in the xml descriptor 
+
+ 
+
+ in : repository directory, desired repository URL (may be local) 
+
+ out : ArchetypeCatalog
+
+
++---
\ No newline at end of file

Propchange: maven/archetype/trunk/archetype-plugin/src/site/apt/specification/crawl-repository.apt
------------------------------------------------------------------------------
    svn:eol-style = native

Added: maven/archetype/trunk/archetype-plugin/src/site/apt/specification/create-from-project.apt
URL: http://svn.apache.org/viewvc/maven/archetype/trunk/archetype-plugin/src/site/apt/specification/create-from-project.apt?rev=620351&view=auto
==============================================================================
--- maven/archetype/trunk/archetype-plugin/src/site/apt/specification/create-from-project.apt (added)
+++ maven/archetype/trunk/archetype-plugin/src/site/apt/specification/create-from-project.apt Sun Feb 10 14:33:02 2008
@@ -0,0 +1,100 @@
+ ------
+ Create an Archetype from a Project
+ ------
+ Raphaël Piéroni
+ ------
+ 10 February 2008
+ ------
+
+~~ 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.
+
+~~ NOTE: For help with the syntax of this file, see:
+~~ http://maven.apache.org/guides/mini/guide-apt-format.html
+
+
+What is done during the creation of an archetype?
+
+~~TODO: add content
+
++---
+
+How to create an archetype?
+    The simple way: 
+
+ mvn archetype:createFromProject
+    Configuring the plugin
+        -Darchetype.languages
+        -Darchetype.filteredExtensions
+        -Darchetype.phase=(package|install|deploy)
+        -Dpackage
+        -Darchetype.propertyFile
+        configuring the post generation goals and their associated properties
+        should be possible to configure the most of the plugin using a property file for automation
+    Beeing behind a proxy is automatically configured by Maven
+    Actual configuration 
+
+ @parameter default-value="false" boolean interactive; 
+
+ @parameter expression="${archetype.filteredExtentions}" String archetypeFilteredExtentions; 
+
+ @parameter expression="${archetype.languages}" String archetypeLanguages; 
+
+ @parameter expression="${user.home}/.m2/archetype.xml" File archetypeRegistryFile; 
+
+ @parameter default-value="UTF-8" expression="${archetype.encoding}" String defaultEncoding; 
+
+ @parameter expression="${archetype.ignoreReplica}" boolean ignoreReplica = true; 
+
+ @parameter expression="${archetype.partialArchetype}" boolean partialArchetype = false; 
+
+ @parameter expression="${archetype.preserveCData}" boolean preserveCData = false; 
+
+ @parameter expression="${localRepository}" ArtifactRepository localRepository; 
+
+ @parameter expression="${archetype.keepParent}" boolean keepParent = true; 
+
+ @parameter expression="${project}" MavenProject project; 
+
+ @parameter default-value="target/archetype.properties" expression="${archetype.properties}" File propertyFile; 
+
+ @parameter expression="${basedir}/target" File outputDirectory; 
+
+ @parameter expression="${testMode}" boolean testMode;
+
++---
+
++---
+3 ways to call cfp:
+  basic way: create the archetype from project in target/generated-sources/archetype/
+	and package archetype jar in target/
+  install way: same as basic plus copy the archetype jar in local repository
+	and update the local catalog
+  deploy way: same as install plus deploy the archetype jar in known deployment repository
+	and update the known deployment repository catalog
+    updating a local catalog:
+load the local catalog and construct a catalog
+  if the archetype is not in local catalog
+	=> add it
+  else if the archetype is newer than in local catalog
+	=> change the version and repository in local
+  else there is a problem because we install an older version
+    updating a remote catalog:
+dowload the remote catalog and construct a memory catalog
+same as for the local updating
+upload the modified catalog
++---

Propchange: maven/archetype/trunk/archetype-plugin/src/site/apt/specification/create-from-project.apt
------------------------------------------------------------------------------
    svn:eol-style = native

Added: maven/archetype/trunk/archetype-plugin/src/site/apt/specification/create.apt
URL: http://svn.apache.org/viewvc/maven/archetype/trunk/archetype-plugin/src/site/apt/specification/create.apt?rev=620351&view=auto
==============================================================================
--- maven/archetype/trunk/archetype-plugin/src/site/apt/specification/create.apt (added)
+++ maven/archetype/trunk/archetype-plugin/src/site/apt/specification/create.apt Sun Feb 10 14:33:02 2008
@@ -0,0 +1,120 @@
+ ------
+ Create a Project from an Archetype
+ ------
+ Raphaël Piéroni
+ ------
+ 10 February 2008
+ ------
+
+~~ 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.
+
+~~ NOTE: For help with the syntax of this file, see:
+~~ http://maven.apache.org/guides/mini/guide-apt-format.html
+
+
+What is done during the creation of a project?
+
+~~TODO: add content
++---
+How to use an archetype?
+    The simple way : 
+
+ mvn archetype:create
+        standard call and standard output/prompt and standard generated tree
+    Configuring the plugin
+        for selection
+            -Darchetype.catalog
+                This property is used to define the catalogs to search archetypes into. 
+
+ This property hold a comma separated list of catalogs. 
+
+ The valid catalogs are: internal (the default), local, remote, file://path, http://url. 
+
+ - internal uses an internal catalog 
+
+ - local uses the ~/.m2/archetype-catalog.xml file 
+
+ - remote uses the http://repo1.maven.org/maven2/arccchetype-catalog.xml file 
+
+ - file://path uses the catalog file defined by path (or the archetype-catalog.xml file located in path directory) 
+
+ - http://url uses the catalog file defined by url (or the archetype-catalog.xml file located in url web directory)
+            -DarchetypeGroupId 
+
+ -DarchetypeArtifactId 
+
+ -DarchetypeVersion 
+
+ -DarchetypeRepository
+                When these 4 properties are defined, no catalog is searched. 
+
+ When only archetypeRepository is missing, the first archetype sharing both group and artifact ids found in any catalog gives its repository definition. 
+
+ When archetypeRepository and achetypeVersion are missing, the first archetype sharing both group and artifact ids found in any catalog, gives its repository and version definition. 
+
+ When archetypeGroupId or archetypeArtifactId is missing the standard selection behaviour occurs.
+            -Darchetype.interactive
+                Defined in settings.xml, this property allow the usage of archetype selection. 
+
+ defaults to @settings.interactiveMode
+            @settings.localRepository
+                Used to cache downloaded archetypes
+        for configuration
+            defined using executionProperties 
+
+ 
+
+ -DgroupId 
+
+ -DartifactId 
+
+ -Dversion 
+
+ -Dpackage 
+
+ -DanotherVelocityProperty
+                these properties are used to configure the created project 
+
+ groupId (defaults to com.company) 
+
+ artifactId (defaults to project) 
+
+ version (defaults to 1.0-SNAPSHOT) 
+
+ package (defaults to groupId.artifactId)
+                these properties should be renamed to 
+
+ target.groupId 
+
+ target.artifactId 
+
+ target.version 
+
+ target.package
+            -Darchetype.interactive
+                Defined in settings.xml, this property allow the usage of archetype selection. 
+
+ defaults to @settings.interactiveMode
+        for generation
+            -DarchetypeGoals
+                comma separated list of goals called against the project after been created
+            @basedir
+                the directory where the project will be created
+        for batch mode
+    Beeing behind a proxy is automatically configured by Maven
++---
\ No newline at end of file

Propchange: maven/archetype/trunk/archetype-plugin/src/site/apt/specification/create.apt
------------------------------------------------------------------------------
    svn:eol-style = native

Added: maven/archetype/trunk/archetype-plugin/src/site/apt/specification/specification.apt
URL: http://svn.apache.org/viewvc/maven/archetype/trunk/archetype-plugin/src/site/apt/specification/specification.apt?rev=620351&view=auto
==============================================================================
--- maven/archetype/trunk/archetype-plugin/src/site/apt/specification/specification.apt (added)
+++ maven/archetype/trunk/archetype-plugin/src/site/apt/specification/specification.apt Sun Feb 10 14:33:02 2008
@@ -0,0 +1,49 @@
+ ------
+ Specification
+ ------
+ Raphaël Piéroni
+ ------
+ 10 February 2008
+ ------
+
+~~ 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.
+
+~~ NOTE: For help with the syntax of this file, see:
+~~ http://maven.apache.org/guides/mini/guide-apt-format.html
+
+
+Specification
+
+    The Specification of the Archetype Plugin aims to answer to the following 
+    questions:
+
+    * {{{archetype.html}What is an archetype?}}
+
+    * {{{archetype-metadata.html}How metadata on an archetype is stored?}}
+
+    * {{{create.html}What is done during the creation of a project?}}
+
+    * {{{archetype-catalog.html}How the Archetype Plugin know about archetype?}}
+
+    * {{{create-from-project.html}What is done during the creation of an archetype?}}
+
+    * {{{update-catalog.html}How the Archetype Plugin know about new archetypes?}}
+
+    * {{{crawl-repository.html}How archetype lists are created?}}
+    
+    []
\ No newline at end of file

Propchange: maven/archetype/trunk/archetype-plugin/src/site/apt/specification/specification.apt
------------------------------------------------------------------------------
    svn:eol-style = native

Added: maven/archetype/trunk/archetype-plugin/src/site/apt/specification/update-catalog.apt
URL: http://svn.apache.org/viewvc/maven/archetype/trunk/archetype-plugin/src/site/apt/specification/update-catalog.apt?rev=620351&view=auto
==============================================================================
--- maven/archetype/trunk/archetype-plugin/src/site/apt/specification/update-catalog.apt (added)
+++ maven/archetype/trunk/archetype-plugin/src/site/apt/specification/update-catalog.apt Sun Feb 10 14:33:02 2008
@@ -0,0 +1,131 @@
+ ------
+ Update local and remote Catalog
+ ------
+ Raphaël Piéroni
+ ------
+ 10 February 2008
+ ------
+
+~~ 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.
+
+~~ NOTE: For help with the syntax of this file, see:
+~~ http://maven.apache.org/guides/mini/guide-apt-format.html
+
+
+How the Archetype Plugin know about new archetypes?
+
+~~TODO: add content
++---
+Creation/Deployment behaviour
+    5. archetype developer using local version 
+
+ 
+
+ archetype created using archetpe:create-from-project -Darchetype.phase=install 
+
+ the newly created archetype is copied in teh local repository 
+
+ and the archetype-catalog.xml file located at the root of the repository is updated with the archetype information 
+
+ 
+
+ when using in archetype:create -Darchetype.catalog=local 
+
+ the archetype must be specified using -Darchetype.groupId, -Darchetype.artifactId 
+
+ only the local repository is used and the LATEST version in it is used 
+
+ or selected with -Darchetype.selectVersion 
+
+ or specified with -Darchetype.version
+        configuration behaviour 
+
+ returns an incomplete creation request
+            determine archetype's groupId, artifactId, version 
+
+ -> defaults to resolve, overriden by property file, overriden by -D 
+
+ resolve package using (-Dlanguages languages can be found in property file instead) 
+
+ -> defaults to resolve, overriden by property file, overriden by -D 
+
+ determine additional properties 
+
+ -> ask if interactive, overridden by property file only
+        creation behaviour 
+
+ post creation goals (package/install/deploy)
+            determine filesets using: 
+
+ -> package, languages, filtereds, multi-module 
+
+ determine pom rewriting using: 
+
+ -> keepParent, addtional properties 
+
+ create archetype files using: 
+
+ -> package, common properties, additional properties 
+
+ create archetype's metadata file 
+
+ create archetype's pom using 
+
+ -> archetype's id, copying devs, licnese, ... AND deploymentManagement
+    6. archetype developer deployment the archetype 
+
+ 
+
+ archetype create using archetype:create-from-project -Darchetype.phase=deploy 
+
+ 
+
+ the deployment url used is taken from the initial project 
+
+ credentials are automatically configured by Maven 
+
+ the catalog file is located at the root of the repository URL and is named archetype-catalog.xml 
+
+ 
+
+ the deployment url and credentials could be overrided to use staging repositories, but how? 
+
+ 
+
+ proxies are automatically configured by Maven 
+
+ 
+
+ synchronisation between repositories of catalog files is easy as they don't define any repository URL
+        deployment credentials:
+            initialPom.deploymentManagement 
+
+ -> remote URL or remote snapshot URL 
+
+ settings.servers
+        deployment artifact:
+            initialPom.groupId or archetype.groupId in property file or in -D 
+
+ initialPom.artifactId +'-archetype' or archetype.artifactId in property file or in -D 
+
+ initialPom.version or archetype.version in property file or in -D
+        deployment metadata:
+            deploy vesions metadata as any artifact 
+
+ use deploymentManagement to update remote catalog
++---
\ No newline at end of file

Propchange: maven/archetype/trunk/archetype-plugin/src/site/apt/specification/update-catalog.apt
------------------------------------------------------------------------------
    svn:eol-style = native

Modified: maven/archetype/trunk/archetype-plugin/src/site/apt/usage.apt
URL: http://svn.apache.org/viewvc/maven/archetype/trunk/archetype-plugin/src/site/apt/usage.apt?rev=620351&r1=620350&r2=620351&view=diff
==============================================================================
--- maven/archetype/trunk/archetype-plugin/src/site/apt/usage.apt (original)
+++ maven/archetype/trunk/archetype-plugin/src/site/apt/usage.apt Sun Feb 10 14:33:02 2008
@@ -27,7 +27,7 @@
 ~~ http://maven.apache.org/guides/mini/guide-apt-format.html
 
 
-* Projet creation
+Projet creation
 
     Creating a project from an archetype involves three steps:
 
@@ -39,7 +39,7 @@
 
     []
 
- * Usage
+Usage
 
    Calling <<<archetype:create>>> the plugin will first ask to choose
    the archetype from the internal catalog. Just enter the number of the archetype.
@@ -163,3 +163,4 @@
 
 11 directories, 3 files
 +---
+



Mime
View raw message