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 <[email protected]> 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 ```
