|
|
Line 1: |
Line 1: |
| <!-- page was renamed from PackagingDrafts/EclipsePlugins | | <!-- page was renamed from PackagingDrafts/EclipsePlugins |
| --> | | --> |
| = Packaging Eclipse Plugins =
| |
|
| |
|
| |
|
| |
| == Glossary ==
| |
| * '''Bundle''': An [http://en.wikipedia.org/wiki/OSGi#Bundles "OSGi bundle"].
| |
| * '''Plugin''': A functional unit of Eclipse functionality. Post-Eclipse 3.0, the term "plugin" can almost always be interchanged with the term "bundle". Colloquially, among non-Eclipse developers, the term is used to refer to a set of functional Eclipse plugins ex. "CDT".
| |
| * '''Feature''': A collection of plugins.
| |
| * '''Fragment''': A bundle with native elements ex. <code>org.eclipse.core.filesystem.linux.${arch}</code>
| |
|
| |
| == Introduction == | | == Introduction == |
| Eclipse is a modular platform that can be used for building everything from server-side applications to full-blown graphical applications like the Eclipse IDE and Lotus Notes. Each of the modular blobs is referred to as a plugin or a bundle. In a nutshell, the system itself is a small runtime (Equinox) based on the OSGi specifications [see http://www.eclipse.org/equinox/ for more information] which loads and runs a given list of bundles. Most people think of Eclipse as a programming integrated development environment (IDE). This document details best practices for packaging Eclipse IDE plugins. Examples include adding Subversion functionality (<code>eclipse-subclipse</code>) and tools for tracking your tasks (<code>eclipse-mylyn</code>).
| |
|
| |
| == Naming ==
| |
| Eclipse plugin packages '''MUST''' be named <code>eclipse-<projectname></code>. For example, a package of the anyedit plugin for Eclipse would by named <code>eclipse-anyedit</code>.
| |
|
| |
| === Binary RPM naming ===
| |
| If a project provides multiple features, package each of the features as a separate binary plugin, matching the naming and grouping of plugins directly.
| |
|
| |
| === Group Tag ===
| |
| There is no single Group tag for Eclipse plugins. Choose a Group that best fits the plugin and satisfies <code>rpmlint</code>. Some of the existing Groups include:
| |
| <pre>
| |
| Development/Tools
| |
| Development/Languages
| |
| System Environment/Libraries
| |
| </pre>
| |
|
| |
| == Source ==
| |
| Obtaining source for Eclipse plugins is sometimes difficult. Most projects do not release source tarballs so it is often necessary to create an archive from a source revision control system. Ensure that instructions for reproducing the source archive are included in comments in the specfile. These instructions can take the form of either explicit instructions as in [http://cvs.fedoraproject.org/viewcvs/*checkout*/devel/eclipse-cdt/eclipse-cdt.spec eclipse-cdt] or be put into a [http://cvs.fedoraproject.org/viewcvs/*checkout*/devel/eclipse-rpm-editor/fetch-specfile-editor.sh?content-type=text%2Fplain separate shell script] as in [http://cvs.fedoraproject.org/viewcvs/*checkout*/devel/eclipse-rpm-editor/eclipse-rpm-editor.spec eclipse-rpm-editor] .
| |
|
| |
| Remember that Eclipse plugin packages, like all Fedora software packages, must be built from source, and cannot contain any "pre-built" binary components.
| |
|
| |
| == Building ==
| |
| Eclipse plugins '''SHOULD''' be built with the Eclipse Plugin Development Environment (PDE; PDE Build specifically) because these builds are generally easier to maintain. <code>ant</code> builds are acceptable, but are generally more difficult to maintain. Following what upstream does is the best practice.
| |
|
| |
| === pdebuild ===
| |
| There is a script that makes invoking PDE Build easy: <code>/usr/lib{,64}/eclipse/buildscripts/pdebuild</code>:
| |
|
| |
| <pre>
| |
| usage: /usr/lib{,64}/eclipse/buildscripts/pdebuild [<options>]
| |
|
| |
| Use PDE Build to build Eclipse features
| |
|
| |
| Optional arguments:
| |
| -h Show this help message
| |
| -f Feature ID to build
| |
| -d Plugin dependencies in addition to Eclipse SDK
| |
| (space-separated, names on which to glob features and plugins)
| |
| -a Additional build arguments (ex. -DjavacSource=1.5)
| |
| -j VM arguments (ex. -DJ2SE-1.5=%{_jvmdir}/java/jre/lib/rt.jar)
| |
| -v Be verbose
| |
| -D Debug platform itself (passes -consolelog -debug to Eclipse)
| |
| -o Orbit dependencies
| |
| </pre>
| |
|
| |
| == File Locations ==
| |
| All platform-independent plugins/features should go into <code>%{_datadir}/eclipse/dropins/<one word name of this feature or plugin></code>. JARs should therefore go into <code>%{_datadir}/eclipse/dropins/<name>/plugins</code> and features should go into <code>%{_datadir}/eclipse/dropins/<name>/features</code>. Architecture-specific plugins/features should go into <code>%{_libdir}/eclipse/dropins/<one word name of this feature or plugin></code>. JARs should therefore go into <code>%{_libdir}/eclipse/dropins/<name>/plugins</code> and features should go into <code>%{_datadir}/eclipse/dropins/<name>/features</code>. Example:
| |
|
| |
| <pre>
| |
| %install
| |
| installDir=%{buildroot}%{_datadir}/eclipse/dropins/quickrex
| |
| install -d -m 755 $installDir
| |
| unzip -q -d $installDir \
| |
| build/rpmBuild/de.babe.eclipse.plugins.QuickREx.zip
| |
| </pre>
| |
|
| |
| == Arch vs. noarch ==
| |
| While many Eclipse plugins will be architecture-independent, there will be some that contain native parts. Plugins without native fragments should be noarch and go into %{_datadir}/eclipse/dropins and plugins with native fragments should be arch-dependent and go into %{_libdir}/eclipse/dropins.
| |
|
| |
| == Things to avoid ==
| |
| === Pre-built binaries ===
| |
| If Eclipse plugins depend upon third party libraries (and licensing permits it), developers often include these libraries directly in their source control system. In this case, the libraries must exist as other packages in Fedora and their contents (such as their JARs) be symlinked from within the source and build trees of the Eclipse plugin being packaged. While it may make source archives smaller in size if they are cleansed of these pre-built files, it is not necessary to do so unless the libraries themselves are not redistributable. Binary RPMs '''MUST NOT''' include pre-built files.
| |
|
| |
| {{Template:Note}} A simple check which may be run at the end of <code>%prep</code> (courtesy David Walluck (I think that's who gave it to Ben Konrath)):
| |
| <pre>
| |
| JARS=""
| |
| for j in $(find -name \*.jar); do
| |
| if [ ! -L $j ] ; then
| |
| JARS="$JARS $j"
| |
| fi
| |
| done
| |
| if [ ! -z "$JARS" ] ; then
| |
| echo "These JARs should be deleted and symlinked to system JARs: $JARS"
| |
| exit 1
| |
| fi
| |
| </pre>
| |
|
| |
| === Differing from upstream ===
| |
| Plugins that are jarred should remain jarred and those that are expanded should be expanded in their RPM. There are two cases (that we can think of as of this writing) that warrant diverging from upstream:
| |
| # Symlinking to a binary JAR from another package
| |
| # Expanding a JAR to allow for symlinking to a binary JAR from another package
| |
|
| |
| See below for a tip on how to deal with the expanded JAR case.
| |
|
| |
| == Specfile Template ==
| |
| <pre>
| |
|
| |
| Name: eclipse-plugin
| |
| Version: 1.0
| |
| Release: 1%{?dist}
| |
| Summary: Plugin provides such and such functionality for the Eclipse IDE.
| |
|
| |
| Group: Development/Tools
| |
| License: EPL
| |
| URL: http://www.eclipse.org/plugin
| |
| Source0: org.eclipse.plugin-TAG-fetched-src.tar.bz2
| |
| Arch: noarch
| |
|
| |
| BuildRequires: java-devel >= 1.5.0
| |
| BuildRequires: eclipse-pde
| |
| Requires: eclipse-platform
| |
| BuildRequires: eclipse-platform
| |
|
| |
| %description
| |
| Plugin provides such and such functionality for the Eclipse IDE.
| |
| Specific functionality b is provided in %{name}-b.
| |
|
| |
| %package b
| |
| Summary: b functionality for plugin
| |
| Requires: %{name} = %{version}-%{release}
| |
| Group: Development/Tools
| |
|
| |
| %description b
| |
| %{name}-b enhances plugin with b-specific functionality.
| |
|
| |
| %prep
| |
| %setup -q org.eclipse.plugin
| |
|
| |
| %build
| |
| %{_eclipse_base}/buildscripts/pdebuild -f org.eclipse.plugin_feature
| |
|
| |
| %{_eclipse_base}/buildscripts/pdebuild -f org.eclipse.plugin.b_feature
| |
|
| |
| %install
| |
| install -d -m 755 $RPM_BUILD_ROOT%{_datadir}/eclipse/dropins/plugin-a
| |
| unzip -q -d $RPM_BUILD_ROOT%{_datadir}/eclipse/dropins/plugin-a \
| |
| build/rpmBuild/org.eclipse.plugin_feature.zip
| |
| unzip -q -d $RPM_BUILD_ROOT%{_datadir}/eclipse/dropins/plugin-b \
| |
| build/rpmBuild/org.eclipse.plugin.b_feature.zip
| |
|
| |
| %files
| |
| %{_datadir}/eclipse/dropins/plugin-a
| |
|
| |
| %files b
| |
| %{_datadir}/eclipse/dropins/plugin-b
| |
|
| |
| %changelog
| |
| * Fri Oct 17 2008 Andrew Overholt <overholt redhat com> 1.0-2
| |
| - Update for Eclipse 3.4.x
| |
|
| |
| * Fri Feb 29 2008 Andrew Overholt <overholt@redhat.com> 1.0-1
| |
| - Initial Fedora package
| |
| </pre>
| |
|
| |
| == Tips and Notes ==
| |
|
| |
|
| === Common Defines ===
| | This page contains Fedora guidelines for packaging Eclipse plug-ins. Since Eclipse plug-ins are also Java packages, this page extends (and where necessary, overrides) the guidelines laid out in the [[Packaging/Java|Fedora Packaging Guidelines for Java]]. If you are not familiar with Java packaging in Fedora, [[Packaging/Java|please read the Java guidelines]] before continuing. |
|
| |
|
| === Requires === | | == Package naming == |
| Until <code>rpmstubby</code> (see below) is released and/or more widespread, <code>Requires</code> on bits provided by the Eclipse SDK (RCP, SWT, Platform, JDT, PDE, CVS, etc.) should only be on the binary package providing the required functionality (ex. <code>eclipse-cvs-client</code> or <code>eclipse-rcp</code>). For IDE features, the most common requirement will be <code>eclipse-platform</code>.
| |
|
| |
|
| === Features vs. Plugins ===
| | Packages '''MUST''' follow the standard Fedora [[Packaging/NamingGuidelines#Addon_Packages_.28Eclipse_plugins.29 | package naming guidelines]] for add-on packages. |
| Eclipse features are groups of plugins. They are preferred, but not required since they provide nice demarcation lines for binary RPMs. We generally try to make binary RPMs mirror upstream features. Eclipse features also work nicely with <code>rpmstubby</code> (see below), but not all plugins have features.
| |
|
| |
|
| === JAR Expansion === | | == BuildRequires and Requires == |
| In rare cases it may be necessary to symlink to something ''inside'' a JAR. This situation is often referred to as "nested JARs". If the plugin code itself is not enclosed in a nested JAR, expansion will result in a directory structure containing class files. This is best illustrated with an example:
| |
|
| |
|
| <pre>
| | Eclipse plug-ins in Fedora are always built with Maven/Tycho, so they '''MUST''' BuildRequire it: |
| $ unzip -l org.eclipse.mylyn.web.core_2.2.0.I20071220-1700.jar | grep jar$
| | * <code>BuildRequires: tycho</code> |
| 46725 12-20-07 20:08 lib-httpclient/commons-codec-1.3.jar
| |
| 279781 12-20-07 20:08 lib-httpclient/commons-httpclient-3.0.1.jar
| |
| 38015 12-20-07 20:08 lib-httpclient/commons-logging-1.0.4.jar
| |
| 26202 12-20-07 20:08 lib-httpclient/commons-logging-api-1.0.4.jar
| |
| 153253 12-20-07 20:08 lib-rome/jdom-1.0.jar
| |
| 197290 12-20-07 20:08 lib-rome/rome-0.8.jar
| |
| 26624 12-20-07 20:08 lib-xmlrpc/ws-commons-util-1.0.1-sources.jar
| |
| 34840 12-20-07 20:08 lib-xmlrpc/ws-commons-util-1.0.1.jar
| |
| 35142 12-20-07 20:08 lib-xmlrpc/xmlrpc-client-3.0-sources.jar
| |
| 43312 12-20-07 20:08 lib-xmlrpc/xmlrpc-client-3.0.jar
| |
| 91225 12-20-07 20:08 lib-xmlrpc/xmlrpc-common-3.0-sources.jar
| |
| 98051 12-20-07 20:08 lib-xmlrpc/xmlrpc-common-3.0.jar
| |
| </pre> | |
|
| |
|
| Note that we have embedded JARs which we would like to turn into symlinks to existing JARs (from other packages). If we simply unzip the plugin JAR and symlink, one would think we would be okay:
| | And optionally, for plug-ins that make advanced use of Tycho: |
| | * <code>BuildRequires: tycho-extras</code> |
|
| |
|
| <pre> | | Since Eclipse plug-in packages are also Java packages, the binary packages or their dependencies '''MUST''' have Requires (generated by RPM or manual) on: |
| $ unzip -qq org.eclipse.mylyn.web.core_2.2.0.I20071220-1700.jar
| | * <code>java-headless</code> or <code>java-headless >= 1:minimal_required_version</code> |
| $ rm !$
| | * <code>javapackages-tools</code> |
| $ ls
| |
| about.html lib-httpclient lib-rome lib-xmlrpc META-INF org
| |
| $ <do symlinking here>
| |
| </pre> | |
|
| |
|
| However, we end up with the plugin classes themselves being expanded in the <code>org</code> directory. [https://bugzilla.redhat.com/273881 Bug #273881] causes build failures when building debuginfo packages in this case. The acceptable workaround is to modify the build.properties file in the plugin to JAR the plugin code separately (ex. <code>mylyn-webcore.jar</code>) and include it within this expanded plugin directory. An example of this work-around can be seen in [http://cvs.fedoraproject.org/viewcvs/devel/eclipse-mylyn/ eclipse-mylyn] (specifically the patches related to <code>org.eclipse.mylyn.webcore</code>).
| | And additionally, Eclipse plug-in binary packages or their dependencies '''MUST''' have Requires (generated by RPM or manual) on: |
| | * <code>eclipse-filesystem</code> |
| | * <code>eclipse-platform</code> |
|
| |
|
| === rpmstubby ===
| | {{admon/note|Note|In order to avoid circular dependencies, there is an exception to this rule. If the plug-in form a constituent part of the core Eclipse platform, then the binary package '''MUST NOT''' have a Requires on <code>eclipse-platform</code>.}} |
| <code>rpmstubby</code> is a small project that is part of the [http://eclipse.org/linuxtools linuxdistros project] at eclipse.org. Its aim is to make packaging Eclipse plugins as RPMs extremely simple. Specfiles for packages like <code>eclipse-mylyn</code> were originally stubbed out using it. Available as eclipse-rpmstubby package.
| |
|
| |
|
| [[Category:Packaging guidelines]] | | [[Category:Packaging guidelines]] |