You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@jackrabbit.apache.org by tr...@apache.org on 2017/10/20 02:36:01 UTC
svn commit: r1812697 - in
/jackrabbit/commons/filevault-package-maven-plugin/trunk/plugin/src/site:
markdown/dev.md markdown/import_package.md site.xml
Author: tripod
Date: Fri Oct 20 02:36:01 2017
New Revision: 1812697
URL: http://svn.apache.org/viewvc?rev=1812697&view=rev
Log:
@trivial: add docu of import-package handling
Added:
jackrabbit/commons/filevault-package-maven-plugin/trunk/plugin/src/site/markdown/import_package.md
Modified:
jackrabbit/commons/filevault-package-maven-plugin/trunk/plugin/src/site/markdown/dev.md
jackrabbit/commons/filevault-package-maven-plugin/trunk/plugin/src/site/site.xml
Modified: jackrabbit/commons/filevault-package-maven-plugin/trunk/plugin/src/site/markdown/dev.md
URL: http://svn.apache.org/viewvc/jackrabbit/commons/filevault-package-maven-plugin/trunk/plugin/src/site/markdown/dev.md?rev=1812697&r1=1812696&r2=1812697&view=diff
==============================================================================
--- jackrabbit/commons/filevault-package-maven-plugin/trunk/plugin/src/site/markdown/dev.md (original)
+++ jackrabbit/commons/filevault-package-maven-plugin/trunk/plugin/src/site/markdown/dev.md Fri Oct 20 02:36:01 2017
@@ -19,7 +19,7 @@ Developing
Latest development
------------------
-The latest FileVault source code is available via Subversion at
+The latest FileVault Package Maven Plugin source code is available via Subversion at
* https://svn.apache.org/repos/asf/jackrabbit/commons/filevault-package-maven-plugin/trunk
@@ -41,9 +41,9 @@ or
git clone https://github.com/apache/jackrabbit-filevault-package-maven-plugin.git
-Building FileVault
+Building FileVault Package Maven Plugin
------------------
-You can build FileVault using maven:
+You can build FileVault Package Maven Plugin using maven:
cd filevault-package-maven-plugin
mvn clean install
Added: jackrabbit/commons/filevault-package-maven-plugin/trunk/plugin/src/site/markdown/import_package.md
URL: http://svn.apache.org/viewvc/jackrabbit/commons/filevault-package-maven-plugin/trunk/plugin/src/site/markdown/import_package.md?rev=1812697&view=auto
==============================================================================
--- jackrabbit/commons/filevault-package-maven-plugin/trunk/plugin/src/site/markdown/import_package.md (added)
+++ jackrabbit/commons/filevault-package-maven-plugin/trunk/plugin/src/site/markdown/import_package.md Fri Oct 20 02:36:01 2017
@@ -0,0 +1,112 @@
+Generating import-package MANIFEST entries
+==========================================
+
+The Filevault content package maven plugin can analyze the classpath of the compiled classes, derived from the content and create an `import-package` MANIFEST entry. Although this is rather something to be expected in the OSGi world, declaring the java packages that the content potentially needs can help detecting deployment errors early.
+
+How it works
+------------
+_(todo: add more detailed explanation)_
+
+The generation of the `import-package` entry is performed in 3 steps:
+
+#### 1. generate classes
+1. JSP or HTL plugin transpile the scripts
+2. Maven compiler plugin compiles the generated java sources
+
+
+#### 2. analyze classes
+The classpath analysis is done in the `analyze-classes` goal:
+
+1. scan the java classes and extract the used java packages
+2. scan the dependencies and extract package version information from the MANIFEST if present
+3. cross reference the packages with the version information from the bundles
+4. write preliminary `import-package` entry to `${vault.generatedImportPackage}`
+
+
+#### 3. post-process and merge with project properties
+The final step is performed in the `package` goal:
+
+1. read `${vault.generatedImportPackage}`
+2. merge with instructions in `<importPackage>`
+3. add `import-package` entry to `META-INF/MANIFEST.MF`
+
+
+Working with JSPs
+-----------------
+(todo)
+
+Working with HTL
+----------------
+
+Where as the HTL use classes provided through bundles or via java classes in the content are simple to handle, the HTL scripts needs more treatment. similar to the JSPs, the HTL maven plugin can be used to transpile the scripts to java and then the maven compiler will create the classes.
+
+### Note on the analyzed packages
+The transpiled HTL scripts will contain some sightly compiler and runtime references, which are not true dependencies of the scripts. Nevertheless, they are needed to compile the scripts for the validation and will end up in the analyzed packages. by default, the following packages are excluded from the final `import-package`:
+
+```
+org.apache.sling.scripting.sightly.compiler.expression.nodes
+org.apache.sling.scripting.sightly.java.compiler
+org.apache.sling.scripting.sightly.render
+```
+
+_Note: The excludes are present in the default value of the `<importPackage>` property and are lost if it is definedin the project. In this cases they need to be added manually._
+
+### Example configuration for HTL
+
+_note: at the time of writing, the HTL plugin wasn't released yet. version 1.0.15-SNAPSHOT or higher will be required._
+
+```
+<build>
+ <sourceDirectory>src/content/jcr_root</sourceDirectory>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.jackrabbit</groupId>
+ <artifactId>filevault-package-maven-plugin</artifactId>
+ <version>1.0.0-SNAPSHOT</version>
+ <extensions>true</extensions>
+ <configuration>
+ <filterSource>${basedir}/src/content/META-INF/vault/filter.xml</filterSource>
+ </configuration>
+ </plugin>
+ <plugin>
+ <groupId>org.apache.sling</groupId>
+ <artifactId>htl-maven-plugin</artifactId>
+ <version>1.0.9-SNAPSHOT</version>
+ <executions>
+ <execution>
+ <id>validate-scripts</id>
+ <goals>
+ <goal>validate</goal>
+ </goals>
+ <phase>generate-sources</phase>
+ <configuration>
+ <sourceDirectory>src/content/jcr_root</sourceDirectory>
+ <includes>
+ <include>**/*.html</include>
+ </includes>
+ <failOnWarnings>true</failOnWarnings>
+ <generateJavaClasses>true</generateJavaClasses>
+ </configuration>
+ </execution>
+ </executions>
+ </plugin>
+ </plugins>
+</build>
+
+<dependencies>
+ <!-- needed for HTL compilation validation -->
+ <dependency>
+ <groupId>org.apache.sling</groupId>
+ <artifactId>org.apache.sling.scripting.sightly.compiler</artifactId>
+ <version>1.0.14</version>
+ <scope>provided</scope>
+ </dependency>
+ <dependency>
+ <groupId>org.apache.sling</groupId>
+ <artifactId>org.apache.sling.scripting.sightly.compiler.java</artifactId>
+ <version>1.0.15-SNAPSHOT</version>
+ <scope>provided</scope>
+ </dependency>
+</dependencies>
+```
+
Modified: jackrabbit/commons/filevault-package-maven-plugin/trunk/plugin/src/site/site.xml
URL: http://svn.apache.org/viewvc/jackrabbit/commons/filevault-package-maven-plugin/trunk/plugin/src/site/site.xml?rev=1812697&r1=1812696&r2=1812697&view=diff
==============================================================================
--- jackrabbit/commons/filevault-package-maven-plugin/trunk/plugin/src/site/site.xml (original)
+++ jackrabbit/commons/filevault-package-maven-plugin/trunk/plugin/src/site/site.xml Fri Oct 20 02:36:01 2017
@@ -25,8 +25,12 @@
<menu name="Overview">
<item name="Introduction" href="index.html"/>
<item name="Goals" href="plugin-info.html"/>
+ <item name="Import Package" href="import_package.html"/>
<item href="dev.html" name="Developing"/>
</menu>
+ <menu name="Documentation">
+ <item name="import-package generation" href="import_package.html"/>
+ </menu>
<menu name="Project Documentation">
<item href="project-summary.html" name="Project Summary"/>
<item href="license.html" name="Project License"/>