Difference between revisions of "GCube Project Layout"

From Gcube Wiki
Jump to: navigation, search
(Project Layout Explained)
(POM Properties referring the Layout)
 
(16 intermediate revisions by the same user not shown)
Line 1: Line 1:
  
 
= Standard Project Layout =
 
= Standard Project Layout =
gCube projects for new software components are primarily developed with the Java language using Maven as build automation tool. The layout of a project mostly reflects the common conventions used for Maven with some variations.
+
gCube projects for software components are primarily developed with the Java language using Maven as build automation tool. The layout of a project mostly reflects the common conventions used for Maven with some variations.
  
 
<pre>
 
<pre>
Line 18: Line 18:
 
         |-WEB-INF/
 
         |-WEB-INF/
 
         |-META-INF/   
 
         |-META-INF/   
 +
  |-CHANGELOG.md
 +
  |-LICENSE.md
 +
  |-README.md
 +
  |-FUNDING.md
 +
</pre>
 +
 +
= Multi-Module Project Layout =
 +
Maven supports project aggregation where multiple software components can be built by independent units called ''modules''.
 +
In a multi-module project layout, the root project folder contains the parent pom.xml and the *.md files, while each module's folder contains its own instance of the standard layout (see previous section). The layout is repeated because the module is an independently distributed unit of software.
 +
<pre>
 +
- project folder/
 +
  |-pom.xml
 +
  |-ModuleA/
 +
    |-src/ 
 +
        |-...
 +
    |-gcube/
 +
        |-... 
 +
    |-CHANGELOG.md
 +
    |-LICENSE.md
 +
    |-README.md
 +
    |-FUNDING.md
 +
  |-ModuleB/
 +
    |-src/ 
 +
        |-...
 +
    |-gcube/
 +
        |-... 
 +
    |-CHANGELOG.md
 +
    |-LICENSE.md
 +
    |-README.md
 +
    |-FUNDING.md
 +
    |-CHANGELOG.md
 +
  |-ModuleC/
 +
    |-src/ 
 +
        |-...
 +
    |-gcube/
 +
        |-... 
 +
    |-CHANGELOG.md
 +
    |-LICENSE.md
 +
    |-README.md
 +
    |-FUNDING.md
 +
    |-CHANGELOG.md
 +
 
 
   |-CHANGELOG.md
 
   |-CHANGELOG.md
 
   |-LICENSE.md
 
   |-LICENSE.md
Line 31: Line 73:
 
|-
 
|-
 
| pom.xml
 
| pom.xml
| an XML file that contains information about the project and configuration details used by Maven to build the project.
+
| an XML file that contains information about the project and configuration details used by Maven to build the project
 
|-
 
|-
 
| src/main/java/
 
| src/main/java/
Line 49: Line 91:
 
|-
 
|-
 
| gcube/extra-resources/WEB-INF/
 
| gcube/extra-resources/WEB-INF/
| extra resources to add to the WEB-INF dir of the output jar/war. These resources are filtered
+
| additional resources to add to the WEB-INF dir in the output jar/war. These resources are filtered(*)
 
|-
 
|-
 
| gcube/extra-resources/META-INF/
 
| gcube/extra-resources/META-INF/
| extra resources to add to the META-INF dir of the output jar/war. These resources are filtered
+
| additional resources to add to the META-INF dir in the output jar/war. These resources are filtered(*)
 
|-
 
|-
 
| CHANGELOG.md
 
| CHANGELOG.md
| a curated, chronologically ordered list of notable changes for each version of a project
+
| a curated, chronologically ordered list of notable changes for each version of the project
 
|-
 
|-
 
| LICENSE.md
 
| LICENSE.md
Line 67: Line 109:
 
|}
 
|}
  
'''Note''': if the project is composed by multiple maven modules, the layout above is repeated for each module, because the module is an independent distributed unit of software.
+
(*) For an explanation of filtering see https://maven.apache.org/plugins/maven-resources-plugin/examples/filter.html.
  
 
= File Templates =
 
= File Templates =
  
