incubator-sling-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From romb...@apache.org
Subject svn commit: r1607072 - in /sling/site/trunk/content/documentation: development.mdtext development/ide-tooling.mdtext
Date Tue, 01 Jul 2014 13:35:09 GMT
Author: rombert
Date: Tue Jul  1 13:35:08 2014
New Revision: 1607072

URL: http://svn.apache.org/r1607072
Log:
Transfer the IDE Tooling User Guide from Confluence

- converted text, images are missing for now

Added:
    sling/site/trunk/content/documentation/development/ide-tooling.mdtext
Modified:
    sling/site/trunk/content/documentation/development.mdtext

Modified: sling/site/trunk/content/documentation/development.mdtext
URL: http://svn.apache.org/viewvc/sling/site/trunk/content/documentation/development.mdtext?rev=1607072&r1=1607071&r2=1607072&view=diff
==============================================================================
--- sling/site/trunk/content/documentation/development.mdtext (original)
+++ sling/site/trunk/content/documentation/development.mdtext Tue Jul  1 13:35:08 2014
@@ -14,6 +14,7 @@ Look here for more information on develo
 * [Monitoring Requests]({{ refs.monitoring-requests.path }})
 * [Repository Based Development]({{ refs.repository-based-development.path }})
 * [Sling Testing Tools]({{ refs.sling-testing-tools.path }})
+* [Sling IDE Tooling]({{ refs.ide-tooling.path }})
 
 
 ## Maven Stuff

