Última modificación 15:20 Viernes 18 de Junio de 2004
Los productos basados en Eclipse deben instalarse correctamente en el sistema del usuario final. Con frecuencia de utilizan herramientas de empaquetado con objetivos especiales, como por ejemplo InstallShield y RPM, para construir las instaladores ejecutables que automatizan la instalación, actualización y desinstalación. Esta nota describe cómo escribir un instalador para un producto basado en Eclipse, y para ampliaciones de productos Eclipse instalables por separado.
Se presupone que existen un equipo de desarrollo del producto responsable de suministrar los ingredientes originales que deberán dirigirse a los sistemas de los usuarios finales empaquetados como instalador ejecutable. La creación de instaladores ejecutables se especifica en script, al igual que las acciones de instalación necesarias para interactuar con el usuario final y los archivos de repositorio de su sistema. Esta nota describe con detalle lo que estos instaladores deben hacer y cómo deben funcionar.
Esta nota debe considerarse como una receta destinada a la persona responsable de escribir un instalador para productos basados en Eclipse. Existen dos buenas razones para recomendar a todos los que escriben instaladores que sigan nuestra receta:
Un instalador de producto debe estar autocontenido - el tipo de información que puede distribuirse en un CD e instalarse en cualquier máquina con un sistema operativo adecuado.
Eclipse requiere un Entorno de tiempo de ejecución Java (JRE) Java2 para ejecutar código Java. Los JRE son software bajo licencia que se obtiene de los distribuidores de Java. Si dispone de una licencia para redistribuir un JRE de un distribuidor de JRE, una empresa puede incluir un JRE en su producto e instalarlo en el sistema del usuario final al mismo tiempo que el producto. La alternativa consiste en que un JRE esté preinstalado en el sistema del usuario final, y asociarlo al producto en el momento de la instalación. De una forma u otra, un producto basado en Eclipse necesita un JRE adecuado, y el instalador del producto debe jugar un papel en la instalación de un JRE o en la localización y enlace a un JRE preexistente.
Supongamos que debe instalarse un JRE con el producto. Un directorio que contenga el
JRE representa una entrada del script de creación del instalador. Llame a este directorio
<JRE>. Este directorio debe tener una estructura de directorio JRE estándar,
con el ejecutable Java ubicado en jre/bin/java.exe
y la biblioteca de clases
en jre/lib/rt.jar
debajo del directorio <JRE>.
Como referencia, la estructura fundamental de este directorio es la siguiente:
<JRE>/
jre/
bin/
java.exe
lib/
rt.jar
Existen archivos (y subdirectorios) adicionales en estos directorios; sólo hemos mostrado un ejemplo para proporcionar la estructura general. Los nombres que aparecen en cursiva son específicos de producto.
La segunda entrada del script de creación del instalador es un directorio,
<product head
>, que contiene el lanzador ejecutable específico
del producto y los archivos no relacionados con Eclipse. Como referencia, la estructura
fundamental de este directorio es la siguiente (las cursivas indican nombres de archivo
que variarán en función del producto):
<product head>/
La tercera entrada del script de creación del instalador es un directorio,
<
acmeproduct.exe
product body
>, que contiene las características y conectores
desarrollados para el producto.
Como referencia, la estructura fundamental de este directorio es la siguiente:
<product body>/
eclipse/
features/
com.example.acme.acmefeature_1.0.0/
feature.xml
com.example.acme.otherfeature_1.0.0/
feature.xml
plugins/
com.example.acme.acmefeature_1.0.0/
plugin.xml
about.ini
about.properties
about.mappings
plugin_customization.ini
splash.bmp
com.example.acme.otherfeature_1.0.0/
plugin.xml
about.ini
about.properties
about.mappings
com.example.acme.myplugin_1.0.0/
plugin.xml
myplugin.jar
com.example.acme.otherplugin_1.0.0/
plugin.xml
otherplugin.jar
La cuarta entrada del script de creación del instalador es un directorio,
<platform
>, que contiene las características y conectores
de la propia plataforma Eclipse y las herramientas de terceros que se incluyan.
Este
directorio también incluye el lanzador ejecutable Eclipse estándar,
eclipse.exe
, (denominado eclipse
en el sistema operativo Unix),
su compañero startup.jar
y los archivos de la plataforma Eclipse que deben figurar en la raíz de la instalación.
Como referencia, la estructura fundamental de este directorio es la siguiente:
<platform>
El contenido exacto de los directorios de entrada <
eclipse/
eclipse.exe
startup.jar
features/
org.eclipse.platform_2.0.0/
org.eclipse.platform.win32_2.0.0/
org.eclipse.jdt_2.0.0/
org.eclipse.pde_2.0.0/
plugins/
org.eclipse.platform_2.0.0/
org.eclipse.core.runtime_2.0.0/
org.eclipse.core.boot_2.0.0/
org.eclipse.core.resources_2.0.0/
org.eclipse.ui_2.0.0/
org.eclipse.jdt_2.0.0/
org.eclipse.jdt.core_2.0.0/
org.eclipse.jdt.ui_2.0.0/
org.eclipse.pde_2.0.0/
org.eclipse.pde.core_2.0.0/
org.eclipse.pde.ui_2.0.0/
(más directorios de conector org.eclipse.*)
JRE
>,
<product head
>, <product body
> y
<platform
> determina qué archivos se instalarán finalmente en
el sistema del usuario final.
Las últimas entradas del script de creación del instalador son las series de ID y
versión de la característica primaria del producto; por ejemplo,
"com.example.acme.acmefeature"
y
"1.0.0
"; y el nombre del ejecutable del producto, por
ejemplo, "acmeproduct
.exe
".
Para los productos que no requieren su propio ejecutable de producto, será la vía de
acceso del lanzador de ejecutable Eclipse estándar
"eclipse/eclipse.exe
".
Estas series tienen una importancia especial para el instalador, ya que aparecen en los
nombres de archivo y directorio y en el contenido de los archivos de
marcador creados durante la instalación.
Durante la instalación, el instalador debe comportarse de forma estándar (en la lista de pasos se indican más detalles):
Si la ubicación especificada en el paso 5 es <install
>, el
instalador copia todos los archivos de los directorios <JRE
>,
<platform>,
<product
> y
<product plug-ins>
en <install
>.
Archivo de entrada | Archivo instalado |
<JRE>/* |
<install>/eclipse/* |
<product head>/* |
<install>/* |
<product body>/* |
<install>/* |
<platform>/* |
<install>/* |
El archivo de marcador creado en el paso 8 es <install>/eclipse/.eclipseproduct
y se utiliza para marcar
un directorio en el que se ha instalado un producto basado en Eclipse, principalmente
para que lo localicen los instaladores de ampliaciones. Este archivo de marcador es un
archivo de formato
java.io.Properties
(codificación de caracteres ISO 8859-1 con carácter de escape "\") y contiene
la siguiente información que identifica el producto de cara al usuario y distingue entre
sí los productos basados en Eclipse:
name=Acme Visual Tools Pro
id=com.example.acme.acmefeature
version=1.0.0
Los valores de las propiedades de "ID" y "versión" son entradas del script de creación del instalador; probablemente, el nombre del producto es conocido y está codificado por programa. (Generalmente, los productos no accederán a este archivo de marcador; sólo los instaladores de producto y ampliación lo escriben o leen).
El paso 6 requiere la comprobación de un archivo
<install>/eclipse/.eclipseproduct
o
<install>/eclipse/.eclipseextension
existente. Un producto no
puede instalarse exactamente en el mismo lugar que otro producto o ampliación.
Después de instalar todos los archivos, la estructura de nivel más alto del directorio de instalación contendrá los siguientes archivos y subdirectorios (y quizás otros):
<install>/
Si un instalador de producto solicita información de licencia del usuario, como
por ejemplo el nombre del propietario registrado y la clave de licencia, esta información
debe suministrarse en el diálogo "about" (Acerca de) del producto (paso 10).
acmeproduct.exe
eclipse/
.eclipseproduct
eclipse.exe
startup.jar
features/
plugins/
jre/
Esta operación se realiza registrando las respuestas del usuario en el archivo
"about.mapping
" en el conector de la característica primaria. Por
ejemplo, en
<install>/plugins/com.example.acme.acmefeature_1.0.0/about.mapping
.
El archivo "about.mapping
" puede preexistir en la entrada
<product head
> o puede ser necesario que el instalador lo cree
durante la instalación.
Las claves son números; el valor de la clave "n" se sustituye por la
subserie "{n}
" en la propiedad "aboutText
".
Por ejemplo, si una clave de licencia tiene el número de campo 0, debe crearse un archivo
"about.mapping
" que contenga una línea, como por ejemplo
"0=T42-24T-ME4U-U4ME
".
N.B.
El archivo "about.mapping
" es un archivo de formato
java.io.Properties
( codificación de caracteres ISO 8859-1 con el carácter de escape "\").
Si la codificación de caracteres nativa durante la instalación es diferente de ISO
8859-1, el instalador es responsable de convertir la codificación de caracteres nativa a
Unicode y de añadir caracteres de escape "\" cuando sea necesario. Los
caracteres de escape son necesarios cuando las series contienen caracteres especiales
(como por ejemplo "\") o caracteres no latinos. Por ejemplo, el campo número 1
que contiene las tres primeras letras del alfabeto griego se escribiría
"1=\u03B1\u03B2\u03B3
".
En el paso 12, el instalador del producto lanza el ejecutable del producto,
<install>/acmeproduct.exe
, con la opción
especial -initialize [detalles exactos TBD]. Esto provoca que la plataforma Eclipse
realice de forma silenciosa todo el proceso de primera vez, que consume tiempo, y
almacene en antememoria los resultados, para que, cuando el usuario inicie el producto,
éste aparezca en un estado preparado para la gestión.
Durante la desinstalación, el desinstalador debe comportarse de forma estándar:
install
>, y todos los
archivos de <install
>/eclipse/features
e <install
>/eclipse/plugins
, incluyendo los
que han sido colocados por terceros que no son este instalador (por ejemplo,
por el gestor de actualización de Eclipse)Cuando el producto se ha desinstalado, deben suprimirse los archivos depositados
durante la instalación, junto con las características actualizadas y los
conectores creados por el gestor de actualización de Eclipse. Importante: durante
la desinstalación, puede haber otros directorios y archivos en el directorio
<install>
, especialmente
<install>/eclipse/workspace/
,
<install>/eclipse/links/
e
<install>/eclipse/configuration/
, que contienen datos importantes
que deben conservarse cuando se desinstala el producto. El usuario debe estar en
condiciones de desinstalar y reinstalar un producto en la misma ubicación sin perder datos
importantes.
Cuando el producto ya está instalado en el sistema del usuario, el instalador debe permitir la aplicación de una actualización de servicio o de versión al producto instalado.
Durante la instalación, el instalador debe comportarse de forma estándar:
En el paso 2, un producto desinstalado puede reconocerse por la presencia de un
directorio "eclipse
" que contiene de forma inmediata un archivo
denominado ".eclipseproduct
".
El padre del directorio "eclipse
" es el directorio de instalación
de un producto, es decir, <install>/eclipse/.eclipseproduct
.
La información contenida en este archivo de marcador debe mostrarse al usuario para que
confirme que se está actualizando el producto correcto (puede haber varios productos
basados en Eclipse en el sistema del usuario).
El instalador debe realizar comprobaciones de compatibilidad en el paso 3 mediante
comparación de patrones simples con los subdirectorios del directorio
<install>/eclipse/features
. Por ejemplo, la presencia de una
carpeta que coincide con
"com.example.acme.otherfeature_1.0.1
" asegurará que
se ha aplicado una actualización de servicio determinada al producto instalado.
En el paso 7, el instalador puede suprimir o sustituir cualquiera de los archivos que
ha instalado originalmente y añadir más archivos. Importante: varios archivos y
directorios, incluyendo <install>/eclipse/workspace/
, <install>/eclipse/configuration
, pueden ubicarse conjuntamente
con la instalación y contener archivos de datos importantes que deben conservarse cuando
se actualiza el producto.
En situaciones de actualización, existen muchas posibilidades de que la mayoría de los
archivos situado debajo de <install>/eclipse/plugins/
sean los
mismos (al igual que en el caso de <install>/eclipse/features/
).
Existe una oportunidad significativa de optimización en
<install>/eclipse/plugins/
, dado que el nombre de
subdirectorio, que intercala el número de versión del conector (o fragmento), cambia si y
sólo si cambia alguno de los archivo situados por debajo de él. En otras palabras, no
es necesario modificar ningún archivo de
<install>/eclipse/plugins/org.eclipse.ui_2.0.0
/ si este
subdirectorio también debe existir después de la actualización; si alguno de los archivos
del conector debe cambiar, el número de versión del conector se revisa, provocando que
los archivos del conector actualizado se instalen en un directorio paralelo,
<install>/eclipse/plugins/org.eclipse.ui_2.0.1
/.
Se espera que el JRE se encuentre en <install>/eclipse/jre/bin/javaw.exe
.
Si se encuentra en otro lugar, debe especificarse la vía de acceso absoluta mediante la
opción -vm
en la línea de mandatos; por ejemplo, -vm C:\j2jre1.3.0\jre\bin\javaw.exe
.
En este caso, el instalador debe añadir esta opción a la línea de mandatos del acceso
directo de escritorio que crea.
Entendemos por ampliación un conjunto de características instalables por separado y sus conectores que pueden asociarse con, y utilizarse desde, uno o más productos basados en Eclipse instalados en el mismo sistema. Al contrario que un producto, una ampliación no está autocontenida; no incluye un ejecutable de producto, la plataforma Eclipse ni un JRE.
Sin tener en cuenta casos especiales, se presupone que una ampliación consta de una
sola característica. La primer entrada del script de creación del instalador es un
directorio, <extension
>, que contiene su característica y
conectores. Presuponemos que una ampliación no tiene archivos relacionados con Eclipse;
si los tiene, estarían en <extension>/
y no en <extension>/eclipse/
.
Como referencia, la estructura fundamental de este directorio es la siguiente:
<extension>/
eclipse/
features/
com.example.wiley.anvilfeature_1.0.0/
feature.xml
plugins/
com.example.wiley.anvilfeature_1.0.0/
plugin.xml
about.ini
about.properties
about.mappings
com.example.wiley.mainplugin_1.0.0/
com.example.wiley.otherplugin_1.0.0/
El contenido exacto del directorio de entrada <extension
>
determina qué archivos se instalarán finalmente en el sistema del usuario final.
Las últimas entradas del script de creación del instalador son las series de ID y
versión de la característica de la ampliación; por ejemplo,
"com.example.wiley.anvil
"
y "1.0.0
". Estas series tienen una importancia especial para el instalador, ya que aparecen en los
nombres de archivo y directorio y en el contenido de los archivos de
marcador creados durante la instalación.
En la mayoría de los aspectos, un instalador de ampliación es similar a un instalador de producto. A continuación se indican las áreas en las que se diferencian:
Durante la instalación, el instalador se comporta de forma estándar:
Si la ubicación especificada en el paso 5 es <install
>, el
instalador copia todos los archivos del directorio <extension>
en <install
> en el paso 11.
Archivo de entrada | Archivo instalado |
<extension>/* |
<install>/* |
En el paso 7, cualquier producto Eclipse puede ser candidato. Un producto basado en
Eclipse puede reconocerse por la presencia de un archivo <product install>/eclipse/.eclipseproduct
; el usuario debe poder solicitar una
búsqueda en disco limitada para los productos instalados (un botón "buscar
productos instalados") o desplazarse a un directorio que contenga un producto (es
decir, un botón "examinar").
El instalador debe realizar comprobaciones de compatibilidad en el paso 8 mediante
comparación de patrones simples con los subdirectorios del
directorio <install>/eclipse/features
. Por ejemplo, la
presencia de una carpeta que
coincide con "org.eclipse.jdt_2.*
" significa que JDT se incluye en
el producto instalado.
El archivo de marcador creado en el
paso 10 es <install>/
.eclipseextension
y se
utiliza para marcar un directorio en el que se ha instalado una ampliación basada
en
Eclipse, principalmente para que la localicen los instaladores de ampliaciones
(análogo al archivo de marcador .eclipseproduct
de un producto). Este
archivo de marcador es un archivo de formato
java.io.Properties
(codificación de caracteres ISO 8859-1 con carácter de escape "\") y contiene
la siguiente información que identifica la ampliación de cara al usuario y
distingue entre
sí las ampliaciones basadas en Eclipse:
name=Wiley Anvil Enterprise Edition
id=com.example.wiley.anvilfeature
version=1.0.0
Los valores de las propiedades de "ID" y "versión" son entradas del script de creación del instalador; probablemente, el nombre de la ampliación es conocido y está codificado por programa. (Generalmente, los productos no accederán a este archivo de marcador; sólo los instaladores de producto y ampliación lo escriben o leen).
Después de instalar todos los archivos, la estructura de nivel más alto del directorio de instalación contendrá los siguientes archivos y subdirectorios:
<install>/
eclipse/
.eclipseextension
features/
plugins/
La única diferencia significativa con respecto a un instalador de producto consiste en que un instalador de ampliación también crea archivos de enlace en otros productos basados en Eclipse ya instalados en el sistema del usuario. (Con ello, el usuario no tiene que asociar manualmente la ampliación nueva desde el interior de cada producto mediante el gestor de actualización de Eclipse).
El archivo de enlace creado en el paso 14 es <product install>/eclipse/links/com.example.wiley.anvilfeature.link
;
es decir, el archivo tiene el mismo nombre que el directorio de característica de
ampliación menos el sufijo del número de versión. Un archivo de enlace es un archivo de
formato
java.io.Properties
(codificación de caracteres ISO 8859-1 con el carácter de escape "\").
La clave es "path" y el valor es la vía de acceso absoluta de la ampliación
instalada, <install>
; por ejemplo, una entrada puede ser "path=C:\\Program Files\\Wiley\\Anvil
".
El instalador es responsable de convertir la codificación de caracteres nativa a
Unicode y de añadir caracteres de escape "\" cuando sea necesario. Generalmente,
los caracteres de escape son necesarios, ya que <install>
contiene generalmente caracteres especiales (como por ejemplo "\") y puede
hacer mención a directorios con caracteres no latinos en los nombres. El producto lee los
archivos de enlace cuando se inicia. El instalar mantiene un registro de los archivos de
enlace que crea, para que puedan localizarse cuando se actualice o desinstale la
ampliación.
Durante la instalación, el desinstalador debe comportarse de forma estándar:
install
>, y todos los
archivos de <install
>/eclipse/features
e <install
>/eclipse/plugins
, incluyendo los
que han sido colocados por terceros que no son este instalador (por ejemplo,
por el gestor de actualización de Eclipse)Cuando se desinstala una ampliación, todos los archivos de conector y característica deben suprimirse; no existen archivos de datos importantes que deban conservarse en estos subdirectorios. Esto permite al usuario desinstalar una ampliación por completo, incluyendo las actualizaciones aplicadas por el gestor de actualización de Eclipse.
Cuando la ampliación ya está instalada en el sistema del usuario, el instalador debe permitir la aplicación de una actualización de servicio o de versión a la ampliación instalada.
Durante la instalación, el instalador debe comportarse de forma estándar:
En el paso 2, una ampliación desinstalada puede reconocerse por la presencia
de un directorio "eclipse
" que contiene de forma inmediata un
archivo denominado ".eclipseextension
".
El padre del directorio "eclipse
" es el directorio de
instalación
de una ampliación, es decir,
<install>/eclipse/.eclipseextension
.
La información contenida en este archivo de marcador debe mostrarse al usuario para que
confirme que se está actualizando la ampliación correcta (puede haber varias
ampliaciones basadas en Eclipse en el sistema del usuario).
En el paso 7, el instalador no debe suprimir ni sobreescribir ninguno de los archivos
que ha instalado originariamente; en lugar de ello, sólo debe añadir los archivos de
nuevas versiones de características y conectores, y posiblemente volver a escribir el
archivo de marcador <install>/eclipse/.eclipseextension
. Conservar
las versiones anteriores proporciona al usuario la opción de restituir la actualización.
Al igual que al actualizar una instalación de producto, no es necesario modificar ningún
archivo de <install>/eclipse/plugins/com.example.wiley.otherplugin_1.0.0
/
si este subdirectorio también debe existir después de la actualización; si alguno de los
archivo de conector debe cambiarse, el número de versión del conector se revisa,
provocando que los archivos del conector actualizado se instalen en un directorio
paralelo, <install>/eclipse/plugins/com.example.wiley.otherplugin_1.0.1
/.