You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maven.apache.org by ra...@apache.org on 2008/02/10 23:33:04 UTC
svn commit: r620351 - in
/maven/archetype/trunk/archetype-plugin/src/site/apt: ./ examples/
specification/
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
+---
+