Added: sling/site/trunk/content/documentation/development/ide-tooling.mdtext
URL: http://svn.apache.org/viewvc/sling/site/trunk/content/documentation/development/ide-tooling.mdtext?rev=1607072&view=auto
==============================================================================
--- sling/site/trunk/content/documentation/development/ide-tooling.mdtext (added)
+++ sling/site/trunk/content/documentation/development/ide-tooling.mdtext Tue Jul  1 13:35:08
2014
@@ -0,0 +1,139 @@
+Title: Sling IDE tooling for Eclipse User Guide
+
+## Prerequisites
+
+The Sling IDE tooling is known to work on Eclipse versions starting with Kepler. There is
a hard dependency on the faceted project framework, which is included in the 'Eclipse IDE
for Java EE Developers' package. If you're running a different package, you can always install
it from the main Eclipse update site.
+
+There is an optional feature which relies on m2eclipse. For now it only provides project
creation wizards, so if you don't use Maven you don't have to install it.
+Installation
+
+## Overall concepts
+
+The Sling IDE tooling is centered around the Server and Module concepts. A Server is an instance
of a Sling launchpad - or derivatives such as Adobe CQ - on which you deploy your content.
A Module is a collection of resources grouped into a single Eclipse project which can be deployed
onto one or multiple Servers.
+
+The tooling supports content and bundle modules. Content modules typically hold Sling scripts
- like JSP and ESP files, client-side resources like CSS and JSS file, but also arbitrary
repository content. Content modules support support setting JCR properties for nodes other
than nodes and files, based on the FileVault serialization format. You can read mode about
FileVault at the Apache Jackkrabit FileVault docs Bundle modules represent a single OSGi bundle.
+Server definition
+
+To create a new Sling launchpad server you will need to start a Sling launchpad outside of
Eclipse. We do not yet support starting Sling Launchpad instances from Eclipse.
+
+To kick off, create a new Sling Launchpad Server using the File -> New -> Other...
menu entry.
+
+In the resulting wizard, select the External Sling Launchpad category and enter the host
name.
+
+Once that is done, press finish.
+
+## Server configuration
+
+The server will appear in the servers view. You can double-click on it to review the settings
which were automatically provided.
+
+There are a couple of important settings in the server definition page:
+
+# port: used for connecting to the server
+# publishing interval: controls how fast the resources will be published after a change.
We recommend setting the interval to 0, for fast deploy times
+# username, password, context path: controls the connection details to the Sling instance.
+# debug port: used for connecting in debug mode
+
+For working with OSGi bundles, a special support bundle must be installed to support fast
bundle redeployment. If it is not present, you can install it using the hyperlink from the
Install section.
+
+You can now connect to the server
+
+## Content sync
+
+Content projects are required to have at least
+
+# a jcr_root directory, which contains the serialized content of the repository
+# a META-INF/vault/filter.xml file, which contains the workspace filter definition
+
+All changes performed in the local workspace are synchronized to the repository, given that
they are included in the workspace filter definition.
+
+### Creating a new content project
+
+Creating a new Sling content project is easily done by using the new Sling Content Project
Wizard. To kick off, start by selected File -> New -> Project and select Sling Content
Project under the Sling category.
+
+You will then be asked to name the project and select its location.
+
+Finally, you can select whether to add the project to an existing server or create a new
one.
+
+Once you press finish, the project will be created and deployed to the server.
+
+### Converting existing projects
+
+To mark a project as being a Sling content module, click it in the Project Explorer and Select
Configure -> Convert to Sling Content Project... . A dialog will pop up and will ask you
to confirm the inferred location of the jcr_root directory. You can also change this from
the project properties, the Sling page.
+
+### Content navigator
+
+In the Project Explorer view there is an additional 'jcr_root' contribution to the project.
It is denoted by a folder icon with a small web overlay. This contribution provides a logical
view over the repository content, taking into account JCR metadata. As such, .content.xml
files will be folded into the corresponding node.
+
+Node properties can be edited in a distinct JCR properties view.
+
+### filter.xml - workspace filter definition
+
+A content project does not synchronize all its contents to the workspace. Instead, it looks
for a filter.xml file which defines which content is included in synchronization operations.
More information about the filter.xml file format and semantics can be found at FileVault
docs - Workspace Filter
+
+### Deploying projects on the server
+
+To deploy a project on the server, open the Servers view and use the Add and Remove... dialog
to add one or more modules.
+
+After content projects are deployed, each change will cause the changed resources to be updated
in the repository.
+
+### Manual content sync
+
+It is possible to manually import/export content from/to the repository. The precondition
is that the content project must be associated with a started Sling launchpad server. The
actions are available on the project root, or on any child resource under the jcr_root folder.
+
+The export wizard is available under the Sling -> Export Content ... action.
+
+The import wizard is available under the Sling -> Export Content ... action.
+
+## Bundle sync
+
+The only requirement for bundle projects is that they are Java projects which generate an
exploded OSGi bundle in their output directory. That requires at least a valid OSGi Manifest
located in META-INF/MANIFEST.MF, but typically one of more Java classes. Other auxiliary files,
such as Declarative Service descriptors, must also be placed under the project's output directory.
+
+### Creating a new bundle project
+
+Creating a new Sling bundle project is easily done by using the new Sling Bundle Project
Wizard. This wizard is only available when the Maven-based integration is installed. To kick
off, start by selected File -> New -> Project and select Sling Bundle Project under
the Sling category.
+
+The next page allows you to select the archetype to use. It's recommended to select the latest
version of the archetype.
+
+You will be asked to configure the archetype's properties.
+
+Finally, you can select whether to add the project to an existing server or create a new
one.
+
+Once you press finish, the project will be created and deployed to the server.
+
+### Converting existing projects
+
+To mark a project as being a Sling bundle module, right click it in the Project Explorer
and Select Configure -> Convert to Sling Bundle Project... . A dialog will appear with
all the candidate Sling bundle project from the workspace so that you can quickly select multiple
projects.
+
+### Deploying projects on the server
+
+To deploy a project on the server, open the Servers view and use the Add and Remove... dialog
to add one or more modules.
+
+After OSGi bundle projects are deployed, each change will cause the bundle to be redeployed
on the server.
+
+## Troubleshooting
+
+### Gathering debug information
+
+All operations that are performed on the Sling launchpad are logged in the Sling console.
To view these operations, open the Eclipse console view and select Open Console -> Sling
Console.
+
+Additional information can be obtained by enabling the Eclipse platform tracing facility.
To do so, open the Eclipse preferences and navigate to General -> Tracing. Make sure that
'Enable tracing' is checked and all options under 'Sling IDE Tooling' are enabled.
+
+Why do I get an errror about "No DS descriptor found at..."?
+
+Bundle deployment assumes that the OSGi bundle is packaged into the project's output directory.
This includes:
+
+# the manifest
+# compiled class files
+# resources
+# Declarative Services descriptors
+
+One often-occuring situation is that a Maven project using the maven-scr-plugin generates
the descriptors outside of target/classes, typically in target/scr-plugin-generated. To fix
this, make sure that you're using the maven-scr-plugin 1.15.0 or newer and that you have not
set a custom outputDirectory.
+
+# Known issues
+
+The content sync implementation tries to mimic the FileVault semantics as closely as possible.
However, it is possible that some more exotic content structures will not be handled properly.
Some of the problems we're are of are:
+
+# [SLING-3586 - Publishing content fails if intermediate nodes are not present in the repository](https://issues.apache.org/jira/browse/SLING-3586)
. The workaround is to manually create the missing nodes in the repository .
+# [SLING-3591 - Unable to delete all nodes of a full coverage aggregate](https://issues.apache.org/jira/browse/SLING-3591)
. The workaround is to manually delete the child nodes .
+# [SLING-3573 - Local resources which are no longer present in the repository are not deleted
when importing](https://issues.apache.org/jira/browse/SLING-3573) . The workaround is to manually
delete the workspace files .
+# [SLING-3644 - Improve handling of binary properties outside nt:file file nodes](https://issues.apache.org/jira/browse/SLING-3644)
. Currently there is no workaround, but in practice this is not an often-encountered situation.
\ No newline at end of file



Mime
View raw message