Difference between revisions of "Eclipse plugin package guidelines"

From ArchWiki
Jump to: navigation, search
m (add tag i18n)
(assorted style upgrades, didn't check update status)
Line 1: Line 1:
 
[[Category:Development (English)]]
 
[[Category:Development (English)]]
 
 
{{i18n|Eclipse plugin package guidelines}}
 
{{i18n|Eclipse plugin package guidelines}}
  
== Introduction ==
 
 
There are many ways to install working Eclipse plugins, especially since the introduction of the ''dropins'' directory in Eclipse 3.4, but some or them are messy, and having a standardized and consistent way of packaging is very important to lead to a clean system structure. It's not easy, however, to achieve this without the packager knowing every detail about how Eclipse plugins work. This page aims to define a standard and simple structure for Eclipse plugin PKGBUILDs, so that the filesystem structure can remain consistent between all plugins without having the packager to start again for every new package.
 
There are many ways to install working Eclipse plugins, especially since the introduction of the ''dropins'' directory in Eclipse 3.4, but some or them are messy, and having a standardized and consistent way of packaging is very important to lead to a clean system structure. It's not easy, however, to achieve this without the packager knowing every detail about how Eclipse plugins work. This page aims to define a standard and simple structure for Eclipse plugin PKGBUILDs, so that the filesystem structure can remain consistent between all plugins without having the packager to start again for every new package.
  
 
== Eclipse plugin structure and installation ==
 
== Eclipse plugin structure and installation ==
The typical Eclipse plugin contains two directories, ''features'' and ''plugins'', and since Eclipse 3.3 they could only be placed in ''/usr/share/eclipse/''. The content of these two directories could be mixed with that of other plugins, but it created a mess and rendered the structure difficult to manage. It was also very difficult to tell at a glance which package contained which file.
+
The typical Eclipse plugin contains two directories, {{filename|features}} and {{filename|plugins}}, and since Eclipse 3.3 they could only be placed in {{filename|/usr/share/eclipse/}}. The content of these two directories could be mixed with that of other plugins, and it created a mess and rendered the structure difficult to manage. It was also very difficult to tell at a glance which package contained which file.
  
This installation method is still supported in Eclipse 3.4, but the preferred one is now using the ''/usr/share/eclipse/dropins/'' directory. Inside this directory can live an unlimited number of subdirectories, each one containing its own ''features'' and ''plugins'' subdirectories. This allows to keep a tidy and clean structure, and should be the standard packaging way.
+
This installation method is still supported in Eclipse 3.4, but the preferred one is now using the {{filename|/usr/share/eclipse/dropins/}} directory. Inside this directory can live an unlimited number of subdirectories, each one containing its own {{filename|features}} and {{filename|plugins}} subdirectories. This allows to keep a tidy and clean structure, and should be the standard packaging way.
  
 
== Packaging ==
 
== Packaging ==
  
 
=== Sample PKGBUILD ===
 
=== Sample PKGBUILD ===
Here's an example, we'll detail how to customize it below.
+
Here is an example, we will detail how to customize it below.
  
 
  pkgname=eclipse-mylyn
 
  pkgname=eclipse-mylyn
Line 51: Line 49:
  
 
=== How to customize the build ===
 
=== How to customize the build ===
The main variable which needs to be customized is the ''pkgname''. If you are packaging a typical plugin, then this is the only thing you need to do: most plugins are distributed in zip files which only contain the two ''features'' and ''plugins'' subdirectories. So, if you're packaging the ''foo'' plugin and the source file only contains the ''features'' and ''plugins'', you just need to change ''pkgname'' to ''eclipse-foo'' and you're set.
+
The main variable which needs to be customized is the {{codeline|pkgname}}. If you are packaging a typical plugin, then this is the only thing you need to do: most plugins are distributed in zip files which only contain the two {{filename|features}} and {{filename|plugins}} subdirectories. So, if you are packaging the {{codeline|foo}} plugin and the source file only contains the {{filename|features}} and {{filename|plugins}}, you just need to change {{codeline|pkgname}} to {{codeline|eclipse-foo}} and you are set.
  
 
Read on to get to the internals of the PKGBUILD, which help to understand how to setup the build for all the other cases.
 
Read on to get to the internals of the PKGBUILD, which help to understand how to setup the build for all the other cases.
Line 58: Line 56:
  
 
==== Package naming ====
 
==== Package naming ====
Packages should be named eclipse-''pluginname'', so that they're recognizable as eclipse-related packages and it's easy to extract the plugin name with a simple shell substitution like ''${pkgname/eclipse-}'', not having to resort to an unneeded ''${_realname}'' variable. The plugin name is necessary to tidy up everything during installation and to avoid conflicts.
+
Packages should be named {{codeline|eclipse-''pluginname''}}, so that they are recognizable as eclipse-related packages and it is easy to extract the plugin name with a simple shell substitution like {{codeline|<nowiki>${pkgname/eclipse-}</nowiki>}}, not having to resort to an unneeded {{codeline|<nowiki>${_realname}</nowiki>}} variable. The plugin name is necessary to tidy up everything during installation and to avoid conflicts.
  
 
==== Files ====
 
==== Files ====
  
 
===== Extraction =====
 
===== Extraction =====
Some plugins need the features to be extracted from jar files. The ''jar'' utility, already included in the JRE, is used to do this. However, ''jar'' can't extract to directories other than the current one: this means that, after every directory creation, it's necessary to ''cd'' inside it before extracting. The ''${_dest}'' variable is used in this context to improve readability and PKGBUILD tidiness.
+
Some plugins need the features to be extracted from jar files. The {{codeline|jar}} utility, already included in the JRE, is used to do this. However, {{codeline|jar}} cannot extract to directories other than the current one: this means that, after every directory creation, it is necessary to {{codeline|cd}} inside it before extracting. The {{codeline|<nowiki>${_dest}</nowiki>}} variable is used in this context to improve readability and PKGBUILD tidiness.
  
 
===== Locations =====
 
===== Locations =====
Line 73: Line 71:
 
  /usr/share/eclipse/dropins/pluginname/eclipse/plugins/plugin2.jar
 
  /usr/share/eclipse/dropins/pluginname/eclipse/plugins/plugin2.jar
  
This structure allows for mixing different versions of libraries that may be needed by different plugins while being clear about which package owns what. It will also avoid conflicts in case different packages provide the same library. The only alternative would be splitting every package from its libraries, with all the extra fuss it requires, and it wouldn’t even be guaranteed to work because of packages needing older library versions.
+
This structure allows for mixing different versions of libraries that may be needed by different plugins while being clear about which package owns what. It will also avoid conflicts in case different packages provide the same library. The only alternative would be splitting every package from its libraries, with all the extra fuss it requires, and it would not even be guaranteed to work because of packages needing older library versions.
Features have to be unjarred since Eclipse won't detect them otherwise, and the whole plugin installation won’t work. This happens because Eclipse treats update sites and local installations differently (don't ask why, it just does).
+
Features have to be unjarred since Eclipse will not detect them otherwise, and the whole plugin installation will not work. This happens because Eclipse treats update sites and local installations differently (do not ask why, it just does).
  
 
==== The build() function ====
 
