Clarify Building section in Readme

[kwin]

Currently the readme just states

To compile your own version of the Core Components, you can build and install everything on your running AEM instance by issuing the following command in the top level folder of the project: mvn clean install -PautoInstallSinglePackage

This is not enough for local AEM instances based on a newer quickstart from https://experience.adobe.com/#/downloads/content/software-distribution/en/aemcloud.html.

The reason is twofold:

1. The AEM quickstart already comes with Core WCM Components preinstalled
2. The OSGi installer is configured in a way that it allows multiple version of the same BSN (https://sling.apache.org/documentation/bundles/osgi-installer.html#multi-version-support)

As the original Core WCM version cannot be uninstalled easily (as it is installed from location launchpad:resources/install/20/core.wcm.components.core-2.11.1.jar) there is no easy way to force the scripts to load the classes from the newer bundle (https://issues.apache.org/jira/browse/SLING-9210).

[msagolj]

@kwin you are correct the above description is only for the on-prem versions of quickstart. What you are referring to is the local installable cloud-ready quickstart.

An additional important thing to note is that in the cloud ready quickstart the core components are installed under /libs and not /apps (due to some restrictions that are enforced by AEMaaCS).

So we internally introduced the cloud profile, that generates additional packages during build with extension -cloud.zip for the content and /extensions/amp/content packages so they can be used to be installed on a cloud ready quickstart.

Lately we extended the profile to also generate an -allpackage with the correct cloud content packages so you should be able to use:

mvn clean install -PautoInstallSinglePackage -Pcloud

see Issue #1262, PR is #1263.

But unfortunately as you noted in 2. above, the command will update the content package, but you end up with 2 core component bundles installed and active. So you still have to manually remove the unwanted version in the /system/console.

The issue #1262 is still open , so any ideas for how we could simplify this further are welcome :)

[kwin]

IMHO the most straightforward way to achieve that is deploying the bundle separately via sling-maven-plugin with the deploymentMethod=WebConsole, as that will upgrade by default (https://github.com/apache/felix-dev/blob/a1dfca900fe853fe5c73da936e0642c85886463a/webconsole/src/main/java/org/apache/felix/webconsole/internal/core/BundlesServlet.java#L1590). For the Sling Installer itself there is no option yet: https://issues.apache.org/jira/browse/SLING-9951.

I would suggest to come up with a new profile autoInstallForCloudQuickstart which deploys packages not containing the bundles the regular way (but to /libs instead of /apps) and in addition deploys the bundles like outlined above.

[kwin]

Another related issue is that even with all workarounds from above (i.e. deploying the script to /libs/...) the precompiled HTL scripts in bundle with BundleSymbolic-Name aem-precompiled-scripts still take precedence! How can I force it to use my scripts? Compare with https://issues.apache.org/jira/browse/SLING-9965.

Actually the only way to overwrite the bundled scripts is by deploying them to /apps instead of /libs!

[stefanseifert]

i think the usual workaround is to stop the bundle aem-precompiled-scripts in your local instance

[kwin]

Another issue: Deploying the snapshot version of the bundle via sling-maven-plugin only works one time -> https://issues.apache.org/jira/browse/FELIX-6365.

Also when executing mvn install -PautoInstallPackage on the core bundle, the deployment is executed two times

[INFO]
[INFO] --- maven-sling-plugin:2.1.0:install (default) @ core.wcm.components.core ---
[INFO] Installing Bundle com.adobe.cq.core.wcm.components.core(/Users/konradwindszus/git/aem-core-wcm-components/bundles/core/target/core.wcm.components.core-2.12.3-SNAPSHOT.jar) to http://localhost:4502/system/console via POST
[INFO] Bundle installed
[INFO]
[INFO] --- maven-sling-plugin:2.1.0:install (install-bundle) @ core.wcm.components.core ---
[INFO] Installing Bundle com.adobe.cq.core.wcm.components.core(/Users/konradwindszus/git/aem-core-wcm-components/bundles/core/target/core.wcm.components.core-2.12.3-SNAPSHOT.jar) to http://localhost:4502/system/console via POST
[INFO] Bundle installed

[vladbailescu]

@kwin , we moved the building information to a dedicated file and I documented the cloud profile. I also added an id for the maven-sling-plugin in parent.pom to prevent duplicated execution. See https://github.com/adobe/aem-core-wcm-components/pull/1313