eclipse/site/src/site/apt/development.apt

 -----
 Development of Apache Doxia Eclipse Editor Plugin
 -----
 Vincent Siveton
 Benson Margulies
 -----
 2011-09-09
 -----

~~ Licensed to the Apache Software Foundation (ASF) under one
~~ or more contributor license agreements.  See the NOTICE file
~~ distributed with this work for additional information
~~ regarding copyright ownership.  The ASF licenses this file
~~ to you under the Apache License, Version 2.0 (the
~~ "License"); you may not use this file except in compliance
~~ with the License.  You may obtain a copy of the License at
~~
~~   http://www.apache.org/licenses/LICENSE-2.0
~~
~~ Unless required by applicable law or agreed to in writing,
~~ software distributed under the License is distributed on an
~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
~~ KIND, either express or implied.  See the License for the
~~ specific language governing permissions and limitations
~~ under the License.

~~ NOTE: For help with the syntax of this file, see:
~~ http://maven.apache.org/doxia/references/apt-format.html

Development of Apache Doxia Eclipse Editor Plugin

  The project is divided in an OSGi bundle containing Apache Doxia and a set of Eclipse plugins and features.
  The build uses {{{http://www.eclipse.org/tycho/}Tycho}} and of course Apache Maven (version 3).

* Doxia Components as an OSGi plugin

   To have eclipse plugins that use the insides of Doxia, we need at least one
   OSGi bundle containing Doxia itself (<<<org.apache.maven.doxia.eclipse.dependencies>>>).
   This could be arranged by adding OSGi
   manifest metadata to them one-at-a-time, but I doubt that anyone has much
   enthusiasm for that.

   The initial attempt at this using the maven-bundle-plugin was relatively simple.
   By using Embed-Dependencies and _exportcontents, you can instruct it to
   grab all the maven dependencies of the current project as jars embedded in the
   bundle jar, and set up the manifest to match.

   Unfortunately, both the maven-eclipse-plugin and M2E are poorly behaved
   in the face of this. m-e-p responds by trying to edit the MANIFEST.MF of
   a project that uses it. M2E, according to Igor, 'does not support
   Embed-Dependencies'. Since some of us are not big M2E fans, I'm structuring
   this in a way which should be palatable to both.

   That requires giving up on Tycho's ability to work with a dependent bundle
   called out as a Maven dependency. Instead, this project builds an OSGi
   bundle which is, essentially, 'shaded', and then sticks it into a P2 repository
   hiding in the local repository. Then the Tycho build of the editor plugins
   searches that repository.

* Eclipse plugins

   The plugins are divided in a common project (<<<org.apache.maven.doxia.ide.eclipse.common.ui>>>), which contains all
   generic classes to handle actions, dialogs, editors, rules and wizards.
   Other plugins are specific implementations for a given Doxia format (i.e. APT).

* Building

  Tycho won't resolve through the reactor for the bundle, so you need to build
  <<<org.apache.maven.doxia.eclipse.dependencies>>> project first:

+-------------------------------+
mvn clean install -f doxia-osgi/pom.xml
|_ Makes an OSGi bundle of Doxia.
+-------------------------------+

  Then, and only then, you can build plugins themselves:

+-------------------------------+
mvn clean install -f eclipse-plugins/pom.xml
|_ Creates a feature and a P2 repository
|_ Builds Eclipse plugins
+-------------------------------+

  See the {{{http://svn.apache.org/repos/asf/maven/doxia/doxia-ide/trunk/eclipse/README.TXT}README.TXT}}
  for more informations.