Author: ltheussl
Date: Sun Jul 23 15:17:13 2006
New Revision: 424841
URL: http://svn.apache.org/viewvc?rev=424841&view=rev
Log:
PR: MAVEN-1765
Submitted by: Jeff Jensen
Add a Basic Concepts page to Getting Started section.
Added:
maven/maven-1/core/trunk/xdocs/start/concepts.xml (with props)
Modified:
maven/maven-1/core/trunk/xdocs/navigation.xml
maven/maven-1/core/trunk/xdocs/start/index.xml
Modified: maven/maven-1/core/trunk/xdocs/navigation.xml
URL:
http://svn.apache.org/viewvc/maven/maven-1/core/trunk/xdocs/navigation.xml?rev=424841&r1=424840&r2=424841&view=diff
==============================================================================
--- maven/maven-1/core/trunk/xdocs/navigation.xml (original)
+++ maven/maven-1/core/trunk/xdocs/navigation.xml Sun Jul 23 15:17:13 2006
@@ -48,6 +48,7 @@
<!-- TODO [later]: clean up directory structure -->
<menu name="User's Guide">
<item name="Getting Started" collapse="true" href="/start/index.html">
+ <item name="Concepts" href="/start/concepts.html"/>
<item name="Installing" href="/start/install.html"/>
<item name="Building a Project" href="/start/quick-start.html"/>
<item name="Creating a Project" href="/start/ten-minute-test.html"/>
@@ -139,7 +140,7 @@
TODO [later]: overhaul development-process.xml and development directories
-->
<!-- until next year...
- <menu name="ApacheCon Europe 2005">
+ <menu name="ApacheCon Europe 2005">
<item name="ApacheCon Europe 2005" href="http://www.apachecon.com/";
img="http://apache.org/images/ac2005eu_135x50.gif"; />
</menu>
Added: maven/maven-1/core/trunk/xdocs/start/concepts.xml
URL:
http://svn.apache.org/viewvc/maven/maven-1/core/trunk/xdocs/start/concepts.xml?rev=424841&view=auto
==============================================================================
--- maven/maven-1/core/trunk/xdocs/start/concepts.xml (added)
+++ maven/maven-1/core/trunk/xdocs/start/concepts.xml Sun Jul 23 15:17:13 2006
@@ -0,0 +1,240 @@
+<?xml version="1.0"?>
+<!--
+/*
+ * 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.
+ */
+ -->
+
+<document>
+ <properties>
+ <title>Concepts to Understand Before Using Maven</title>
+ <author email="[EMAIL PROTECTED]">Jeff Jensen</author>
+ </properties>
+
+ <body>
+ <section name="Basic Maven Concepts">
+ <subsection name="Plugins">
+ <h4>What are Plugins?</h4>
+ <p>
+ Read the "Plugin" definition in the
+ <a href="../reference/glossary.html">glossary</a>.
+ </p>
+ <p>
+ Maven plugins implement the functionality.
+ For example, the "java" plugin does java operations
+ such as the "compile" goal.
+ </p>
+ <p>
+ Plugins are installed in the local Maven repository
+ along with the other non-plugin dependencies.
+ </p>
+ <p>
+ For plugin reference information,
+ refer to the <a
href="http://maven.apache.org/maven-1.x/plugins/index.html";>Plugins</a> page.
+ </p>
+ <p>
+ Maven 1 has two types of plugins: bundled and non-bundled.
+ See below for details on these plugin types.
+ </p>
+ <p>
+ Note that in Maven 2, all plugins are non-bundled.
+ </p>
+ <h4>Bundled Plugins</h4>
+ <p>
+ Bundled plugins are those that come with the Maven distribution.
+ Users need no additional actions to use them.
+ Refer to the
+ <a
href="http://maven.apache.org/maven-1.x/plugins/bundled/index.html";>Plugins
List</a>.
+ </p>
+ <h4>Non-Bundled Plugins</h4>
+ <p>
+ Non-bundled plugins are those that do not come with the Maven
distribution.
+ This is how Maven is expandable with new functionality -
+ anyone can create a Maven plugin.
+ Since these plugins do not ship with Maven,
+ the user must install them into the local Maven repository.
+ </p>
+ <p>
+ There are three ways to make a Maven plugin visible to your project:
+ </p>
+ <ol>
+ <li>
+ Declare the plugin as a dependency in the project.
+ Maven will then automatically download and
+ install it into the local repository.
+ <p>
+ This is typically the preferred method.
+ The benefits of this approach are:
+ </p>
+ <ul>
+ <li>Reproducibility: The project has plugin dependencies
documented in addition to jar dependencies.</li>
+ <li>Ease: The download and install is automatic for all
users/computers.</li>
+ <li>Snapshots: When the version is a SNAPSHOT, Maven always
checks for newer versions.</li>
+ </ul>
+ For example:
+<source><![CDATA[
+<dependency>
+ <groupId>maven-plugins</groupId>
+ <artifactId>maven-findbugs-plugin</artifactId>
+ <version>1.3</version>
+ <type>plugin</type>
+</dependency>
+]]></source>
+ <p>
+ Note that this method does not install the plugin into Maven's
plugin directory,
+ which means that the plugin will only be usable by the project
declaring
+ it as dependency. In order to permanently install a plugin and
make it visible
+ to all your projects, you should use one of the following
methods.
+ </p>
+ </li>
+ <li>
+ Use the "plugin:download" goal to
+ download the plugin and install it into Maven's plugin directory.
+ For example:
+<source>maven plugin:download -DgroupId=maven-plugins
-DartifactId=maven-findbugs-plugin -Dversion=1.3</source>
+ </li>
+ <li>
+ Alternatively to the above, you may just manually download and
install the plugin.
+ </li>
+ </ol>
+ <p>
+ Refer to the non-bundled plugins in the list on the
+ <a
href="http://maven.apache.org/maven-1.x/plugins/index.html";>Plugins</a> page.
+ </p>
+ </subsection>
+
+ <subsection name="Goals">
+ <p>
+ Read the "Goal" definition in the
+ <a href="../reference/glossary.html">glossary</a>.
+ </p>
+ <p>
+ Ant users run custom created "targets", Maven users run goals.
+ Usually, one runs pre-defined Maven goals
+ (the bundled or non-bundled plugins have the goals),
+ but sometimes users create their own goals in either
+ a new plugin or in the maven.xml file.
+ </p>
+ <p>
+ For example,
+ </p>
+ <source>maven java:compile</source>
+ <p>
+ compiles the Java source.
+ </p>
+ <p>
+ Note that you can run multiple goals one after the other
+ in the same invocation of Maven.
+ For example,
+ </p>
+ <source>maven faq xdoc</source>
+ <p>
+ runs the faq plugin followed by the xdoc plugin.
+ </p>
+ <p>
+ Note that some plugin goals cause other plugin goals to run first.
+ For example, running
+ </p>
+ <source>maven jar</source>
+ <p>
+ causes these goals to run in this order:
+ </p>
+ <ol>
+ <li>java:compile</li>
+ <li>test:test</li>
+ <li>jar:jar</li>
+ </ol>
+ <p>
+ Refer to the
+ <a href="index.html">Getting Started</a> and
+ <a href="../using/index.html">Using Maven</a>
+ pages for more info.
+ </p>
+
+ </subsection>
+
+ <subsection name="project.xml">
+ <p>
+ The project.xml file is the "POM" - project object model.
+ It contains the configuration information for the project.
+ </p>
+ <p>
+ Refer to the
+ <a href="../reference/project-descriptor.html">Project Descriptor</a>
+ on the Reference page for its info.
+ </p>
+ <p>
+ Refer to th
+ <a href="../using/customising.html#Project_Inheritence">Project
Inheritence</a>
+ section in
+ <a href="../using/customising.html">Customising Maven</a>
+ for more info.
+ </p>
+ </subsection>
+
+ <subsection name="project.properties">
+ <p>
+ Properties for the project are set in this file.
+ When a plugin lists customization properties,
+ this is the file to put them in.
+ </p>
+ <p>
+ When extending from another POM,
+ this file is inherited too.
+ </p>
+ <p>
+ In addition to plugin properties,
+ the Maven core itself has many properties.
+ </p>
+ <p>
+ Refer to the
+ <a href="../reference/properties.html">Properties Reference</a>
+ on the Reference page and the
+ <a
href="../using/customising.html#Extending_the_Build_with_Properties">Extending
the Build with Properties</a>
+ section in
+ <a href="../using/customising.html">Customising Maven</a>
+ for more info.
+ </p>
+ </subsection>
+
+ <subsection name="maven.xml">
+ <p>
+ Note, it is recommended to limit use of this file.
+ The maven.xml file can contain processing customization.
+ This includes
+ complete custom goals and
+ adding to the lifecycle of another plugin.
+ </p>
+ <p>
+ Refer to the
+ <a href="../reference/scripting.html">Scripting</a> section,
+ <a href="../using/customising.html">Customising Maven</a> and
+ <a href="../tags.html">Maven Jelly Tag Libraries</a>
+ for more info.
+ </p>
+ <p>
+ One of the best ways to understand maven.xml
+ is to look at ones in existing Maven projects,
+ including those in Maven source.
+ </p>
+ <p>
+ Note that Maven 2 does not have this file.
+ Instead, the plugins and the POM has all processing and
configuration.
+ </p>
+ </subsection>
+ </section>
+
+ </body>
+</document>
Propchange: maven/maven-1/core/trunk/xdocs/start/concepts.xml
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: maven/maven-1/core/trunk/xdocs/start/concepts.xml
------------------------------------------------------------------------------
svn:keywords = "Author Date Id Revision"
Modified: maven/maven-1/core/trunk/xdocs/start/index.xml
URL:
http://svn.apache.org/viewvc/maven/maven-1/core/trunk/xdocs/start/index.xml?rev=424841&r1=424840&r2=424841&view=diff
==============================================================================
--- maven/maven-1/core/trunk/xdocs/start/index.xml (original)
+++ maven/maven-1/core/trunk/xdocs/start/index.xml Sun Jul 23 15:17:13 2006
@@ -28,6 +28,7 @@
get Maven up and running on your system.
</p>
<ul>
+ <li><a href="concepts.html">Concepts</a> - Concepts to understand
before using Maven</li>
<li><a href="install.html">Installing</a> - Installation
instructions</li>
<li><a href="quick-start.html">Building a Project</a> - How to use
Maven to build a given project</li>
<li><a href="ten-minute-test.html">Creating a Project</a> - A 'Ten
Minute Test' on how to create a project with Maven</li>
![http://apache.org/images/ac2005eu_135x50.gif"](http://apache.org/images/ac2005eu_135x50.gif"){kind=link}