Difference between revisions of "Maven distro directory layout"

From Gcube Wiki
Jump to: navigation, search
(descriptor.xml)
 
(26 intermediate revisions by the same user not shown)
Line 1: Line 1:
'''Important''': The guidelines provided in this page have been adopted starting from gCube 3.10.1 (March 2015).
+
'''Important''': The guidelines provided in this page have been adopted starting from gCube 3.10.1 (March 2016).
  
= distro directory =
+
The ''distro'' directory of gCube Maven components contains a set of files and templates used to generate files that will be included in the distribution packages of the component.
  
This directory contains a set of files and templates of files that will be included in the distribution packages of the component. This process is done through the Maven [http://maven.apache.org/plugins/maven-assembly-plugin/ Assembly plugin] (controlled by the [[#descriptor.xml|descriptor.xml]] file) located in this folder.
+
The following sections describes the mandatory and optional files expected to be in this directory. However, ''distro'' directory can also contains other component-specific files required to be distributed in the component packages.
  
The following sections describes the common files that ALL components must provide. This directory can also contains other component-specific files required to be distributed in the component packages.
+
The layout, the files and the filtering mechanism presented in this section work only for Maven components. They will not work with the '''Ant''' components. However, since <u>also Ant components must provide the mandatory files</u> and since Ant does not provide any support for filtering of files, developers must take care of keep the files updated manually.
  
 
+
= Mandatory Files =
'''Important note''': The layout, the files and the filtering mechanism presented in this section work only for Maven components. They will not work with the '''Ant''' components. <u>Also Ant components must provide such files</u>, but, since Ant does not provide any support for filtering of files, developers must take care of keep the files updated manually.
+
The following sections describe the files that must be provided by ALL components.
  
 
== README ==
 
== README ==
Each gCube component must include a README file that must be included in distribution packages of the component. The file briefly describe the component and the gCube system and provide references to the source code, binaries, documentation as well as to the INSTALL and LICENSE file.
+
Each gCube component must include a README file that must be included in distribution packages of the component. The file briefly describe the component and the gCube system and provide references to the source code, binaries, documentation, authors and maintainers and to the software license.
  
  
Line 17: Line 17:
  
  
By convention, the README file should be located under the <code>distro/</code> folder (together with the other metadata files: LICENSE, MAINTAINERS, INSTALL, ...). It should follow this template (only minor changes to fits the component needs are allowed):
+
By convention, the README file should be located under the <code>distro/</code> folder. It should follow this template (only minor changes to fits the component needs are allowed):
  
<source lang="text" highlight="23,24,43,44,45">
+
<source lang="text" highlight="23,24,30,31,48,55,56">
 
The gCube System - ${name}
 
The gCube System - ${name}
 
--------------------------------------------------
 
--------------------------------------------------
Line 39: Line 39:
  
  
Authors and Maintainers
+
Authors
 
--------------------------------------------------
 
--------------------------------------------------
 
   
 
   
Line 45: Line 45:
 
* Second Author(email-AT-example.org), Organization, Country
 
* Second Author(email-AT-example.org), Organization, Country
  
Please see the file named "MAINTAINERS" in this directory for the current maintainers of this software.
+
 
 +
Maintainers
 +
-----------
 +
 +
* John Doe (john.doe-AT-acme.org), ACME Inc.
 +
* Second Maintainer(email-AT-example.org), Organization, Country
  
 
   
 
   
Line 56: Line 61:
 
Binaries can be downloaded from the gCube website:  
 
Binaries can be downloaded from the gCube website:  
 
   ${gcube.website}
 
   ${gcube.website}
 +
 +
 +
Installation
 +
--------------------------------------------------
 
   
 
   
+
Installation documentation is available on-line in the gCube Wiki:
 +
    ${gcube.wikiRoot}/[admin guide page name here]
 +
 
 +
 
 
Documentation  
 
Documentation  
 
--------------------------------------------------
 
--------------------------------------------------
 
   
 
   
Documentation is available on-line in the gCube Documentation Wiki:
+
Documentation is available on-line in the gCube Wiki:
     Developer Guide - ${gcube.wikiRoot}/[page name here]
+
     ${gcube.wikiRoot}/[user guide page name here]
     User Guide - ${gcube.wikiRoot}/[page name here]
+
     ${gcube.wikiRoot}/[developer guide page name here]
    Admin Guide - ${gcube.wikiRoot}/[page name here]
+
 
  
 
 
Support  
 
Support  
 
--------------------------------------------------
 
--------------------------------------------------
Line 74: Line 85:
  
  
Installation
 
--------------------------------------------------
 
 
Please see the file named "INSTALL" in this directory.
 
 
 
 
Licensing
 
Licensing
 
--------------------------------------------------
 
--------------------------------------------------
 
   
 
   
 
This software is licensed under the terms you may find in the file named "LICENSE" in this directory.
 
This software is licensed under the terms you may find in the file named "LICENSE" in this directory.
 
  
 
</source>
 
</source>
  
  
The <span style="background-color: #ffc">highlighted lines</span> in the template should be replaced with appropriate data for the component before commit it in SVN. It is very static information and use dynamic property values for that does not have any advantage (and, in case of authors, technically difficult). In any case developers are free to define properties in their <code>pom.xml</code> and use them in the README.
+
Only the <span style="background-color: #ffc">highlighted lines</span> in the template must be customized and replaced with appropriate data for the component before commit it in SVN. In any case developers are free to define additional properties in their <code>pom.xml</code> and use them in the README.
  
 
'''Important note''': the <code>@...@</code> sequence is used by Maven as delimiter for properties (alternative to <code>${...}</code>), therefore it is recommended to avoid to use the <code>@</code> character otherwise Maven will not be able to correctly parse the file. It is suggested to replace <code>@</code> with <code>-AT-</code> in the e-mail addresses.
 
'''Important note''': the <code>@...@</code> sequence is used by Maven as delimiter for properties (alternative to <code>${...}</code>), therefore it is recommended to avoid to use the <code>@</code> character otherwise Maven will not be able to correctly parse the file. It is suggested to replace <code>@</code> with <code>-AT-</code> in the e-mail addresses.
Line 155: Line 159:
  
 
Currently the license under which gCube is distributed is the EUPL v1.1 and the <code>${gcube.license}</code> is replaced with [https://joinup.ec.europa.eu/sites/default/files/ckeditor_files/files/eupl%20v%20%201%201%20-%20EN.txt.txt this text].
 
Currently the license under which gCube is distributed is the EUPL v1.1 and the <code>${gcube.license}</code> is replaced with [https://joinup.ec.europa.eu/sites/default/files/ckeditor_files/files/eupl%20v%20%201%201%20-%20EN.txt.txt this text].
 
 
== MAINTAINERS ==
 
The MAINTAINERS file (referenced by the README) should provide name and contacts of the '''current''' maintainers of the component.
 
<source lang="text">
 
Maintainers
 
-----------
 
 
* John Doe (john.doe@acme.org), ACME Inc.
 
* Second Author(email@example.org), Organization, Country
 
 
 
</source>
 
 
This file can also report the ''history'' of Maintainers, but it must be clear who are the current maintainers.
 
 
== INSTALL ==
 
This file should briefly provide instructions to install the component.
 
  
  
Line 179: Line 165:
 
This file (referenced by the README) contains the list of all changes, fixes and new features for each release of the component.An example of changelog.xml file is:
 
This file (referenced by the README) contains the list of all changes, fixes and new features for each release of the component.An example of changelog.xml file is:
  
<source lang="xml">
+
<source lang="text">
 
<ReleaseNotes>
 
<ReleaseNotes>
 
<Changeset component="org.gcube.messaging.consumer.1-2-0" date="2010-07-16">
 
<Changeset component="org.gcube.messaging.consumer.1-2-0" date="2010-07-16">
Line 195: Line 181:
  
 
Further information can be found in the [[Changelog Generation procedure]] page.
 
Further information can be found in the [[Changelog Generation procedure]] page.
 +
 +
 +
== profile.xml ==
 +
This is a gCube-specific file used by gCube SoftwareGateway and Deployer services to correctly register the software in the infrastructure and deploy it on gCube nodes. It specifies the gCube coordinates (Class, Name and Version) and references to the packages of the component. Before the adoption of Maven, it was used also to specify dependencies of the software.
 +
 +
Since the adoption of Maven, the profile.xml became much simple thanks to the use of Maven properties and resource filtering. More information on how to properly write a profile.xml is reported in these section: [[Developing_gCube_Maven_Components#Profile_2|general profiles]], for
 +
[[Developing_gCube_Maven_Components#Profile_3|portlets]] and for [[Developing_gCube_Maven_Components#Profile_4|widgets]].
  
  
 
== descriptor.xml ==
 
== descriptor.xml ==
 +
 +
'''ATTENTION: Sine November 2017, it is possible to use a default descriptor in common to all gCube components. If used, the component does not need to include this file any-more. Please read more on this [[Developing_gCube_Maven_Components#Service_Archive_.28SA.29|here]].'''
 +
 
This file is used by the Maven [http://maven.apache.org/plugins/maven-assembly-plugin/ Assembly plugin] to build the '''servicearchive.tar.gz'' artifact. This package contains the binary files of the component plus all the files described in this page.  
 
This file is used by the Maven [http://maven.apache.org/plugins/maven-assembly-plugin/ Assembly plugin] to build the '''servicearchive.tar.gz'' artifact. This package contains the binary files of the component plus all the files described in this page.  
  
Line 220: Line 216:
 
<include>README</include>
 
<include>README</include>
 
<include>LICENSE</include>
 
<include>LICENSE</include>
<include>INSTALL</include>
 
<include>MAINTAINERS</include>
 
 
<include>changelog.xml</include>
 
<include>changelog.xml</include>
 +
                                <include>profile.xml</include>
 
</includes>
 
</includes>
 
<fileMode>755</fileMode>
 
<fileMode>755</fileMode>
Line 230: Line 225:
 
<files>
 
<files>
 
<file>
 
<file>
<source>target/${build.finalName}.war</source>
+
<source>target/${build.finalName}.${project.packaging}</source>
 
<outputDirectory>/${artifactId}</outputDirectory>
 
<outputDirectory>/${artifactId}</outputDirectory>
 
</file>
 
</file>
 +
 
</files>
 
</files>
 
</assembly>
 
</assembly>
 
</pre>
 
</pre>
 +
  
 
Plase note that the Assembly plugin must be explicitly activated in the component pom.xml:
 
Plase note that the Assembly plugin must be explicitly activated in the component pom.xml:
Line 242: Line 239:
 
<groupId>org.apache.maven.plugins</groupId>
 
<groupId>org.apache.maven.plugins</groupId>
 
<artifactId>maven-assembly-plugin</artifactId>
 
<artifactId>maven-assembly-plugin</artifactId>
<version>2.2</version>
 
 
<configuration>
 
<configuration>
 
<descriptors>
 
<descriptors>
Line 259: Line 255:
 
</plugin>
 
</plugin>
 
</pre>
 
</pre>
 +
 +
= Deprecated files =
 +
The following sections describe the files that were used in the past but that are now deprecated because the information contained is available elsewhere. In order to allow a smoother transition, all the release and distribution scripts continue to support these files (otherwise explicitly mentioned).
 +
 +
== MAINTAINERS ==
 +
The README template also include a section for maintainers. It is recommended to include names and contacts of maintainers directly in the README and to remove the MAINTAINERS file.
 +
 +
== INSTALL ==
 +
This file should briefly provide instructions to install the component, however in most cases this information is available in the gCube wiki (Admin Guide). To avoid replication of information, it is recommended to remove this file completely and to specify in the README (Installation section) the link to the on-line documentation.
 +
 +
== svnpath.txt ==
 +
This file was used to keep track of the path of the source code in the SVN. However this information is available in the ${scm.url} Maven property. Maven components can remove this file.

Latest revision as of 13:09, 30 October 2017

Important: The guidelines provided in this page have been adopted starting from gCube 3.10.1 (March 2016).

The distro directory of gCube Maven components contains a set of files and templates used to generate files that will be included in the distribution packages of the component.

The following sections describes the mandatory and optional files expected to be in this directory. However, distro directory can also contains other component-specific files required to be distributed in the component packages.

The layout, the files and the filtering mechanism presented in this section work only for Maven components. They will not work with the Ant components. However, since also Ant components must provide the mandatory files and since Ant does not provide any support for filtering of files, developers must take care of keep the files updated manually.

Mandatory Files

The following sections describe the files that must be provided by ALL components.

README

Each gCube component must include a README file that must be included in distribution packages of the component. The file briefly describe the component and the gCube system and provide references to the source code, binaries, documentation, authors and maintainers and to the software license.


In order to have as much as possible uniform README files across components and to reduce the effort to maintain the file updated, a standardized template is provided. The template makes use of placeholders (delimited by ${...}) that are replaced at build-time with the value of Maven properties. This approach allows to keep the same README in the source code while distributing files containing always updated information.


By convention, the README file should be located under the distro/ folder. It should follow this template (only minor changes to fits the component needs are allowed):

The gCube System - ${name}
--------------------------------------------------
 
${description}
 
 
${gcube.description}
 
${gcube.funding}
 
 
Version
--------------------------------------------------
 
${version} (${buildDate})
 
Please see the file named "changelog.xml" in this directory for the release notes.
 
 
Authors
--------------------------------------------------
 
* John Doe (john.doe-AT-acme.org), ACME Inc.* Second Author(email-AT-example.org), Organization, Country 
 
Maintainers
-----------
 
* John Doe (john.doe-AT-acme.org), ACME Inc.* Second Maintainer(email-AT-example.org), Organization, Country 
 
Download information
--------------------------------------------------
 
Source code is available from SVN: 
    ${scm.url}
 
Binaries can be downloaded from the gCube website: 
   ${gcube.website}
 
 
Installation
--------------------------------------------------
 
Installation documentation is available on-line in the gCube Wiki:
    ${gcube.wikiRoot}/[admin guide page name here]  
 
Documentation 
--------------------------------------------------
 
Documentation is available on-line in the gCube Wiki:
    ${gcube.wikiRoot}/[user guide page name here]    ${gcube.wikiRoot}/[developer guide page name here] 
 
Support 
--------------------------------------------------
 
Bugs and support requests can be reported in the gCube issue tracking tool:
    ${gcube.issueTracking}
 
 
Licensing
--------------------------------------------------
 
This software is licensed under the terms you may find in the file named "LICENSE" in this directory.


Only the highlighted lines in the template must be customized and replaced with appropriate data for the component before commit it in SVN. In any case developers are free to define additional properties in their pom.xml and use them in the README.

Important note: the @...@ sequence is used by Maven as delimiter for properties (alternative to ${...}), therefore it is recommended to avoid to use the @ character otherwise Maven will not be able to correctly parse the file. It is suggested to replace @ with -AT- in the e-mail addresses.


All the placeholders delimited by ${...} must correspond to Maven properties. There are two source of properties:

  • the component pom.xml. It is possible to access custom-defined properties in the section <properties> of the pom as well as default properties defined by Maven (e.g. ${version}, ${name});
  • the gCube maven-parent (available here);

The properties are replaced during the build by the filtering mechanism used by the plugins that create the distribution packages (i.e. the assembly plugin).

These are the properties used in the README template provided above:

property definition description
${name} pom.xml The value of <name> tag in the pom
${description} pom.xml The value of <description> tag in the pom
${gcube.description} maven-parent A brief description of gCube framework
${gcube.funding} maven-parent The declaration of EU projects that funded the gCube development
${version} pom.xml The value of <version> tag in the pom
${buildDate} maven-parent The date of the component build. It is in the YYYY-MM-dd format (format defined in maven-parent)
${scm.url} pom.xml The location of component source code in SVN. It must be defined in the pom in <scm><url>[location]</url></scm>
${gcube.website} maven-parent The website of gCube system: http://gcube-system.org/
${gcube.wikiRoot} maven-parent The home page of the gCube wiki: https://wiki.gcube-system.org/gcube/index.php/
${gcube.issueTracking} maven-parent The home page of the gCube Issue Tracker: https://support.d4science.org/projects/gcube/

LICENSE

This file (referenced by the README file) contains the text of the license under which the software is distributed. In order to avoid massive update of this file in all components if in the future, the gCube license will change, the entire text of this file is provided by a Maven property defined in the maven-parent: ${gcube.license}

${gcube.license}


Currently the license under which gCube is distributed is the EUPL v1.1 and the ${gcube.license} is replaced with this text.


changelog.xml

This file (referenced by the README) contains the list of all changes, fixes and new features for each release of the component.An example of changelog.xml file is:

<ReleaseNotes>
<Changeset component="org.gcube.messaging.consumer.1-2-0" date="2010-07-16">
  <Change>Extended the Monitoring Generic Resource with the possibility to specify site managers for each site domain</Change>
  <Change>Notification are now filtered over domain</Change>
  <Change>Added daily notification summary</Change>
</Changeset>
<Changeset component="org.gcube.messaging.consumer-library.1-1-2" date="2010-07-16">
  <Change>Added queries for NodeAccounting portlet</Change>
</Changeset>
</ReleaseNotes>

This file contribute to the generation of the full gCube release changelog. In order to correctly generate the final changelog, the value of component tag must match exactly the name of the ETICS Configuration, therefore it is wrong to put here ${name} (unless the name of the component matches the name of the ETIC configuration.

Further information can be found in the Changelog Generation procedure page.


profile.xml

This is a gCube-specific file used by gCube SoftwareGateway and Deployer services to correctly register the software in the infrastructure and deploy it on gCube nodes. It specifies the gCube coordinates (Class, Name and Version) and references to the packages of the component. Before the adoption of Maven, it was used also to specify dependencies of the software.

Since the adoption of Maven, the profile.xml became much simple thanks to the use of Maven properties and resource filtering. More information on how to properly write a profile.xml is reported in these section: general profiles, for portlets and for widgets.


descriptor.xml

ATTENTION: Sine November 2017, it is possible to use a default descriptor in common to all gCube components. If used, the component does not need to include this file any-more. Please read more on this here.

This file is used by the Maven Assembly plugin to build the 'servicearchive.tar.gz artifact. This package contains the binary files of the component plus all the files described in this page.

This is a generic descriptor.xml file (it may be customized to include other files needed to be distributed for the component):

<assembly
	xmlns="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.0"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.0 http://maven.apache.org/xsd/assembly-1.1.0.xsd">
	<id>servicearchive</id>
	<formats>
		<format>tar.gz</format>
	</formats>
	<baseDirectory>/</baseDirectory>
	<fileSets>
		<fileSet>
			<directory>${distroDirectory}</directory>
			<outputDirectory>/</outputDirectory>
			<useDefaultExcludes>true</useDefaultExcludes>
			<includes>
				<include>README</include>
				<include>LICENSE</include>
				<include>changelog.xml</include>
                                <include>profile.xml</include>
			</includes>
			<fileMode>755</fileMode>
			<filtered>true</filtered>
		</fileSet>
	</fileSets>
	<files>
		<file>
			<source>target/${build.finalName}.${project.packaging}</source>
			<outputDirectory>/${artifactId}</outputDirectory>
		</file>

	</files>
</assembly>


Plase note that the Assembly plugin must be explicitly activated in the component pom.xml:

<plugin>
	<groupId>org.apache.maven.plugins</groupId>
	<artifactId>maven-assembly-plugin</artifactId>
	<configuration>
		<descriptors>
			<descriptor>${distroDirectory}/descriptor.xml</descriptor>
		</descriptors>
	</configuration>
	<executions>
		<execution>
			<id>servicearchive</id>
			<phase>install</phase>
			<goals>
				<goal>single</goal>
			</goals>
		</execution>
	</executions>
</plugin>

Deprecated files

The following sections describe the files that were used in the past but that are now deprecated because the information contained is available elsewhere. In order to allow a smoother transition, all the release and distribution scripts continue to support these files (otherwise explicitly mentioned).

MAINTAINERS

The README template also include a section for maintainers. It is recommended to include names and contacts of maintainers directly in the README and to remove the MAINTAINERS file.

INSTALL

This file should briefly provide instructions to install the component, however in most cases this information is available in the gCube wiki (Admin Guide). To avoid replication of information, it is recommended to remove this file completely and to specify in the README (Installation section) the link to the on-line documentation.

svnpath.txt

This file was used to keep track of the path of the source code in the SVN. However this information is available in the ${scm.url} Maven property. Maven components can remove this file.