You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maven.apache.org by hb...@apache.org on 2010/04/10 03:21:45 UTC
svn commit: r932658 -
/maven/site/trunk/src/site/apt/guides/mini/guide-creating-archetypes.apt
Author: hboutemy
Date: Sat Apr 10 01:21:45 2010
New Revision: 932658
URL: http://svn.apache.org/viewvc?rev=932658&view=rev
Log:
updated the mini-guide:
o archetype.xml is preferred in META-INF/maven/ (META-INF/ only supported for backward compatibility)
o more strict difference between archetype *artifact* and archetype *plugin*
o links to descriptor reference
o added a note about 1.0.x and 2.0.x versions
Modified:
maven/site/trunk/src/site/apt/guides/mini/guide-creating-archetypes.apt
Modified: maven/site/trunk/src/site/apt/guides/mini/guide-creating-archetypes.apt
URL: http://svn.apache.org/viewvc/maven/site/trunk/src/site/apt/guides/mini/guide-creating-archetypes.apt?rev=932658&r1=932657&r2=932658&view=diff
==============================================================================
--- maven/site/trunk/src/site/apt/guides/mini/guide-creating-archetypes.apt (original)
+++ maven/site/trunk/src/site/apt/guides/mini/guide-creating-archetypes.apt Sat Apr 10 01:21:45 2010
@@ -3,61 +3,74 @@
------
Jason van Zyl, Alexander Hars, Franz Allan Valencia See
------
- 25 July 2006
+ 2010-04-10
------
Guide to Creating Archetypes
- Creating an archetype is a pretty straight forward process. An archetype is a
- very simple plugin, that contains the project prototype you wish to create.
- An archetype is made up of:
-
- * an archetype descriptor (<<<archetype.xml>>> in directory:
- <<<src/main/resources/META-INF/>>>). It lists all the files that will be
- contained in the archetype and categorizes them so they can be processed
+ Creating an archetype is a pretty straight forward process. An archetype is a
+ very simple artifact, that contains the project prototype you wish to create.
+ An archetype is made up of:
+
+ * an {{{http://maven.apache.org/archetype/archetype-common/archetype.html}archetype descriptor}}
+ (<<<archetype.xml>>> in directory:
+ <<<src/main/resources/META-INF/maven/>>>). It lists all the files that will be
+ contained in the archetype and categorizes them so they can be processed
correctly by the archetype generation mechanism.
- * the prototype files that are copied by the archetype (directory:
+ * the prototype files that are copied by the archetype plugin (directory:
<<<src/main/resources/archetype-resources/>>>)
- * the prototype pom (<<<pom.xml>>> in:
+ * the prototype pom (<<<pom.xml>>> in:
<<<src/main/resources/archetype-resources>>>)
* a pom for the archetype (<<<pom.xml>>> in the archetype's root directory).
- []
+ []
+
+ Note: this mini-guide has been written for
+ {{{http://maven.apache.org/plugins/maven-archetype-plugin-1.0-alpha-7/}archetype plugin version 1.0.x}}.
+ {{{http://maven.apache.org/archetype/maven-archetype-plugin/}Archetype plugin 2.0.x}} is a new generation
+ that fully supports archetypes created for 1.0.x, and adds a
+ {{{http://maven.apache.org/archetype/archetype-common/archetype.html}new archetype descriptor}}: it's
+ more fexible, has more features, but the basis si absolutely the same.
+
To create an archetype follow these steps:
-* 1. Create a new project and pom.xml for the archetype plugin
+* 1. Create a new project and pom.xml for the archetype artifact
+
+ An example <<<pom.xml>>> for an archetype artifact looks as follows:
- An example <<<pom.xml>>> for an archetype plugin looks as follows:
-
-+----+
++----+
-<project>
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
+
<groupId>my.groupId</groupId>
<artifactId>my-archetype-id</artifactId>
<version>1.0-SNAPSHOT</version>
<packaging>jar</packaging>
</project>
-+----+
++----+
- All you need to specify is a <<<groupId>>>, <<<artifactId>>> and
- <<<version>>>. These three parameters will be needed later for invoking the
+ All you need to specify is a <<<groupId>>>, <<<artifactId>>> and
+ <<<version>>>. These three parameters will be needed later for invoking the
archetype via <<<archetype:create>>> from the commandline.
* 2. Create the archetype descriptor
- The archetype descriptor is a file called <<<archetype.xml>>> which must be
- located in the <<<src/main/resources/META-INF/>>> directory. An example of an archetype
- descriptor can be found in the quickstart archetype:
+ The {{{http://maven.apache.org/archetype/archetype-common/archetype.html}archetype descriptor}}
+ is a file called <<<archetype.xml>>> which must be
+ located in the <<<src/main/resources/META-INF/maven/>>> directory. An example of an archetype
+ descriptor can be found in the quickstart archetype:
+----+
-<archetype>
+<archetype xmlns="http://maven.apache.org/plugins/maven-archetype-plugin/archetype/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/plugins/maven-archetype-plugin/archetype/1.0.0 http://maven.apache.org/xsd/archetype-1.0.0.xsd">
<id>quickstart</id>
<sources>
<source>src/main/java/App.java</source>
@@ -69,14 +82,14 @@ Guide to Creating Archetypes
+----+
- The <<<\<id\>>>> tag should be the same as the <<<artifactId>>> in the
- archetype <<<pom.xml>>>.
+ The <<<\<id\>>>> tag should be the same as the <<<artifactId>>> in the
+ archetype <<<pom.xml>>>.
- An optional <<<\<allowPartial\>true\</allowPartial\>>>> tag makes it possible
- to run the <<<archetype:create>>> even on existing projects.
+ An optional <<<\<allowPartial\>true\</allowPartial\>>>> tag makes it possible
+ to run the <<<archetype:create>>> even on existing projects.
- The <<<\<sources\>>>>, <<<\<resources\>>>>, <<<\<testSources\>>>>, <<<\<testResources\>>>> and
- <<<\<siteResources\>>>> tags represent the different sections of the project:
+ The <<<\<sources\>>>>, <<<\<resources\>>>>, <<<\<testSources\>>>>, <<<\<testResources\>>>> and
+ <<<\<siteResources\>>>> tags represent the different sections of the project:
* <<<\<sources\>>>> = <<<src/main/java>>>
@@ -86,24 +99,24 @@ Guide to Creating Archetypes
* <<<\<testResources\>>>> = <<<src/test/resources>>>
- * <<<\<siteResources\>>>> = <<<src/site>>>
+ * <<<\<siteResources\>>>> = <<<src/site>>>
[]
- <<<\<sources\>>>> and <<<\<testSources\>>>> can contain <<<\<source\>>>>
- elements that specify a source file.
+ <<<\<sources\>>>> and <<<\<testSources\>>>> can contain <<<\<source\>>>>
+ elements that specify a source file.
- <<<\<testResources\>>>> and <<<\<siteResources\>>>> can contain
- <<<\<resource\>>>> elements that specify a resource file.
+ <<<\<testResources\>>>> and <<<\<siteResources\>>>> can contain
+ <<<\<resource\>>>> elements that specify a resource file.
- Place other resources such as the ones in the <<<src/main/webapp>>> directory
+ Place other resources such as the ones in the <<<src/main/webapp>>> directory
inside the <<<\<resources\>>>> tag.
At this point one can only specify individual files to be created but not empty
- directories.
+ directories.
- Thus the quickstart archetype shown above defines the following directory
- structure:
+ Thus the quickstart archetype shown above defines the following directory
+ structure:
+----+
@@ -129,24 +142,28 @@ archetype
* 3. Create the prototype files and the prototype pom.xml
- The next component of the archetype to be created is the prototype
- <<<pom.xml>>>. Any <<<pom.xml>>> will do, just don't forget to the set
- <<<artifactId>>> and <<<groupId>>> as variables ( <<<$\{artifactId\}>>> /
- <<<$\{groupId\}>>> ). Both variables will be initialized from the commandline
- when calling <<<archetype:create>>>.
+ The next component of the archetype to be created is the prototype
+ <<<pom.xml>>>. Any <<<pom.xml>>> will do, just don't forget to the set
+ <<<artifactId>>> and <<<groupId>>> as variables ( <<<$\{artifactId\}>>> /
+ <<<$\{groupId\}>>> ). Both variables will be initialized from the commandline
+ when calling <<<archetype:create>>>.
- An example for a prototype <<<pom.xml>>> is:
+ An example for a prototype <<<pom.xml>>> is:
+----+
-<project>
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
+
<groupId>${groupId}</groupId>
<artifactId>${artifactId}</artifactId>
- <packaging>jar</packaging>
<version>${version}</version>
+ <packaging>jar</packaging>
+
<name>A custom project</name>
<url>http://www.myorganization.org</url>
+
<dependencies>
<dependency>
<groupId>junit</groupId>
@@ -159,52 +176,52 @@ archetype
+----+
-* 4. Install and run the archetype
+* 4. Install the archetype and run the archetype plugin
- Now you are ready to install the archetype:
+ Now you are ready to install the archetype:
+----+
-mvn install
+mvn install
+----+
- Now that you have created an archetype you can try it on your local system by
- using the following command. In this command, you need to specify the full
- information about the archetype you want to use (its <<<groupId>>>, its
- <<<artifactId>>>, its <<<version>>>) and the information about the new project
- you want to create (<<<artifactId>>> and <<<groupId>>>). Don't forget to
- include the version of your archetype (if you don't include the version, you
- archetype creation may fail with a message that version:RELEASE was not found)
+ Now that you have created an archetype, you can try it on your local system by
+ using the following command. In this command, you need to specify the full
+ information about the archetype you want to use (its <<<groupId>>>, its
+ <<<artifactId>>>, its <<<version>>>) and the information about the new project
+ you want to create (<<<artifactId>>> and <<<groupId>>>). Don't forget to
+ include the version of your archetype (if you don't include the version, you
+ archetype creation may fail with a message that version:RELEASE was not found)
+----+
mvn archetype:create \
-DarchetypeGroupId=<archetype-groupId> \
- -DarchetypeArtifactId=<archetype-artifactId> \
+ -DarchetypeArtifactId=<archetype-artifactId> \
-DarchetypeVersion=<archetype-version> \
-DgroupId=<my.groupid> \
- -DartifactId=<my-artifactId>
+ -DartifactId=<my-artifactId>
+----+
- Once you are happy with the state of your archetype you can deploy (or submit
- it to ibiblio) it as any other artifact and the archetype will then be
+ Once you are happy with the state of your archetype, you can deploy (or submit
+ it to ibiblio) it as any other artifact and the archetype will then be
available to any user of Maven.
-
+
* Alternative way to start creating your Archetype
-
- Instead of manually creating the directory structure needed for an archetype,
- simply use
-
+
+ Instead of manually creating the directory structure needed for an archetype,
+ simply use
+
+------+
-mvn archetype:create
+mvn archetype:create
-DgroupId=[your project's group id]
-DartifactId=[your project's artifact id]
-DarchetypeArtifactId=maven-archetype-archetype
+------+
Afterwhich, you can now customize the contents of the <<<archetype-resources>>>
- directory, and <<<archetype.xml>>>, then, proceed to Step#4 (Install and run
+ directory, and <<<archetype.xml>>>, then, proceed to Step#4 (Install the archetype and run
the archetype plugin).