 ------
 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/doxia/references/apt-format.html


Archetype creation

    Creating an archetype from an existing project involves three steps:

    * the archetype resolution

    * the archetype installation:deployment

    * the archetype usage

    []


Usage

    Calling <<<mvn archetype:create-from-project>>> the plugin first resolves
    the package by guessing the project directory.

    It then generates the directory tree of the archetype in the
    <<<target/generated-sources/archetype>>> directory.

+---
mvn archetype:create-from-project
[INFO] Scanning for projects...
[INFO] Searching repository for plugin with prefix: 'archetype'.
[INFO] ------------------------------------------------------------------------
[INFO] Building project
[INFO]    task-segment: [archetype:create-from-project]
[INFO] ------------------------------------------------------------------------
[INFO] Preparing archetype:create-from-project
[INFO] No goals needed for project - skipping
[INFO] Setting property: classpath.resource.loader.class => 'org.codehaus.plexus.velocity.ContextClassLoaderResourceLoader'.
[INFO] Setting property: velocimacro.messages.on => 'false'.
[INFO] Setting property: resource.loader => 'classpath'.
[INFO] Setting property: resource.manager.logwhenfound => 'false'.
[INFO] [archetype:create-from-project]
[INFO] Setting default archetype's groupId: com.company
[INFO] Setting default archetype's artifactId: project
[INFO] Setting default archetype's version: 1.0-SNAPSHOT
[INFO] Setting default groupId: com.company
[INFO] Setting default artifactId: project
[INFO] Setting default version: 1.0-SNAPSHOT
[INFO] Setting default package: com.company.project
[INFO] Archetype created in target/generated-sources/archetype
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 4 seconds
[INFO] Finished at: Fri Feb 22 21:49:52 GMT 2008
[INFO] Final Memory: 10M/26M
[INFO] ------------------------------------------------------------------------
+---

    Then move to that generated directory and call <<<mvn install>>> on the
    created archetype.

+---
$ cd target/generated-sources/archetype/
$ mvn install
[INFO] Scanning for projects...
[INFO] ------------------------------------------------------------------------
[INFO] Building project
[INFO]    task-segment: [install]
[INFO] ------------------------------------------------------------------------
[INFO] [resources:resources]
[INFO] Using default encoding to copy filtered resources.
[INFO] [resources:testResources]
[INFO] Using default encoding to copy filtered resources.
[INFO] Setting property: classpath.resource.loader.class => 'org.codehaus.plexus.velocity.ContextClassLoaderResourceLoader'.
[INFO] Setting property: velocimacro.messages.on => 'false'.
[INFO] Setting property: resource.loader => 'classpath'.
[INFO] Setting property: resource.manager.logwhenfound => 'false'.
[INFO] [archetype:jar]
[INFO] [archetype:add-archetype-metadata]
[INFO] [archetype:integration-test]
[INFO] [install:install]
[INFO] Installing /home/local/rafale/projects/tmp/project/target/generated-sources/archetype/target/project-1.0-SNAPSHOT.jar to /home/rafale/.m2/repository/com/company/project/1.0-SNAPSHOT/project-1.0-SNAPSHOT.jar
[INFO] [archetype:update-local-catalog]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 10 seconds
[INFO] Finished at: Fri Feb 22 21:51:57 GMT 2008
[INFO] Final Memory: 14M/35M
[INFO] ------------------------------------------------------------------------
+---

    Finally move to a fresh directory and use your archetype.

+---
$ mkdir /tmp/archetype
$ cd /tmp/archetype
$ mvn archetype:generate -DarchetypeCatalog=local
[INFO] Scanning for projects...
[INFO] Searching repository for plugin with prefix: 'archetype'.
[INFO] ------------------------------------------------------------------------
[INFO] Building Maven Default Project
[INFO]    task-segment: [archetype:generate] (aggregator-style)
[INFO] ------------------------------------------------------------------------
[INFO] Preparing archetype:generate
[INFO] No goals needed for project - skipping
[INFO] Setting property: classpath.resource.loader.class => 'org.codehaus.plexus.velocity.ContextClassLoaderResourceLoader'.
[INFO] Setting property: velocimacro.messages.on => 'false'.
[INFO] Setting property: resource.loader => 'classpath'.
[INFO] Setting property: resource.manager.logwhenfound => 'false'.
[INFO] [archetype:generate]
Choose archetype:
1: local -> project (project)
Choose a number or apply filter (format: [groupId:]artifactId, case sensitive contains): 1:
+---

Testing
	
	The user can provide archetype test projects by placing them in <<<src/it/projects>>>
	folder of their project. Upon creating archetype from the existing project all the test
	projects will be executed to verify the archetype created by this project is good.
	{{{./integration-test-mojo.html}Read more}} about testing maven archetype.

Configuration

    The <<<create-from-project>>> goal enable the user to provide some sensible
    configuration using the system properties or a property file.

    The system properties permits the user to define the groupId, artifactId,
    version of the created archetype. They also permits to override the resolved
    package and to create a partial archetype.

    When used, the property file takes precedence over the system properties.
    It is also the only way to define additional properties in the archetype.
    
Post-generation script

	If the user wants to customize the generated project even further, a groovy script
	named <<<archetype-post-generate.groovy>>> can be added in <<<src/main/resources/META-INF/>>>.
	This script will end up in the generated archetype's <<<META-INF>>> folder and will be executed
	upon creating a project from this archetype. This groovy script has access to the 
	<<<ArchetypeGenerationRequest>>> object, as well as all the <<<System.getProperties()>>> and all
	the archetype generation properties the user has specified.