==== The build() function ====
First thing to be noticed is the ''cd ${srcdir}'' command. Usually source archives extract the ''features'' and ''plugins'' folders directly under ''${srcdir}'', but this is not always the case. Anyway, for most non-''(de facto)''-standard plugins this is the only line that needs to be changed.
+
First thing to be noticed is the {{codeline|<nowiki>cd ${srcdir}</nowiki>}} command. Usually source archives extract the {{filename|features}} and {{filename|plugins}} folders directly under {{codeline|<nowiki>${srcdir}</nowiki>}}, but this is not always the case. Anyway, for most non-''(de facto)''-standard plugins this is the only line that needs to be changed.
Next is the ''features'' section. It creates the necessary directories, one for every jar file, and extracts the jar in the corresponding directory. Similarly, the ''plugins'' section installs the jar files in their directory. A while cycle is used to prevent funny-named files.
+
Next is the {{codeline|features}} section. It creates the necessary directories, one for every jar file, and extracts the jar in the corresponding directory. Similarly, the {{codeline|plugins}} section installs the jar files in their directory. A while cycle is used to prevent funny-named files.

Revision as of 21:25, 10 October 2011

This template has only maintenance purposes. For linking to local translations please use interlanguage links, see Help:i18n#Interlanguage links.


Local languages: Català – Dansk – English – Español – Esperanto – Hrvatski – Indonesia – Italiano – Lietuviškai – Magyar – Nederlands – Norsk Bokmål – Polski – Português – Slovenský – Česky – Ελληνικά – Български – Русский – Српски – Українська – עברית – العربية – ไทย – 日本語 – 正體中文 – 简体中文 – 한국어


External languages (all articles in these languages should be moved to the external wiki): Deutsch – Français – Română – Suomi – Svenska – Tiếng Việt – Türkçe – فارسی

There are many ways to install working Eclipse plugins, especially since the introduction of the dropins directory in Eclipse 3.4, but some or them are messy, and having a standardized and consistent way of packaging is very important to lead to a clean system structure. It's not easy, however, to achieve this without the packager knowing every detail about how Eclipse plugins work. This page aims to define a standard and simple structure for Eclipse plugin PKGBUILDs, so that the filesystem structure can remain consistent between all plugins without having the packager to start again for every new package.

