Google Git
Sign in
apache / sling-site / refs/heads/master / . / src / main / jbake / assets / components / sling-feature-converter-maven-plugin / usage.html
blob: 2a1e442242733a969b4b68813cf10b492e943098 [file] [log] [blame]
<!DOCTYPE html>
<!--
| Generated by Apache Maven Doxia Site Renderer 1.8.1 at 2020-01-16
| Rendered using Apache Maven Fluido Skin 1.6
-->
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta name="Date-Revision-yyyymmdd" content="20200116" />
<meta http-equiv="Content-Language" content="en" />
<title>Apache Sling Feature Model Converter Plugin &#x2013; Usage</title>
<link rel="stylesheet" href="./css/apache-maven-fluido-1.6.min.css" />
<link rel="stylesheet" href="./css/site.css" />
<link rel="stylesheet" href="./css/print.css" media="print" />
<script type="text/javascript" src="./js/apache-maven-fluido-1.6.min.js"></script>
</head>
<body class="topBarDisabled">
<div class="container-fluid">
<div id="banner">
<div class="pull-left"><div id="bannerLeft"><h2>Apache Sling Feature Model Converter Plugin</h2>
</div>
</div>
<div class="pull-right"></div>
<div class="clear"><hr/></div>
</div>
<div id="breadcrumbs">
<ul class="breadcrumb">
<li id="publishDate">Last Published: 2020-01-16<span class="divider">|</span>
</li>
<li id="projectVersion">Version: 1.0.4</li>
</ul>
</div>
<div class="row-fluid">
<div id="leftColumn" class="span2">
<div class="well sidebar-nav">
<ul class="nav nav-list">
<li class="nav-header">Overview</li>
<li><a href="index.html" title="Introduction"><span class="none"></span>Introduction</a> </li>
<li><a href="plugin-info.html" title="Goals"><span class="none"></span>Goals</a> </li>
<li class="active"><a href="#"><span class="none"></span>Usage</a>
</li>
<li class="nav-header">Project Documentation</li>
<li><a href="project-info.html" title="Project Information"><span class="icon-chevron-right"></span>Project Information</a> </li>
<li><a href="project-reports.html" title="Project Reports"><span class="icon-chevron-right"></span>Project Reports</a> </li>
</ul>
<hr />
<div id="poweredBy">
<div class="clear"></div>
<div class="clear"></div>
<div class="clear"></div>
<div class="clear"></div>
<a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy"><img class="builtBy" alt="Built by Maven" src="./images/logos/maven-feather.png" /></a>
</div>
</div>
</div>
<div id="bodyColumn" class="span10" >
<div class="section">
<h2><a name="Usage"></a>Usage</h2>
<div class="section">
<h3><a name="Converting_Sling.2C_Project_Content_Packages_and_Launch_it"></a>Converting Sling, Project Content Packages and Launch it</h3>
<p><b>Note</b>: In this sample we use Maven variables like <b>project.groupId</b> instead of a static value assuming that the project is within the same project that creates the content packages. Adjust that as needed. <b>Note</b>: Because we generate Feature Model files here the feature model files are in <b>target/fm</b>. We use <b>fm</b> instead of <b>features</b> to avoid confusion with the default feature source of <b>src/main/features</b>.</p>
<p>First we need to define the Content Packages that are converted</p>
<div>
<div>
<pre class="source">&lt;dependencies&gt;
...
&lt;dependency&gt;
&lt;groupId&gt;${project.groupId}&lt;/groupId&gt;
&lt;artifactId&gt;my-content-package&lt;/artifactId&gt;
&lt;version&gt;${project.version}&lt;/version&gt;
&lt;type&gt;zip&lt;/type&gt;
&lt;/dependency&gt;
</pre></div></div>
<p>Then we need to include the JCR Package Init to deploy the packages when the project is launched:</p>
<div>
<div>
<pre class="source"> &lt;dependency&gt;
&lt;groupId&gt;org.apache.sling&lt;/groupId&gt;
&lt;artifactId&gt;org.apache.sling.jcr.packageinit&lt;/artifactId&gt;
&lt;version&gt;0.0.1-SNAPSHOT&lt;/version&gt;
&lt;/dependency&gt;
...
&lt;/dependencies&gt;
</pre></div></div>
<p>Then we need to include the package init feature model file which must here is placed in the <b>src/main/resouces/fm</b> folder named <b>sling_packageinit.json</b>:</p>
<div>
<div>
<pre class="source">{
&quot;id&quot;:&quot;${project.groupId}:${project.artifactId}:slingfeature:sling_packageinit:${project.version}&quot;,
&quot;variables&quot;:{
},
&quot;bundles&quot;:[
{
&quot;id&quot;:&quot;org.apache.sling:org.apache.sling.jcr.packageinit:0.0.1-SNAPSHOT&quot;,
&quot;start-level&quot;:&quot;10&quot;
}
]
}
</pre></div></div>
<p>We need to cpy this file into our target folder because this is not a regular JAR build and so the copy of the resources is not done automatically:</p>
<div>
<div>
<pre class="source">&lt;build&gt;
...
&lt;plugins&gt;
&lt;plugin&gt;
&lt;groupId&gt;org.apache.maven.plugins&lt;/groupId&gt;
&lt;artifactId&gt;maven-resources-plugin&lt;/artifactId&gt;
&lt;version&gt;3.1.0&lt;/version&gt;
&lt;configuration&gt;
&lt;outputDirectory&gt;${project.build.directory}&lt;/outputDirectory&gt;
&lt;resources&gt;
&lt;resource&gt;
&lt;directory&gt;src/main/resources&lt;/directory&gt;
&lt;/resource&gt;
&lt;/resources&gt;
&lt;/configuration&gt;
&lt;executions&gt;
&lt;execution&gt;
&lt;id&gt;copy-frm-resource&lt;/id&gt;
&lt;phase&gt;process-resources&lt;/phase&gt;
&lt;goals&gt;
&lt;goal&gt;copy-resources&lt;/goal&gt;
&lt;/goals&gt;
&lt;/execution&gt;
&lt;/executions&gt;
&lt;/plugin&gt;
</pre></div></div>
<p>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:</p>
<div>
<div>
<pre class="source"> &lt;plugin&gt;
&lt;groupId&gt;org.apache.sling&lt;/groupId&gt;
&lt;artifactId&gt;sling-feature-converter-maven-plugin&lt;/artifactId&gt;
&lt;version&gt;1.0.4&lt;/version&gt;
&lt;extensions&gt;true&lt;/extensions&gt;
&lt;executions&gt;
&lt;execution&gt;
&lt;id&gt;convert-pm&lt;/id&gt;
&lt;phase&gt;process-classes&lt;/phase&gt;
&lt;goals&gt;
&lt;goal&gt;convert-pm&lt;/goal&gt;
&lt;/goals&gt;
&lt;configuration&gt;
&lt;inputFolder&gt;src/main/resources/sling/provisioning&lt;/inputFolder&gt;
&lt;outputFolder&gt;target/fm&lt;/outputFolder&gt;
&lt;groupId&gt;${{project.groupId}}&lt;/groupId&gt;
&lt;artifactId&gt;${{project.artifactId}}&lt;/artifactId&gt;
&lt;version&gt;${{project.version}}&lt;/version&gt;
&lt;frameworkProperties&gt;
launchpad:felix.systempackages.substitution=true,
launchpad:felix.systempackages.calculate.uses=true
&lt;/frameworkProperties&gt;
&lt;excludeBundles&gt;
org.apache.sling.launchpad.installer,
org.apache.sling.jcr.repoinit.impl.RepositoryInitializer
&lt;/excludeBundles&gt;
&lt;runModes&gt;
oak_tar,
:standalone
&lt;/runModes&gt;
&lt;/configuration&gt;
&lt;/execution&gt;
</pre></div></div>
<p>In this scenario the Sling Provisioning Models are copied into the source folder. The <b>Launchpad Installer</b> and the <b>Repository Initializer</b> do not work together with Sling FM so they are excluded here. Then we select <b>oak_tar and :standalone</b> as the runmodes for this instance.</p>
<p>Then we convert the Content Package:</p>
<div>
<div>
<pre class="source"> &lt;execution&gt;
&lt;id&gt;convert-cp&lt;/id&gt;
&lt;phase&gt;process-classes&lt;/phase&gt;
&lt;goals&gt;
&lt;goal&gt;convert-cp&lt;/goal&gt;
&lt;/goals&gt;
&lt;configuration&gt;
&lt;!-- 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 --&gt;
&lt;artifactIdOverride&gt;${{project.groupId}}:${{project.artifactId}}:slingosgifeature:${{{filename}}}:${{project.version}}&lt;/artifactIdOverride&gt;
&lt;installConvertedCP&gt;true&lt;/installConvertedCP&gt;
&lt;!-- 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 --&gt;
&lt;convertedCPOutput&gt;${project.build.directory}/fm.out&lt;/convertedCPOutput&gt;
&lt;fmOutput&gt;${project.build.directory}/fm&lt;/fmOutput&gt;
&lt;fmPrefix&gt;test-ui-apps-&lt;/fmPrefix&gt;
&lt;contentPackages&gt;
&lt;contentPackage&gt;
&lt;groupId&gt;org.apache.sling.test&lt;/groupId&gt;
&lt;artifactId&gt;ui.apps&lt;/artifactId&gt;
&lt;/contentPackage&gt;
&lt;/contentPackages&gt;
&lt;/configuration&gt;
&lt;/execution&gt;
&lt;/executions&gt;
&lt;/plugin&gt;
</pre></div></div>
<p>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 <b>test-ui-apps-</b>.</p>
<p>Now we setup this Plugin and set the features folder to <b>target/fm</b> (keep in mind this path has to be relative to the basedir and cannot be absolute):</p>
<div>
<div>
<pre class="source"> &lt;plugin&gt;
&lt;groupId&gt;org.apache.sling&lt;/groupId&gt;
&lt;artifactId&gt;slingfeature-maven-plugin&lt;/artifactId&gt;
&lt;version&gt;1.1.12&lt;/version&gt;
&lt;extensions&gt;true&lt;/extensions&gt;
&lt;configuration&gt;
&lt;features&gt;target/fm&lt;/features&gt;
&lt;/configuration&gt;
</pre></div></div>
<p>Now we can aggregate, collect them into a single FM file (attach) and verify all the generated Feature Model files:</p>
<div>
<div>
<pre class="source"> &lt;execution&gt;
&lt;id&gt;aggregate-base-feature&lt;/id&gt;
&lt;phase&gt;generate-test-sources&lt;/phase&gt;
&lt;goals&gt;
&lt;goal&gt;aggregate-features&lt;/goal&gt;
&lt;generatedFeatures&gt;${basedir}/target/fm&lt;/generatedFeatures&gt;
&lt;/goals&gt;
&lt;configuration&gt;
&lt;aggregates&gt;
&lt;aggregate&gt;
&lt;classifier&gt;example-runtime&lt;/classifier&gt;
&lt;filesInclude&gt;**/*.json&lt;/filesInclude&gt;
&lt;/aggregate&gt;
&lt;/aggregates&gt;
&lt;/configuration&gt;
&lt;/execution&gt;
&lt;execution&gt;
&lt;id&gt;attach-base-feature&lt;/id&gt;
&lt;phase&gt;process-test-sources&lt;/phase&gt;
&lt;goals&gt;
&lt;goal&gt;attach-features&lt;/goal&gt;
&lt;/goals&gt;
&lt;/execution&gt;
&lt;execution&gt;
&lt;id&gt;verify-analyze&lt;/id&gt;
&lt;phase&gt;generate-test-resources&lt;/phase&gt;
&lt;goals&gt;
&lt;goal&gt;analyse-features&lt;/goal&gt;
&lt;/goals&gt;
&lt;configuration&gt;
&lt;framework&gt;
&lt;groupId&gt;org.apache.felix&lt;/groupId&gt;
&lt;artifactId&gt;org.apache.felix.framework&lt;/artifactId&gt;
&lt;version&gt;6.0.1&lt;/version&gt;
&lt;/framework&gt;
&lt;scans&gt;
&lt;scan&gt;
&lt;includeClassifier&gt;example-runtime&lt;/includeClassifier&gt;
&lt;includeTasks&gt;
&lt;includeTask&gt;bundle-packages&lt;/includeTask&gt;
&lt;/includeTasks&gt;
&lt;/scan&gt;
&lt;/scans&gt;
&lt;/configuration&gt;
&lt;/execution&gt;
&lt;/executions&gt;
&lt;/plugin&gt;
...
&lt;/plugins&gt;
&lt;/build&gt;
</pre></div></div>
<p>Finally we can define a profile to launch the Feature Model based project. With that the launch is only done if the project is buil with goal <b>install</b> and profile <b>launch</b> (mvn install -P launch):</p>
<div>
<div>
<pre class="source">&lt;profiles&gt;
&lt;profile&gt;
&lt;id&gt;launch&lt;/id&gt;
&lt;build&gt;
&lt;plugins&gt;
&lt;plugin&gt;
&lt;groupId&gt;org.apache.sling&lt;/groupId&gt;
&lt;artifactId&gt;slingfeature-maven-plugin&lt;/artifactId&gt;
&lt;version&gt;1.1.12&lt;/version&gt;
&lt;extensions&gt;true&lt;/extensions&gt;
&lt;dependencies&gt;
&lt;!-- For now the Extension Content has to be placed ahead of the launcher to make CP
deployment work (see SLING-8483) --&gt;
&lt;dependency&gt;
&lt;groupId&gt;org.apache.sling&lt;/groupId&gt;
&lt;artifactId&gt;org.apache.sling.feature.extension.content&lt;/artifactId&gt;
&lt;version&gt;1.0.5-SNAPSHOT&lt;/version&gt;
&lt;/dependency&gt;
&lt;dependency&gt;
&lt;groupId&gt;org.apache.sling&lt;/groupId&gt;
&lt;artifactId&gt;org.apache.sling.feature.launcher&lt;/artifactId&gt;
&lt;version&gt;1.1.0&lt;/version&gt;
&lt;/dependency&gt;
&lt;/dependencies&gt;
&lt;executions&gt;
&lt;execution&gt;
&lt;id&gt;launch-it&lt;/id&gt;
&lt;phase&gt;install&lt;/phase&gt;
&lt;goals&gt;
&lt;goal&gt;launch-features&lt;/goal&gt;
&lt;/goals&gt;
&lt;configuration&gt;
&lt;selection&gt;
&lt;includeClassifier&gt;example-runtime&lt;/includeClassifier&gt;
&lt;/selection&gt;
&lt;/configuration&gt;
&lt;/execution&gt;
&lt;/executions&gt;
&lt;/plugin&gt;
&lt;/plugins&gt;
&lt;/build&gt;
&lt;/profile&gt;
&lt;/profiles&gt;
</pre></div></div>
<p>The execution of a conversion and launch would look like this:</p>
<div>
<div>
<pre class="source">mvn \
clean \
install \
-P launch
</pre></div></div>
</div>
<div class="section">
<h3><a name="Converting_a_Content_Package_and_Install_its_Feature_Model_Descriptor"></a>Converting a Content Package and Install its Feature Model Descriptor</h3>
<p>Instead of building everything local in a dedicated Maven module now each Content Project Module can install their generated Feature Module descriptor into the local Maven repository so that it can be <b>included as artifact</b> when the FM project is assembled.</p>
<p>First in each Content Package module add this plugin configuration to your POM in the <b>build</b> section:</p>
<div>
<div>
<pre class="source">&lt;plugin&gt;
&lt;groupId&gt;org.apache.sling&lt;/groupId&gt;
&lt;artifactId&gt;sling-feature-converter-maven-plugin&lt;/artifactId&gt;
&lt;version&gt;${sling-feature-converter-maven-plugin.version}&lt;/version&gt;
&lt;extensions&gt;true&lt;/extensions&gt;
&lt;executions&gt;
&lt;execution&gt;
&lt;id&gt;convert-cp&lt;/id&gt;
&lt;phase&gt;verify&lt;/phase&gt;
&lt;goals&gt;
&lt;goal&gt;convert-cp&lt;/goal&gt;
&lt;/goals&gt;
&lt;configuration&gt;
&lt;artifactIdOverride&gt;${project.groupId}:${project.artifactId}:slingosgifeature:${{{filename}}}:${project.version}&lt;/artifactIdOverride&gt;
&lt;installConvertedCP&gt;true&lt;/installConvertedCP&gt;
&lt;convertedCPOutput&gt;${project.build.directory}/fm.out&lt;/convertedCPOutput&gt;
&lt;fmOutput&gt;${project.build.directory}/fm&lt;/fmOutput&gt;
&lt;fmPrefix&gt;peregrine-&lt;/fmPrefix&gt;
&lt;isContentPackage&gt;true&lt;/isContentPackage&gt;
&lt;contentPackages&gt;
&lt;contentPackage&gt;
&lt;groupId&gt;${project.groupId}&lt;/groupId&gt;
&lt;artifactId&gt;${project.artifactId}&lt;/artifactId&gt;
&lt;/contentPackage&gt;
&lt;/contentPackages&gt;
&lt;/configuration&gt;
&lt;/execution&gt;
&lt;/executions&gt;
&lt;/plugin&gt;
</pre></div></div>
<ul>
<li><b>sling-feature-converter-maven-plugin.version</b>: is a property with the version of this plugin to be used (1.0.2 for now)</li>
<li><b>artifactIdOverride</b>: This should match the Maven Id with this pattern: &#x2018;groupId&#x2019;:&#x2018;artifactId&#x2019;:&#x2018;type fixed to slingosgifeature&#x2019;:&#x2018;classifier&#x2019;:&#x2018;version&#x2019;</li>
<li><b>installConvertedCP</b>: must be set to true otherwise I cannot be assembled later</li>
<li><b>convertedCPOutput/fmOutput/fmPrefix</b>: adjust to your preferences</li>
<li><b>isContentPackage</b>: must be set to true</li>
<li><b>contentPackage</b>: must match the module&#x2019;s properties (later we might remove this)</li>
</ul>
<p>After a successful build one can check the installation by going to your local Maven repository, got to the location of you artifact and check if there is a file with the extension <b>slingosgifeature</b>.</p>
<p>Now we can go to the Assembly part and add the FM installed locally as artifact:</p>
<div>
<div>
<pre class="source">&lt;plugin&gt;
&lt;groupId&gt;org.apache.sling&lt;/groupId&gt;
&lt;artifactId&gt;slingfeature-maven-plugin&lt;/artifactId&gt;
&lt;version&gt;${slingfeature-maven-plugin.version}&lt;/version&gt;
&lt;extensions&gt;true&lt;/extensions&gt;
&lt;configuration&gt;
&lt;features&gt;target/fm&lt;/features&gt;
&lt;generatedFeatures&gt;${basedir}/target/fm&lt;/generatedFeatures&gt;
&lt;/configuration&gt;
&lt;executions&gt;
&lt;execution&gt;
&lt;id&gt;aggregate-base-feature&lt;/id&gt;
&lt;phase&gt;generate-test-sources&lt;/phase&gt;
&lt;goals&gt;
&lt;goal&gt;aggregate-features&lt;/goal&gt;
&lt;/goals&gt;
&lt;configuration&gt;
&lt;aggregates&gt;
&lt;aggregate&gt;
&lt;classifier&gt;example-runtime&lt;/classifier&gt;
&lt;filesInclude&gt;**/*.json&lt;/filesInclude&gt;
&lt;configurationOverrides&gt;*=USE_LATEST&lt;/configurationOverrides&gt;
&lt;includeArtifact&gt;
&lt;groupId&gt;org.apache.sling&lt;/groupId&gt;
&lt;artifactId&gt;base.ui.apps&lt;/artifactId&gt;
&lt;version&gt;1.0.4&lt;/version&gt;
&lt;classifier&gt;base.ui.apps&lt;/classifier&gt;
&lt;type&gt;slingosgifeature&lt;/type&gt;
&lt;/includeArtifact&gt;
...
&lt;/aggregate&gt;
&lt;/aggregates&gt;
&lt;/configuration&gt;
&lt;/execution&gt;
&lt;/executions&gt;
&lt;/plugin&gt;
</pre></div></div>
<ul>
<li><b>slingfeature-maven-plugin.version</b>: version of the sling feature maven plugin to be used</li>
<li><b>features/generatedFeatures</b>: add/set depending on your project</li>
<li><b>classifier/filesInclude/configurationOverrides</b>: set depending on your project</li>
<li><b>includeArtifact</b>: one entry per Content Package FM. The <b>groupId</b>, <b>artifactId</b>, <b>version</b> and <b>classifier</b> must match your FM descriptor</li>
</ul></div></div>
</div>
</div>
</div>
<hr/>
<footer>
<div class="container-fluid">
<div class="row-fluid">
<p>Copyright &copy;2007&#x2013;2020
<a href="https://www.apache.org/">The Apache Software Foundation</a>.
All rights reserved.</p>
</div>
</div>
</footer>
</body>
</html>