blob: fe364037819c9c8a708bacf8ecb1ba64cbce30e6 [file] [log] [blame]
------
Archetype Catalog
------
Raphaël Piéroni
------
2011-09-30
------
~~ 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/doxia/references/apt-format.html
How does the Archetype Plugin know about archetypes?
Knowledge about archetypes is stored in catalogs.
The catalogs are xml files: see the {{{../../archetype-models/archetype-catalog/archetype-catalog.html}reference documentation}}.
The Archetype Plugin comes bundled with an internal catalog.
This one is used by default.
The Archetype Plugin can use catalogs from local filesystem and from HTTP
connections.
* Catalog file explained
A catalog is an xml file with such content:
+---
<?xml version="1.0" encoding="UTF-8"?>
<archetype-catalog xmlns="http://maven.apache.org/plugins/maven-archetype-plugin/archetype-catalog/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/plugins/maven-archetype-plugin/archetype-catalog/1.0.0 http://maven.apache.org/xsd/archetype-catalog-1.0.0.xsd">
<archetypes>
<archetype>
[1] <groupId>org.appfuse.archetypes</groupId>
[2] <artifactId>appfuse-basic-jsf</artifactId>
[3] <version>2.0</version>
[4] <repository>http://static.appfuse.org/releases</repository>
[5] <description>AppFuse archetype for creating a web application with Hibernate, Spring and JSF</description>
</archetype>
...
</archetypes>
</archetype-catalog>
+---
[[1]] The groupId of the archetype. <<REQUIRED>>
[[2]] The artifactId of the archetype. <<REQUIRED>>
[[3]] The version of the archetype. <<<RELEASE>>> is a valid version. <<REQUIRED>>
[[4]] The repository where to find the archetype. <<OPTIONAL>>. When
omitted, the archetype is searched for in the repository where the catalog
comes from.
[[5]] The description of the archetype. <<OPTIONAL>>
* Archetype selection explained
During the creation of a project from an archetype, the Archetype Plugin
asks the user to choose an archetype from a list containing the archetypes
from each of the provided catalogs (yes, there may be many).
For each archetype in the list, the Archetype Plugin shows a line like:
+---
1: internal -> appfuse-basic-jsf (AppFuse archetype for creating a web application with Hibernate, Spring and JSF)
+---
* <<<1:>>> The index of the archetype in the aggregated list (starting from
1).
* <<<internal>>> The name of the catalog where the archetype originates from.
* <<<appfuse-basic-jsf>>> The artifactId of the archetype.
* <<<(AppFuse archetype...)>>> The description of the archetype as found in
the catalog.
* Creating a catalog file
At the end of the <<<create-from-project>>> behaviour, the Archetype Plugin
installs/deploys the archetype, and updates the local/remote catalog.
The <<<crawl-repository>>> goal is used to create a catalog file by crawling
a Maven repository located in the filesystem.
* Location of catalog files
The Archetype Plugin knows by default about its internal catalog. It also knows
about the <<<local>>> and <<<remote>>> catalogs.
<<<local>>> represents the <<<~/.m2/archetype-catalog.xml>>> catalog file.
<<<remote>>> represents the <<<http://repo.maven.apache.org/maven2/archetype-catalog.xml>>> catalog file.
The Archetype Plugin can also read catalogs from filesystem/HTTP by
providing the path/URL of a catalog file or of a directory containing an
<<<archetype-catalog.xml>>> file.