Eclipse plugin structure and installation

The typical Eclipse plugin contains two directories, Template:Filename and Template:Filename, and since Eclipse 3.3 they could only be placed in Template:Filename. The content of these two directories could be mixed with that of other plugins, and it created a mess and rendered the structure difficult to manage. It was also very difficult to tell at a glance which package contained which file.

This installation method is still supported in Eclipse 3.4, but the preferred one is now using the Template:Filename directory. Inside this directory can live an unlimited number of subdirectories, each one containing its own Template:Filename and Template:Filename subdirectories. This allows to keep a tidy and clean structure, and should be the standard packaging way.

Packaging

Sample PKGBUILD

Here is an example, we will detail how to customize it below.

pkgname=eclipse-mylyn
pkgver=3.0.3
pkgrel=1
pkgdesc="A task-focused interface for Eclipse"
arch=('i686' 'x86_64')
url="http://www.eclipse.org/mylyn/"
license=('EPL')
depends=('eclipse')
optdepends=('bugzilla: ticketing support')
source=(http://download.eclipse.org/tools/mylyn/update/mylyn-${pkgver}-e3.4.zip)
md5sums=('e98cd7ab3c5d5aeb7c32845844f85c22')

build() {
  _dest=${pkgdir}/usr/share/eclipse/dropins/${pkgname/eclipse-}/eclipse

  cd ${srcdir}

  # Features
  find features -type f | while read _feature ; do
    if [[ ${_feature} =~ (.*\.jar$) ]] ; then
      install -dm755 ${_dest}/${_feature%*.jar}
      cd ${_dest}/${_feature/.jar}
      jar xf ${srcdir}/${_feature} || return 1
    else
      install -Dm644 ${_feature} ${_dest}/${_feature}
    fi
  done

  # Plugins
  find plugins -type f | while read _plugin ; do
    install -Dm644 ${_plugin} ${_dest}/${_plugin}
  done
}

How to customize the build

The main variable which needs to be customized is the Template:Codeline. If you are packaging a typical plugin, then this is the only thing you need to do: most plugins are distributed in zip files which only contain the two Template:Filename and Template:Filename subdirectories. So, if you are packaging the Template:Codeline plugin and the source file only contains the Template:Filename and Template:Filename, you just need to change Template:Codeline to Template:Codeline and you are set.

Read on to get to the internals of the PKGBUILD, which help to understand how to setup the build for all the other cases.

In-depth PKGBUILD review

Package naming

Packages should be named Template:Codeline, so that they are recognizable as eclipse-related packages and it is easy to extract the plugin name with a simple shell substitution like Template:Codeline, not having to resort to an unneeded Template:Codeline variable. The plugin name is necessary to tidy up everything during installation and to avoid conflicts.

Files

Extraction

Some plugins need the features to be extracted from jar files. The Template:Codeline utility, already included in the JRE, is used to do this. However, Template:Codeline cannot extract to directories other than the current one: this means that, after every directory creation, it is necessary to Template:Codeline inside it before extracting. The Template:Codeline variable is used in this context to improve readability and PKGBUILD tidiness.

Locations

As we said, source archives provide two directories, features and plugins, each one packed up with jar files. The preferred dropins structure should look like this:

/usr/share/eclipse/dropins/pluginname/eclipse/features/feature1/...
/usr/share/eclipse/dropins/pluginname/eclipse/features/feature2/...
/usr/share/eclipse/dropins/pluginname/eclipse/plugins/plugin1.jar
/usr/share/eclipse/dropins/pluginname/eclipse/plugins/plugin2.jar

This structure allows for mixing different versions of libraries that may be needed by different plugins while being clear about which package owns what. It will also avoid conflicts in case different packages provide the same library. The only alternative would be splitting every package from its libraries, with all the extra fuss it requires, and it would not even be guaranteed to work because of packages needing older library versions. Features have to be unjarred since Eclipse will not detect them otherwise, and the whole plugin installation will not work. This happens because Eclipse treats update sites and local installations differently (do not ask why, it just does).

The build() function

First thing to be noticed is the Template:Codeline command. Usually source archives extract the Template:Filename and Template:Filename folders directly under Template:Codeline, but this is not always the case. Anyway, for most non-(de facto)-standard plugins this is the only line that needs to be changed. Next is the Template:Codeline section. It creates the necessary directories, one for every jar file, and extracts the jar in the corresponding directory. Similarly, the Template:Codeline section installs the jar files in their directory. A while cycle is used to prevent funny-named files.