----- Doxia Eclipse IDE plugins ----- Benson Margulies ----- 25 August 2011 ----- Overview A collection of Eclipse Editors for the common file formats of Doxia: * APT * Confluence * DocBook (simple) * FML * TWiki * XDOC * XHTML These are made up of an OSGi bundle containing Doxia itself, plus a series of Eclipse plugins that provide the editors. Tree Structure [doxia-osgi] builds an OSGi bundle with all of the dependencies that are not OSGi in their native form. Due to a Tycho limitation, you have to run mvn install on this before building the <<>> subdirectory. [eclipse-plugins] contains all of the other material, using Tycho to make eclipse plugins. Build Process The goal here is to permit both a relatively normal Maven build process and active development inside Eclipse. Due to the unsettled state of the technologies that can connect Maven and Eclipse, what we have is something of a camel. The first task is to package Doxia in OSGi. In, perhaps, a perfect world, all the relevant Doxia bits-and-pieces would have independent OSGi metadata, and be deployed in a public P2 repository (e.g. the Nexus Pro at repository.apache.org). However, this would be considerable effort for dubious value, and further the Doxia components have the same package in multiple components, which causes 'split package' syndrome in OSGi. Rather than add OSGi metadata to all of the individual pieces, this project builds a single bundle that incorporates all of them, and then exports their APIs. The work is done by the <<>> in <<>>. The POM includes all the configuration for the bundle. The present author does not know how all of this gets along with the <<>>. OSGi versioning works differently from the usual Maven convention. Since we're not publishing via the deploy plugin, it's probably safest to tag, update versions, and release by hand. It only has to happen once per Doxia release. See Peter Kriens' explanation of the muddle with OSGi version numbers {{{http://www.osgi.org/blog/2011/06/negative-qualifiers.html}here}}. One solution goes like this: you release (e.g.) 1.0.0. Then set the version number to 1.0.100.qualifier, and use the auto-generated qualifiers. Then, to make a release, you set the version to (e.g.) 1.1.0. This means giving up on the third digit, but we don't generally use three numbers around Maven anyhow. The <<>> directory takes the plugin and packages it up as a feature in a P2 repository. This is just for convenience; I've found that Eclipse more reliably imports projects from here than from the target directory where the bundle plugin operates. Once Doxia is 'bundled', the next problem is the Eclipse plugins themselves. Here, in the <<>> directory, the build uses the Tycho plugins. The Tycho plugins produce Eclipse-compatible OSGi bundles with a minimum of configuration. They also have a minimum of documentation and useful logging messages. So when things go wrong, it can get confusing in a hurry. Tycho will grab the Doxia bundle from the Maven local repository, but not if it is built in the same reactor. Thus, you have to run mvn twice: once to build doxia-osgi, and once for the plugins. The <<>> build delivers its results in <<>>. That is a P2 repository. It can be copied to any old http server and away it goes. I don't know why we would care to bother to make an 'update site' as opposed to a P2 repo. Tycho is completely incompatible with the <<>>, so, again, some sort of manual procedure is called for.