You are viewing a plain text version of this content. The canonical link for it is here.
Posted to users@maven.apache.org by Sébastien BRUNOT <sb...@octo.com> on 2004/03/18 09:58:17 UTC
RE : RE : More visual project descriptor documentation
In fact, it is not documented at all.
Sebastien
-----Message d'origine-----
De : dion@multitask.com.au [mailto:dion@multitask.com.au]
Envoyé : jeudi 18 mars 2004 01:06
À : Maven Users List
Objet : RE : More visual project descriptor documentation
There currently is a complete project.xml as part of the documentation.
See http://maven.apache.org/start/integrate.html
It's not terribly well documented though.
--
dIon Gillard, Multitask Consulting
Sébastien BRUNOT <sb...@octo.com> wrote on 18/03/2004 03:54:51 AM:
> Hi,
>
> Another idea could be the release of a sample COMPLETE project.xml
> documented. The documentation need to be completed first (for example
> : what is the connection string for a subversion repository ?). Here
> is my personal file for that (named project.xml.template) :
>
> <================ BEGINING OF THE FILE
> ======================================================================
> ==
> ===========>
> <?xml version="1.0" encoding="ISO-8859-1"?>
> <project>
>
> <!-- the version of maven's project object model -->
> <pomVersion>3</pomVersion>
>
> <!-- a unique name for this project -->
> <id>SampleJ2EE</id>
>
> <!-- a short but descriptive name for the project -->
> <name>A Sample J2EE project to compare ant versus maven build
> process</name>
>
> <!-- The version of the project under development, e.g.
1.
> 1, 1.2, 2.0-SNAPSHOT -->
> <currentVersion>1.0-SNAPSHOT</currentVersion>
>
> <!-- details about the organization that 'owns' the project -->
> <organization>
> <!-- The full name of the organization. -->
> <name>Octo Technology</name>
> <!-- The URL to the organization's home page. -->
> <url>http://www.octo.com/</url>
> <!-- The URL to the organization's logo image. This can be an
> URL
relative to the base directory of the generated
web
> site, (e.g., /images/org-logo.png) or an absolute URL
(e.g., http:
> //my.corp/logo.png). This value is used
when generating the
> project documentation. -->
> <logo>http://images/octo-logo.jpg</logo>
> </organization>
>
> <!-- the year the project started -->
> <inceptionYear>2003</inceptionYear>
>
> <!-- The Java package name of the project. This value is used when
>
generating JavaDoc. -->
> <package>com.octo.j2ee.sample</package>
>
> <!-- The URL to the project's logo image. This can be an URL
> relative
to the base directory of the generated web site,
(e.
> g., /images/project-logo.png) or an absolute URL (e.g.,
http://my.
> corp/project-logo.png). This is used when
generating the
> project documentation.-->
> <logo>/images/project-logo.jpg</logo>
>
> <!-- Optional. This is the Id of the Gump repository that this
> project
is part of (assuming it participates in the Gump
> integration effort).-->
> <gumpRepositoryId/>
>
> <!-- Optional. A detailed description of the project. This element
> is
usually specified as CDATA to enable the use of HTML
tags
> within the description. This description is used to generate
the
> front page of the project's web site.-->
> <description>
> This project is a sample J2EE project that is build with maven.
> The following maven sub projects are used : TO BE CONTINUED
> </description>
>
> <!-- a short description of what the project does -->
> <shortDescription>
> How to use maven for building a j2ee project.
> </shortDescription>
>
> <!-- the url to the project home page -->
> <url>http://localhost/samplej2ee</url>
>
> <!-- Optional. The URL to the project's issue tracking system. -->
> <issueTrackingUrl/>
>
> <!-- Optional. The hostname of the web server that hosts the
> project's
web site. This is used when the web site is deployed. -->
> <siteAddress>localhost</siteAddress>
>
> <!-- Optional. The directory on the web server where the public
> web
site for this project resides. This is used when the web site is
>
deployed. -->
> <siteDirectory>C:/Documents and Settings/sbrunot/Mes
> documents/www/samplej2ee</siteDirectory>
>
> <!-- Optional. The server server where the final distributions
> will be
published. This is used when the distributions are deployed.
>
If this isn't defined, the central repository is used
> instead as
determined by maven.repo.central and maven.repo.central.
> directory
-->
> <distributionDirectory/>
>
> <!-- Information relating to the source configuration management
> system used by this project. -->
> <repository>
> <!-- Optional. The source configuration management system URL
> that
describes the repository and how to connect to the repository.
>
This is used by Maven when building versions from specific
> ID.
The format of this element is as follows:
scm:<provider>:
> <provider-parameters>
For cvs, the format for pserver
> repositories should be:
scm:cvs:pserver:user@host:
> /cvs/root:module-name
For local networked repositories (eg.
> pserver to local machine)
scm:cvs:lserver:user@host:
> /cvs/root:module-name
For ssh access:
scm:
> cvs:ext:user@host:/cvs/root:module-nameRemember that
CVS will expect
> an environment variable called CVS_RSH to be set,
typically to ssh
> or your ssh client.
Some cvs clients support other
> protocols, such as ntserver and
extssh. Here's an example using CVS
> NT and ntserver:
scm|cvs|ntserver|user@server|e:
> \cvs|DeploymentNote the use of
the vertical bar as delimiter as the
> repository has a colon (:) in it.
For local file system
> repositories
scm:cvs:local:ignored:/cvs/root:module-
> name
The delimiter is determined by the character after
> "scm". eg.
scm|cvs|pserver|user@host|/cvs/root|module-name is
> equivalent to that
listed above.
This can be useful for
> Windows users who have : in their
cvsroot parameter (eg. D:\cvsroot)
>
Where pserver is the protocol used to access CVS,
> user@host is
the user name to log in to the specified cvs host,
> /cvs/root is the cvs
root directory,
and module-name is
> the name of the cvs module to be worked on
As an example,
> the settings for an Apache project are usually:
scm:cvs:pserver:
> anoncvs@cvs.apache.org:/home/cvspublic:module-name
> Currently CVS, Starteam and SubVersion are the only supported
scm's.
> Others will be added as soon as possible
-->
> <connection/>
> <!-- Optional. Just like connection, but for developers, i.e.
> this
scm connection will not be read only. -->
> <developerConnection/>
> <!-- Optional. The URL to the project's browsable CVS repository
-->
> <url/>
> </repository>
>
> <!-- Optional. Contains information on previous versions of the
> project. This information is used when invoking the maven:dist target.
-->
> <versions>
> <!-- A unique identifier for a version. This ID is used to
> specify
the version that maven:dist builds. -->
> <id/>
> <!-- The external version number under which this release was
> distributed. Examples include: 1.0, 1.1-alpha1, 1.2-beta, 1.3.2 etc.
-->
> <name/>
> <!-- The name given in the version control system (e.g. cvs)
> used by
the project for the source code associated with this version
> of the
project.-->
> <tag/>
> </versions>
>
> <!-- Optional. Contains information on branches of the project.
> This
information is used when invoking the maven:dist target. Each
> branch
is described by a tag element-->
> <branches>
> <!-- The branch tag in the version control system (e.g. cvs)
> used by
the project for the source code associated with this branch
> of the
project. -->
> <tag/>
> </branches>
>
> <!-- Contains information about a project's mailing lists. This is
>
used to generate the front page of the site's web site. -->
> <mailingLists>
> <!-- Each mailing list is described by a mailingList element,
> which
is then described by additional elements (described below).
> The auto-generated site documentation references this
information. -->
> <mailingList>
> <!-- The name of the mailing list. -->
> <name/>
> <!-- The email address or link that can be used to subscribe
> to
the mailing list. If this is an email address, a mailto: link
> will
automatically
be created when the documentation is created.-->
> <subscribe/>
> <!-- The email address or link that can be used to unsubscribe
> to
the mailing list. If this is an email address, a mailto: link
> will
automatically
be created when the documentation is
> created.-->
> <unsubscribe/>
> <!-- The link to a URL that can browse the archive. -->
> <archive/>
> </mailingList>
> </mailingLists>
>
> <!-- Describes the committers to a project. This is used to
> generate
the Project Team page of the project's web site. -->
> <developers>
> <!-- Each developer is described by a developer element, which
> is
then described by additional elements (described below).
> The auto-generated site documentation references this
information.-->
> <developer>
> <!-- The full name of the developer. -->
> <name>Sebastien Brunot</name>
> <!-- The username of the developer. -->
> <id>sbrunot</id>
> <!-- The email address of the developer. -->
> <email>sbrunot@octo.com</email>
> <!-- The organization to which the developer belongs.-->
> <organization>Octo Technology</organization>
> <!-- The roles the developer plays in the project. Each role
> is
describe by a role element, the body of which is a role name. -->
> <roles>
> <role>developer</role>
> </roles>
> <!-- The URL for the homepage of the developer -->
> <url/>
> <!-- The timezone the developer is in. This is a number in the
>
range -14 to 14. -->
> <timezone>1</timezone>
> </developer>
> </developers>
>
> <!-- Describes the contributors to a project. This is used to
> generate
the Project Team page of the project's web site.
> Same as <developers> but with <contributor> tags -->
> <contributors/>
>
> <!-- Describes the licenses for this project. This is used to
> generate
the License page of the project's web site.
> Typically the licenses listed for the project are that of the
> project itself, and not of dependencies.-->
> <licences>
> <!-- Each license is described by a license element, which is
> then
describe by additional elements (described below).
The
> auto-generated site documentation references this
information.
> Projects should only list the license(s) that
applies to
> the project and not the licenses that apply to
dependencies.-->
> <licence>
> <!-- The full legal name of the license. -->
> <name/>
> <!-- The official url for the license text. -->
> <url/>
> <!-- The primary method by which this project may be
> distributed.
repo : may be downloaded from the Maven
> repository
manual : user must manually download and
> install the
dependency.-->
> <distribution/>
> </licence>
> </licences>
>
> <!-- Describes the dependencies to a project. This is used to when
>
building a project. -->
> <dependencies>
> <!-- Each dependency is described by a dependency element, which
> is
then described by additional elements (described below).
> These dependencies are used to construct a classpath for your
> project during the build process.
Maven can automatically
> download these dependencies from a
remote repository.
The
> filename that Maven downloads from the repository is
artifactId-
> version.jar where artifactId corresponds to the
artifactId
> element and version corresponds to the version
element.
> When Maven goes looking for a dependency in the remote
repository,
> it uses the dependency element to construct the URL
to
> download from. This URL is defined as:
${repo}
> /${groupId}/${type}s/${artifactId}-${version}.${type}
Where
>
repo is the remote repository URL specified by ${maven.
> repo.remote}
groupId is taken from the dependency
> element
type is taken from the dependency element
> artifactId is taken from the dependency element
version
> is taken from the dependency element
-->
> <dependency>
> <!-- The project group that produced the dependency, e.g. jboss.
-->
> <groupId/>
> <!-- The unique id for an artifact produced by the project
> group,
e.g. jboss-boot -->
> <artifactId/>
> <!-- The version of the dependency., e.g. 3.2.1 -->
> <version/>
> <!-- The name of jar file if it doesn't respect
<artifactId>-
> <version>.jar pattern.-->
> <jar/>
> <!-- The type of dependency. This defaults to jar.
> Other known and recognised dependency types are: ejb and
plugin. -->
> <type/>
> <!-- The url of the dependency's homepage.
This
> url will be provided to the user if the jar file cannot
be
> downloaded from the central repository. -->
> <url/>
> <!-- Properties about the dependency. Various plugins allow
> you to
mark dependencies with properties. For example
> the war plugin looks for a war.bundle property, and if found
will
> include the dependency in WEB-INF/lib.
For example
> syntax, check the war plugin docs. -->
> <properties/>
> </dependency>
> </dependencies>
>
> <!-- build information for the project -->
> <build>
> <!-- An address to which notifications regarding the status of
> builds for this project can be sent.
This is intended for
> use by tools which do unattended builds,
for example those providing
> for
continuous integration. Currently this is used by the
> maven:gump-descriptor target -->
>
>
<nagEmailAddress>turbine-maven-dev@jakarta.apache.org</nagEmailAddress>
> <!-- This element specifies a directory containing the source of
> the
project. The generated build system
will compile the
> source in this directory when the project is
built. The path given
> is relative to
the project descriptor. -->
> <sourceDirectory>src/java</sourceDirectory>
> <!-- This element specifies how source code will be excluded or
> included depending on the presence of a given
class.-->
> <sourceModification>
> <!-- If the class with this name can not be loaded, then the
> includes and excludes specified below will be
applied to
> the contents of the sourceDirectory
Note: not all plugins
> support the sourceModifications
element. -->
> <className/>
> <!-- Describe the files to be included if the class was not
found
-->
> <includes>
> <!-- This element specifies an Ant pattern of files to
> include
in a list. -->
> <include/>
> </includes>
> <!-- Describe the files to be excluded if the class was not
found
-->
> <excludes>
> <!-- This element specifies an Ant pattern of files to
> exclude
from a list. -->
> <exclude/>
> </excludes>
> </sourceModification>
> <!-- This element specifies a directory containing the unit test
>
source of the project.
The generated build system will
> compile these directories when
the project is being tested.
> The unit tests must use the JUnit test framework. The path
given is
> relative to the project descriptor.-->
> <unitTestSourceDirectory>src/test</unitTestSourceDirectory>
> <!-- This element specifies a directory containing Aspect
> sources of
the project. The generated build system will
> compile the Aspects in this directory when the project is built
if
> Aspects have been enabled (see the Aspectj
goals
> document). The path given is relative to the project
descriptor. -->
> <aspectSourceDirectory/>
> <!-- This element specifies unit tests associated with the
project.-->
> <unitTest>
> <!-- Describe the includes unit tests -->
> <includes>
> <!-- This element specifies an Ant pattern of files to
> include
in a list. -->
> <include>**/*Test.java</include>
> </includes>
> <!-- Describe the excludes unit tests -->
> <excludes>
> <!-- This element specifies an Ant pattern of files to
> exclude
from a list. -->
> <exclude>**/NaughtyTest.java</exclude>
> </excludes>
> </unitTest>
> <!-- This element describes all of the resources associated with
> a
project or unit tests. Each resource is described
by a
> resource element, which is then described by additional
elements
> (described below). These resources are
used to complete
> the jar file or to run unit test. -->
> <resources>
> <!-- Each resource must be defined in a resource element. -->
> <resource>
> <!-- Describe the directory where the resource is stored.
> The
path may be absolute, or relative to the project.xml file. -->
> <directory>src/conf</directory>
> <!-- Describe the resource target path. For example, if you
> want
that resource appear into a specific package
(org.
> apache.maven.messages), you must specify this element
with this
> value : org/apache/maven/messages -->
> <targetPath/>
> <!-- Describe the includes files to the project -->
> <includes>
> <!-- This element specifies an Ant pattern of files to
> include
in a list. -->
> <include>*.properties</include>
> </includes>
> <!-- Describe the excludes files to the project -->
> <excludes>
> <!-- This element specifies an Ant pattern of files to
> exclude
in a list. -->
> <exclude/>
> </excludes>
> <!-- Boolean. Describe if resources are filtered or not. -->
> <filtering/>
> </resource>
> </resources>
> </build>
>
> <!-- This element includes the specification of reports to be
> included
in a Maven-generated site. These reports will
be
> run when a user executes maven site. All of the reports will
be
> included in the navigation bar for browsing
in the order
> they are specified. -->
> <reports>
> <!-- The name of the report that should be run when the site is
> generated. There is an established naming convention
that
> is to be used when specifying reports. If you want the
report that
> is generated by a plugin called xyz, then
you would
> specify the following for the value of this element:
maven-xyz-plugin.-->
> <report/>
> </reports>
>
> <!-- Project properties that will be used by various plugins -->
> <properties/>
> </project>
> <================ END OF THE FILE
>
========================================================================
> ================>
>
> Anyway, i have a pray for maven authors : please DOCUMENT WHAT YOU DO
!
> Some clients of mine rejected maven because of
> the lack of real documentation (example : What is the list of variable
> used by maven and its different plugins ? What is
> The grammaticaly correct syntax for a jelly expression ?).
>
> Sebastien
>
> -----Message d'origine-----
> De : Jean-Marc Lavoie [mailto:jmlavoie@trisotech.com]
> Envoyé : mercredi 17 mars 2004 16:47
> À : Maven Users List
> Objet : RE: More visual project descriptor documentation
>
>
> The representation is great, it will be perfect with the proposed
> enhancements.
>
>
> My in first experience with maven projects, I had to create all the
> folder structure, with some errors. Then I discoved the genapp plugin.
> The plugin provides a sample POMS that provides a really great start.
I
> think the plugin should be introduced in the "getting started" section
> to allow user not to start from scratch. This would remove lot of
> questions like resouces in jars, jars creation, JUnits, what to
include
> in the file, and malformed project files as you start with a working
> pom. Then the section you're working one would become an advance
topic,
> as people getting there would already have something working for most
of
> the cases, instead of getting there to create new pom sections.
>
>
>
>
> > -----Original Message-----
> > From: Erik Husby [mailto:mhusby@broad.mit.edu]
> > Sent: Wednesday, March 17, 2004 10:31 AM
> > To: Maven Users List
> > Subject: Re: More visual project descriptor documentation
> >
> >
> > Definitely a step in the right direction. I too think that more
> > indentation is required.
> >
> > Also, visually indicating what elements are required and which are
> > optional would be good. I am sure that this can get tricky but would
> > really help. Or perhaps we can gather a set of example POM's
> > along the
> > lines of:
> >
> > 1. A basic POM that can compile, jar, and test a project.
> > 2. A POM that can compile, jar, test, and install a jar into a local
> > repository.
> > 3. A POM that can compile, jar, test, install, and generate a site.
> >
> > And I am sure that there are some others that would spring to mind.
> >
> > --
> > Erik Husby
> > Team Lead for Software Quality Automation
> > Genome Center at MIT
> > Rm. 2192
> > 320 Charles St
> > Cambridge, MA 02141-2023
> > mobile: 781.354.6669
> > office: 617.258.9227
> > mhusby@broad.mit.edu
> >
> >
> >
> >
---------------------------------------------------------------------
> > To unsubscribe, e-mail: users-unsubscribe@maven.apache.org
> > For additional commands, e-mail: users-help@maven.apache.org
> >
> >
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: users-unsubscribe@maven.apache.org
> For additional commands, e-mail: users-help@maven.apache.org
>
>
> ---
> Incoming mail is certified Virus Free.
> Checked by AVG anti-virus system (http://www.grisoft.com).
> Version: 6.0.614 / Virus Database: 393 - Release Date: 05/03/2004
>
>
> ---
> Outgoing mail is certified Virus Free.
> Checked by AVG anti-virus system (http://www.grisoft.com).
> Version: 6.0.614 / Virus Database: 393 - Release Date: 05/03/2004
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: users-unsubscribe@maven.apache.org
> For additional commands, e-mail: users-help@maven.apache.org
>
---
Incoming mail is certified Virus Free.
Checked by AVG anti-virus system (http://www.grisoft.com).
Version: 6.0.614 / Virus Database: 393 - Release Date: 05/03/2004
---
Outgoing mail is certified Virus Free.
Checked by AVG anti-virus system (http://www.grisoft.com).
Version: 6.0.614 / Virus Database: 393 - Release Date: 05/03/2004
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@maven.apache.org
For additional commands, e-mail: users-help@maven.apache.org