maven-archetype/maven-archetype-plugin/src/site/apt/examples/archetype.apt

 ------
 Guide to Creating Archetypes
 ------
 Jason van Zyl, Alexander Hars, Franz Allan Valencia See
 ------
 25 July 2006
 ------

~~ Copyright 2006 The Apache Software Foundation.
~~
~~ Licensed 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

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 
   correctly by the archetype generation mechanism.

 * the prototype files that are copied by the archetype (directory: 
   <<<src/main/resources/archetype-resources/>>>)

 * the prototpye pom (<<<pom.xml>>> in: 
   <<<src/main/resources/archetype-resources>>>)

 * a pom for the archetype (<<<pom.xml>>> in the archetype's root directory).

 [] 

 To create an archetype follow these steps:

* 1. Create a new project and pom.xml for the archetype plugin

  An example <<<pom.xml>>> for an archetype plugin looks as follows: 
 
+----+ 

<project>
  <modelVersion>4.0.0</modelVersion>
  <groupId>my.groupId</groupId>
  <artifactId>my-archetype-id</artifactId>
  <version>1.0-SNAPSHOT</version>
  <packaging>maven-plugin</packaging>
</project>

+----+ 

  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 <<<src/main/resources/META-INF/>>> An example for an archetype 
 descriptor can be found in the quickstart archetype: 

+----+

<archetype>
  <id>quickstart</id>
  <sources>
    <source>src/main/java/App.java</source>
  </sources>
  <testSources>
    <source>src/test/java/AppTest.java</source>
  </testSources>
</archetype>

+----+

 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. 

 The <<<\<sources\>>>>, <<<\<resources\>>>>, <<<\<testResources\>>>> and 
 <<<\<siteResources\>>>> tags represent the different sections of the project: 

 * <<<\<sources\>>>> = <<<src/main/java>>>

 * <<<\<resources\>>>> = <<<src/main/resources>>>

 * <<<\<testSources\>>>> = <<<src/test/java>>>

 * <<<\<testResources\>>>> = <<<src/test/resources>>>

 * <<<\<siteResources\>>>> = <<<src/site>>> 

 []

 <<<\<sources\>>>> and <<<\<testSources\>>>> can contain <<<\<source\>>>> 
 elements that specify a source 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 
 inside the <<<\<resources\>>>> tag.

 At this point one can only specify individual files to be created but not empty
 directories. 

 Thus the quickstart archetype shown above defines the following directory 
 structure: 

+----+

archetype
|-- pom.xml
`-- src
    `-- main
        `-- resources
            |-- META-INF
            |   `-- archetype.xml
            `-- archetype-resources
                |-- pom.xml
                `-- src
                    |-- main
                    |   `-- java
                    |       `-- App.java
                    `-- test
                        `-- java
                            `-- AppTest.java

+----+

* 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>>>.   

 An example for a prototype <<<pom.xml>>> is: 

+----+

<project>
  <modelVersion>4.0.0</modelVersion>
  <groupId>${groupId}</groupId>
  <artifactId>${artifactId}</artifactId>
  <packaging>jar</packaging>
  <version>${version}</version>
  <name>A custom project</name>
  <url>http://www.myorganization.org</url>
  <dependencies>
    <dependency>
      <groupId>junit</groupId>
      <artifactId>junit</artifactId>
      <version>3.8.1</version>
      <scope>test</scope>
    </dependency>
  </dependencies>
</project>

+----+

* 4. Install and run the archetype

 Now you are ready to install the archetype: 

+----+

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) 


+----+

mvn archetype:create                                    \
  -DarchetypeGroupId=<archetype-groupId>                \
  -DarchetypeArtifactId=<archetype-artifactId>          \ 
  -DarchetypeVersion=<archetype-version>                \
  -DgroupId=<my.groupid>                                \
  -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 
 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 
 
+------+
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 
 the archetype plugin).