* [https://code-repo.d4science.org/gCubeCI/Templates/src/branch/master/gCubeComponents/CHANGELOG.md| CHANGELOG.md]
+
* [https://code-repo.d4science.org/gCubeCI/Templates/src/branch/master/gCubeComponents/CHANGELOG.md CHANGELOG.md]
 +
* [https://code-repo.d4science.org/gCubeCI/Templates/src/branch/master/gCubeComponents/LICENSE.md LICENSE.md]
 +
* [https://code-repo.d4science.org/gCubeCI/Templates/src/branch/master/gCubeComponents/README.md README.md]
 +
* [https://code-repo.d4science.org/gCubeCI/Templates/src/branch/master/gCubeComponents/FUNDING.md FUNDING.md]
 +
 
 +
= File MANIFEST.MF =
 +
A manifest file is automatically created and added to the META-INF folder of the output jar/war.
 +
 
 +
This example shows an instance of the content for the manifest:
 +
<pre>
 +
Manifest-Version: 1.0
 +
SCM-Revision-URL: https://code-repo.d4science.org/gCubeSystem/gx-rest/commit/8948534883a3b0998bb4487f12965122d22863af
 +
Implementation-Title: gCube eXtensions to JAX-RS
 +
Implementation-Version: 1.1.3
 +
SCM-Revision: 8948534883a3b0998bb4487f12965122d22863af
 +
Specification-Title: gCube eXtensions to JAX-RS
 +
Build-Time: 20200725-203436
 +
Build-Jdk-Spec: 1.8
 +
Created-By: Maven Archiver 3.4.0
 +
Specification-Version: 1.1
 +
SCM-Branch: master
 +
</pre>
 +
 
 +
= POM Properties referring the Layout =
 +
From the project's POM it is possible to refer the structure of the layout via the standard Maven Properties:
 +
 
 +
https://cwiki.apache.org/confluence/display/MAVEN/Maven+Properties+Guide
 +
 
 +
In addition, the following POM properties are available to components inheriting from the ''maven-parent'':
 +
* <code>${project.webinf.outputDirectory}</code>
 +
** This represents the WEB-INF folder in the output JAR/WAR.
 +
* <code>${project.metainf.outputDirectory}</code>
 +
**This represents the META-INF folder in the output JAR/WAR.
 +
* <code>${project.test.outputDirectory}</code>
 +
**This represents the folder where the JUnit reports are stored.

Latest revision as of 18:57, 11 August 2020

Standard Project Layout

gCube projects for software components are primarily developed with the Java language using Maven as build automation tool. The layout of a project mostly reflects the common conventions used for Maven with some variations.

- project folder/
  |-pom.xml
  |-src/
     |-main/
        |-java/
        |-webapp/
        |-resources/
     |-test/
        |-java/
        |-resources/
  |-gcube/
     |-extra-resources
        |-WEB-INF/
        |-META-INF/  
  |-CHANGELOG.md
  |-LICENSE.md
  |-README.md
  |-FUNDING.md

Multi-Module Project Layout

Maven supports project aggregation where multiple software components can be built by independent units called modules. In a multi-module project layout, the root project folder contains the parent pom.xml and the *.md files, while each module's folder contains its own instance of the standard layout (see previous section). The layout is repeated because the module is an independently distributed unit of software.

- project folder/
  |-pom.xml
  |-ModuleA/
     |-src/  
        |-...
     |-gcube/
        |-...  
     |-CHANGELOG.md
     |-LICENSE.md
     |-README.md
     |-FUNDING.md 
  |-ModuleB/
     |-src/  
        |-...
     |-gcube/
        |-...  
     |-CHANGELOG.md
     |-LICENSE.md
     |-README.md
     |-FUNDING.md 
     |-CHANGELOG.md
   |-ModuleC/
     |-src/  
        |-...
     |-gcube/
        |-...  
     |-CHANGELOG.md
     |-LICENSE.md
     |-README.md
     |-FUNDING.md 
     |-CHANGELOG.md
  
  |-CHANGELOG.md
  |-LICENSE.md
  |-README.md
  |-FUNDING.md

Project Layout Explained

File or Directory Role
pom.xml an XML file that contains information about the project and configuration details used by Maven to build the project
src/main/java/ application source code
src/main/webapp/ web application source code
src/main/resources/ resources packaged at root level in the output jar/war
src/test/java/ source code for tests
src/test/resources/ resources available on the test classpath
gcube/extra-resources/WEB-INF/ additional resources to add to the WEB-INF dir in the output jar/war. These resources are filtered(*)
gcube/extra-resources/META-INF/ additional resources to add to the META-INF dir in the output jar/war. These resources are filtered(*)
CHANGELOG.md a curated, chronologically ordered list of notable changes for each version of the project
LICENSE.md project's license
README.md a quick and simple way for other users to learn more about the project and how to use it
FUNDING.md sponsors and funding options for the project

(*) For an explanation of filtering see https://maven.apache.org/plugins/maven-resources-plugin/examples/filter.html.

File Templates

File MANIFEST.MF

A manifest file is automatically created and added to the META-INF folder of the output jar/war.

This example shows an instance of the content for the manifest:

Manifest-Version: 1.0
SCM-Revision-URL: https://code-repo.d4science.org/gCubeSystem/gx-rest/commit/8948534883a3b0998bb4487f12965122d22863af
Implementation-Title: gCube eXtensions to JAX-RS
Implementation-Version: 1.1.3
SCM-Revision: 8948534883a3b0998bb4487f12965122d22863af
Specification-Title: gCube eXtensions to JAX-RS
Build-Time: 20200725-203436
Build-Jdk-Spec: 1.8
Created-By: Maven Archiver 3.4.0
Specification-Version: 1.1
SCM-Branch: master

POM Properties referring the Layout

From the project's POM it is possible to refer the structure of the layout via the standard Maven Properties:

https://cwiki.apache.org/confluence/display/MAVEN/Maven+Properties+Guide

In addition, the following POM properties are available to components inheriting from the maven-parent:

  • ${project.webinf.outputDirectory}
    • This represents the WEB-INF folder in the output JAR/WAR.
  • ${project.metainf.outputDirectory}
    • This represents the META-INF folder in the output JAR/WAR.
  • ${project.test.outputDirectory}
    • This represents the folder where the JUnit reports are stored.