You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@sling.apache.org by da...@apache.org on 2020/11/23 13:35:12 UTC
[sling-feature-converter-maven-plugin] 02/37: Updated the docu to
reflect the latest changes
This is an automated email from the ASF dual-hosted git repository.
davidb pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/sling-feature-converter-maven-plugin.git
commit a4bfe9177165a5def62756b9c2572eb7c3018e9a
Author: Andreas Schaefer <sc...@iMac.local>
AuthorDate: Tue Aug 13 18:13:01 2019 -0700
Updated the docu to reflect the latest changes
---
README.md | 68 ++++++++++----------------------
src/site/markdown/usage.md.vm | 91 ++++++++++++++++++++++---------------------
2 files changed, 66 insertions(+), 93 deletions(-)
diff --git a/README.md b/README.md
index 8f46163..09cdd5b 100644
--- a/README.md
+++ b/README.md
@@ -2,64 +2,36 @@
[](https://builds.apache.org/job/Sling/job/sling-slingfeature-maven-plugin/job/master) [](https://builds.apache.org/job/Sling/job/sling-slingfeature-maven-plugin/job/master/test_results_analyzer/) [ project.
-Maven Plugin for Content Package to Feature Model Conversion:
+This plugin provides the means to convert both Content Packages as well as
+Provisioning Models into Feature Models through a POM file.
# Introduction
-This plugin is intended for a content package to also provide a Feature Model
-and its converted package / bundle. This plugin will only work on Content
-Package ZIP files artifacts.
-
+This plugin is intended to convert:
+* Content Packages
+* Provisioning Models
+into Feature Models so that it can be used by the Sling Feature Maven
+Plugin to assemble and run.
+
This plugin is a wrapper for the Sling Feature Content Package Converter
-**org.apache.sling.feature.cpconverter** over a content package the
-POM defines.
+**sling-org-apache-sling-feature-cpconverter** and the Sling Feature Model
+Converter **sling-org-apache-sling-feature-modelconveter** to convert
+source files into Feature Models inside a POM.
-The idea is to convert a Content Package at built time into a Feature
-Module so that it can be used both a regular Content Package in a
-traditional Sling Instance (Lauchpad) or in a Sling Instance in a Feature
-Model.
-The plugin will do the conversion and so a Content Package cna be used
-in a Feature Model w/o any changes in the Content Package.
+This plugin is normally used to convert Sling into its Feature Model
+version and to convert Content Packages into Feature Models so that they
+can be handled by the Sling Feature Maven Plugin and eventually launched.
## Supported goals
-This plugin has only one goal called **convert-cp** which takes a few
-parameters:
+These Goals are support in this plugin:
-* **strictValidation**:
- if set to true this will force the plugin to do a strict
- conversion. Checkout the Content Package 2 Feature
- Model Converter tool. Default: **false**
-* **mergeConfigurations**:
- if set to true if will merge configurations with
- the same PID. Not sure if that makes sense in
- this plugin. Default: **false**
-* **bundleStartOrder**:
- The bundle start order of the generated Feature
- Model. Default **20**
-* **artifactIdOverride**:
- An FM Artifact Id that overrides the one that
- is set by default. **Atttention**: to avoid the
- variable substitution for **${}** please add
- a zero-width whitespace (​) in between.
-* **featureModelsOutputDirectory**:
- Output folder of the Feature Model. Default
- **target/cp-conversion**
-* **convertedContentPackageOutputDirectory**:
- Output folder folder of the converted Content Package. Default
- **target**
-* **installConvertedContentPackage**:
- Install the Converted Content Package into the local Maven
- Repository so that it can be used by the Feature Model without
- a manual copy. Default: **true**
-* **systemProperties**:
- List of strings that represents System Properties like the Java
- **-D** option
+* **convert-cp**: Converts Content Packages into Feature Model files
+and its converted ZIP files
+* **convert-pom**: Converts Provisioning Models into Feature Models
-In order for the plugin to work the Content Package must be already
-created so this plugin must be started in a lifecycle phase after
-**package**.
+See the Site documentation for further info.
\ No newline at end of file
diff --git a/src/site/markdown/usage.md.vm b/src/site/markdown/usage.md.vm
index 9b3f34e..d520dcd 100644
--- a/src/site/markdown/usage.md.vm
+++ b/src/site/markdown/usage.md.vm
@@ -3,6 +3,8 @@
#set($h3 = '###')
#set($h4 = '####')
#set($sp = '${')
+#set($sp2 = '${{')
+#set($sp3 = '${{{')
#set($ep = '}')
@@ -88,25 +90,15 @@ and so the copy of the resources is not done automatically:
</executions>
</plugin>
```
-
-Now we setup this Plugin and set the features folder to **target/fm** (keep in mind this path has to
-be relative to the basedir and cannot be absolute):
+Then we need to setup the Sling Feature Converter Maven Plugin to convert Sling into its Feature Model
+equivalent so that we can launch it together with the converter CP packages later:
```
- <plugin>
+ <plugin>
<groupId>org.apache.sling</groupId>
- <artifactId>slingfeature-maven-plugin</artifactId>
- <version>1.0.5-SNAPSHOT</version>
+ <artifactId>sling-feature-converter-maven-plugin</artifactId>
+ <version>1.0.0-SNAPSHOT</version>
<extensions>true</extensions>
- <configuration>
- <features>target/fm</features>
- </configuration>
-```
-
-First we convert the Sling Provisioning Files to Feature Model files. For that the caller has to provide
-a property called **sling.starter.folder** with the absolute path to the Sling Starter Project:
-
-```
<executions>
<execution>
<id>convert-pm</id>
@@ -115,26 +107,19 @@ a property called **sling.starter.folder** with the absolute path to the Sling S
<goal>convert-pm</goal>
</goals>
<configuration>
- <!-- Absolute Path to the Sling Starter Project Provisioning Folder -->
- <inputFolder>${sp}sling.starter.folder${ep}/src/main/provisioning</inputFolder>
- <!-- Relative path (to basedir) to the output folder. It will be created if needed -->
+ <inputFolder>src/main/resources/sling/provisioning</inputFolder>
<outputFolder>target/fm</outputFolder>
- <!-- Instead of a fixed Feature Id we set placeholder here -->
- <groupId>${sp}{project.groupId}${ep}</groupId>
- <artifactId>${sp}{project.artifactId}${ep}</artifactId>
- <version>${sp}{project.version}${ep}</version>
- <!-- Add Framework Properties to the Launchpad FM to make JRE archives accessible -->
+ <groupId>${sp}{project.groupId}}</groupId>
+ <artifactId>${sp}{project.artifactId}}</artifactId>
+ <version>${sp}{project.version}}</version>
<frameworkProperties>
launchpad:felix.systempackages.substitution=true,
launchpad:felix.systempackages.calculate.uses=true
</frameworkProperties>
- <!-- Exclude certain bundles that conflict with the Launch of Feature Models -->
<excludeBundles>
org.apache.sling.launchpad.installer,
org.apache.sling.jcr.repoinit.impl.RepositoryInitializer
</excludeBundles>
- <!-- Only add run modes of type 'oak_tar' and 'standalone'. Feature Model Projects do
- not support runmodes anymore as each of them represents one particular set -->
<runModes>
oak_tar,
:standalone
@@ -143,7 +128,11 @@ a property called **sling.starter.folder** with the absolute path to the Sling S
</execution>
```
-Convert the Content Packages of this project and prefix the files names to avoid conflicts and make it easier to indentify them:
+In this scenario the Sling Provisioning Models are copied into the source folder.
+The **Launchpad Installer** and the **Repository Initializer** do not work together with Sling FM so
+they are excluded here. Then we select **oak_tar and :standalone** as the runmodes for this instance.
+
+Then we convert the Content Package:
```
<execution>
@@ -153,31 +142,44 @@ Convert the Content Packages of this project and prefix the files names to avoid
<goal>convert-cp</goal>
</goals>
<configuration>
- <!-- NOTE: ${{ / }} is a way to encode placeholders that should not be interpolated in Maven in this call
- and ${{{ / }}} is used to make it a CP Conversion Placeholder }-->
- <artifactIdOverride>${sp}{project.groupId}${ep}:${sp}{project.artifactId}${ep}:slingosgifeature:${sp}{{filename}}${ep}:${sp}{project.version}${ep}</artifactIdOverride>
- <!-- Install the Converted Content Package into the local Maven Repositorires. Without the launch
- will fail -->
+ <!-- NOTE: ${sp2} / }} is a way to encode placeholders that should not be interpolated in Maven in this call
+ and ${sp3} / }}} is used to make it a CP Conversion Placeholder -->
+ <artifactIdOverride>${sp2}project.groupId}}:${sp2}project.artifactId}}:slingosgifeature:${sp3}filename}}}:${sp2}project.version}}</artifactIdOverride>
<installConvertedCP>true</installConvertedCP>
- <!-- Set the output folder for the converted packages -->
- <convertedCPOutput>${sp}project.build.directory${ep}/fm.out</convertedCPOutput>
- <!-- Set the output folder for the converted Feature Model files -->
- <fmOutput>${sp}project.build.directory${ep}/fm</fmOutput>
- <!-- Prefix the files to easily identify them -->
- <fmPrefix>my-project-</fmPrefix>
+ <!-- Attention: because of the hack to deal with the overrides in the local Repo the generated files must be placed locally and not in the local Maven repo -->
+ <convertedCPOutput>${sp}project.build.directory}/fm.out</convertedCPOutput>
+ <fmOutput>${sp}project.build.directory}/fm</fmOutput>
+ <fmPrefix>test-ui-apps-</fmPrefix>
<contentPackages>
- <!-- each of these entries must have a dependency listed above -->
<contentPackage>
- <groupId>${sp}project.groupId${ep}</groupId>
- <artifactId>my-content-package</artifactId>
+ <groupId>org.apache.sling.test</groupId>
+ <artifactId>ui.apps</artifactId>
</contentPackage>
-...
</contentPackages>
</configuration>
</execution>
+ </executions>
+ </plugin>
+```
+
+Here we override the Feature Id to a more generic version, mark that we want to intall the converted files into
+our local Maven repo and that we prefix the converted FM file with **test-ui-apps-**.
+
+Now we setup this Plugin and set the features folder to **target/fm** (keep in mind this path has to
+be relative to the basedir and cannot be absolute):
+
+```
+ <plugin>
+ <groupId>org.apache.sling</groupId>
+ <artifactId>slingfeature-maven-plugin</artifactId>
+ <version>1.0.5-SNAPSHOT</version>
+ <extensions>true</extensions>
+ <configuration>
+ <features>target/fm</features>
+ </configuration>
```
-Now we aggregate, collect them into a single FM file (attach) and verify all the generated Feature Model files:
+Now we can aggregate, collect them into a single FM file (attach) and verify all the generated Feature Model files:
```
<execution>
@@ -270,6 +272,5 @@ The execution of a conversion and launch would look like this:
mvn \
clean \
install \
- -P launch \
- -Dsling.starter.folder=/sling.dev/sling-org-apache-sling-starter
+ -P launch
```