Modificado pela última vez às 15:20, sexta-feira, dia 18 de Junho, 2004
Os produtos baseados no Eclipse devem ser correctamente instalados no computador do utilizador final. As ferramentas de colocação em pacote e instalar ferramentas com objectos especiais, como o InstallShield e RPM, são muitas vezes utilizadas para construir instaladores executáveis que automatizam a instalação, actualização e desinstalação. Esta nota descreve como escrever um instalador para um produto baseado no Eclipse, e para extensões instaláveis separadamente em produtos baseados no Eclipse.
Parte-se do princípio que uma equipa de desenvolvimento de um produto é responsável por fornecer ingredientes primitivos que terão de encontrar o modo de ser colocados em pacote e instalados nos computadores dos utilizadores finais como um instalador executável. A criação de instaladores executáveis é especifica em script, tal como as acções de tempo de instalação necessárias para interagir com o utilizador final e os ficheiros de depósitos no respectivo computador. Esta nota descreve em detalhe o que os instaladores devem fazer e como deverão funcionar.
Esta nota deverá ser criada como uma receita para a pessoa responsável por escrever um instalador para um produto baseado no Eclipse. As duas razões por que recomendamos a todos os programadores de instaladores que sigam as nossas directrizes:
Um instalador de produto deve estar contido em si próprio, o tipo de opção que pode ser distribuída num CD e instalada em qualquer máquina com um sistema operativo adequado.
O Eclipse requer um Java2 Java Runtime Environment (JRE) para executar o código Java. Os JREs são software licenciado, obtido a partir dos fornecedores Java. Com uma licença para redistribuir um JRE de um fornecedor de JRE, uma empresa pode incluir um JRE neste produto, e instalá-lo no computador do utilizador final, ao mesmo tempo que instala o produto. A alternativa é a necessidade de ter um JRE pré-instalado no computador do utilizador final, e associado ao momento de instalação do produto. De um modo ou de outro, o produto baseado no Eclipse requer um JRE adequado, e o instalador do produto tem de actuar quer na instalação de um JRE quer na localização e ligação a um JRE pré-existente.
Parta do princípio que será instalado um JRE com o produto. Um directório que contém o JRE é a entrada do script de criação do instalador. Chame este directório <JRE>. Este directório tem de ter uma estrutura de directório de JRE standard, com o executável Java localizado em jre/bin/java.exe
, e a biblioteca de classes em jre/lib/rt.jar
abaixo do directório de <JRE>.
Como referência, a estrutura fundamental deste directório é semelhante a:
<JRE>/
jre/
bin/
java.exe
lib/
rt.jar
Existem ficheiros adicionais (e sub-directórios) nestes directórios; mostrámos apenas um exemplo para dar uma estrutura geral. Os nomes em itálico são específicos do produto.
A segunda entrada no script de criação do instalador é um directório, <product head
>, que contém o lançador executável específico do produto, e quaisquer ficheiros não relacionados com o Elipse. Como referência, a estrutura fundamental deste directório seria semelhante a (o itálico indicam nome de ficheiros que irão variar de produto para produto):
<product head>/
A terceira entrada do script de criação do instalador é um directório, <
acmeproduct.exe
product body
>, que contém as funções e conectores desenvolvidos para o produto. Como referência, a estrutura fundamental deste directório seria semelhante a:
<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
A quarta entrada do script de criação do instalador é um directório, <platform
>, que contém as funções e conectores para a própria plataforma Eclipse, e quaisquer ferramentas de terceiros incluídas.
Este directório também inclui o lançador executável do Eclipse standard, eclipse.exe
, (chamado eclipse
no ambiente operativo Unic), o seu companheiro startup.jar
e quaisquer outros ficheiros do Eclipse necessários como a raiz da instalação. Como referência, a estrutura fundamental deste directório seria semelhante a:
<platform>
O conteúdo exacto dos directórios de entrada do <
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/
(more org.eclipse.* plug-in directories)
JRE
>, <product head
>, <product body
> e <platform
> determina quais os ficheiros que serão, por fim, instalados no computador do utilizador final.
As entradas finais do script de criação do instalador são cadeias de id e versão para a função principal do produto; por exemplo, "com.example.acme.acmefeature"
e "1.0.0
"; e o nome do executável do produto, por exemplo "acmeproduct
.exe
".
Para produtos que não requerem o seu próprio executável do produto, este deve ser o caminho para o lançador do executável do Eclipse standard "eclipse/eclipse.exe
".
Estas cadeias têm um significado especial para o instalador, aparecendo nos nomes de ficheiros e directórios, e no conteúdo dos ficheiros do marcador criados no momento da instalação.
No momento da instalação, o instalador deve comportar-se segundo o modo padrão (a seguir à lista de passos, encontrará mais detalhes):
Se a localização especificada no passo 5 for <install
>, o instalador copia todos os ficheiros nos directórios do <JRE
>, <platform>,
<product
>, e <product plug-ins>
em <install
>.
Ficheiro de entrada | Ficheiro instalado |
<JRE>/* |
<install>/eclipse/* |
<product head>/* |
<install>/* |
<product body>/* |
<install>/* |
<platform>/* |
<install>/* |
O ficheiro do marcador criado no passo 8, <install>/eclipse/.eclipseproduct
, é utilizado para marcar um directório no qual foi instalado um produto baseado no Eclipse, principalmente para os instaladores de extensão localizarem. Este ficheiro de marcador é um ficheiro de formato java.io.Properties (codificação de caracteres ISO 8859-1 com carácter de escape "\") e contém as informações seguintes que identificam o produto perante o utilizador e distingue um produto baseado no Eclipse do outro:
name=Acme Visual Tools Pro
id=com.example.acme.acmefeature
version=1.0.0
Os valores das propriedades "id" e "version" são entradas no script de criação do instalador; provavelmente, o nome do produto é conhecido e está codificado por programa. (Os produtos não iriam aceder normalmente a este ficheiro de marcador; apenas os instaladores de produto e extensão o gravam ou lêem.)
O passo 6 requer a verificação de um ficheiro <install>/eclipse/.eclipseproduct
ou <install>/eclipse/.eclipseextension
existente. Um produto não pode ser instalado exactamente na mesma localização de outro produto ou extensão.
Após instalar todos os ficheiros, a estrutura de nível superior do directório de instalação iria conter os seguintes ficheiros e sub-directórios (e talvez outros):
<install>/
Se um instalador do produto solicitar informações de licença a um utilizador, como o nome do proprietário registado e a chave de licença, esta informação deveria aparecer na caixa de diálogo "about" do produto (passo 10).
acmeproduct.exe
eclipse/
.eclipseproduct
eclipse.exe
startup.jar
features/
plugins/
jre/
Isto faz-se através do registo das resposta do utilizador no ficheiro "about.mapping
" no conector da função principal. Por exemplo, em <install>/plugins/com.example.acme.acmefeature_1.0.0/about.mapping
.
O ficheiro "about.mapping
" pode existir previamente na entrada <product head
>, ou poderá ser necessário que o instalador o crie no momento da instalação.
As chaves são números; o valor da chave "n" é substituído pela sub-cadeia "{n}
" na propriedade "aboutText
".
Por exemplo, se uma chave de licença fosse o número de campo 0, deveria ser criado um ficheiro "about.mapping
" contendo uma linha semelhante a "0=T42-24T-ME4U-U4ME
".
N.B.
O ficheiro "about.mapping
" é um ficheiro de formato java.io.Properties (codificação de caracteres ISO 8859-1 com carácter de escape "\").
Quando a codificação de caracteres original no momento da instalação é diferente de ISO 8859-1, o instalador é responsável pela conversão da codificação de caracteres original para Unicode, ou por adicionar caracteres de escape "\" onde seja necessário. Os caracteres de escape são necessários quando as cadeias contêm caracteres especiais (como "\") ou caracteres que não sejam do latim. Por exemplo, o número de campo 1 que contém as três primeiras letra do alfabeto grego escrever-se-ia como "1=\u03B1\u03B2\u03B3
".
No passo 12, o instalador do produto lança o ficheiro executável do produto, <install>/acmeproduct.exe
, com a opção -initialize especial [detalhes exactos de TBD]. Isto faz com que a plataforma Eclipse execute calmamente todo o processado de primeira vez que consome mais tempo e guarda os resultados na memória cache, de modo a que quando o utilizador iniciar o produto este aparece de imediato num estado preparado.
No momento da desinstalação, o desinstalador deverá comportar-se de modo padrão:
instalação
>, e todos os ficheiros em <install
>/eclipse/features
e <install
>/eclipse/plugins
incluindo aqueles colocados por terceiros, que não este instalador (por exemplo, o gestor de actualizações do Eclipse). Quando o produto é desinstalado, os ficheiros depositados no momento da execução serão eliminados, juntamente com as funções actualizadas e os conectores criados pelo gestor de actualizações do Eclipse. Importante: no momento da desinstalação, podem existir outros directórios e ficheiros no directório <install>
, especialmente <install>/eclipse/workspace/
, <install>/eclipse/links/
e <install>/eclipse/configuration/
, que podem conter dados importantes que devem ser retidos quando o produto é desinstalado. O utilizador deverá poder desinstalar e instalar novamente na mesma localização sem perder dados importantes.
Quando o produto já está instalado no computador do utilizador, o instalador deverá permite uma actualização do serviço ou da versão a aplicar ao produto instalado.
No momento da instalação, o instalador deverá comportar-se de modo padrão:
No passo 2, um produto instalado pode ser reconhecido pela presença de um directório "eclipse
", de imediato, que contém um ficheiro chamado ".eclipseproduct
".
O ascendente do directório "eclipse
" é um directório de instalação do produto, isto é, <install>/eclipse/.eclipseproduct
.
A informação contida dentro deste ficheiro de marcador deverá ser mostrado ao utilizador para a confirmação de que está a ser actualizado o produto correcto (podem existir vários produtos baseados no Eclipse no computador do utilizador).
O instalador deverá executar verificações de compatibilidade no passo 3 através de correspondência de padrão simples contra os sub-directórios no directório <install>/eclipse/features
. Por exemplo, a presença de uma pasta correspondente "com.example.acme.otherfeature_1.0.1
" iria assegurar que uma determinada actualização do serviço fora aplicada ao produto instalado.
Para o passo 7, o instalador poderá eliminar ou substituir qualquer um dos ficheiros que instalou originalmente, e adicionar mais ficheiros. Importante: vários ficheiros e directórios, incluindo <install>/eclipse/workspace/
, <install>/eclipse/configuration
, podem estar localizados em conjunto e conter ficheiros de dados importantes, que devem ser retidos quando o produto é actualizado.
Em situações de actualização, existem boas hipóteses de que a maior parte do ficheiros seguintes <install>/eclipse/plugins/
sejam iguais (o mesmo acontece com <install>/eclipse/features/
).
Existe uma oportunidade significativa de optimização em <install>/eclipse/plugins/
, uma vez que o nome do sub-directório incorpora o número de versão do conector (ou fragmento), altera-o apenas se nenhum dos ficheiros abaixo deste for alterado. Por outras palavras, não é necessário tocar em nenhum dos ficheiros em <install>/eclipse/plugins/org.eclipse.ui_2.0.0
/ se este sub-directório também existir após a actualização; se qualquer um dos ficheiros do conector fosse alterado, o número de versão do conector seria revisto, fazendo com que os ficheiros para o conector actualizado fossem instalados num directório paralelo <install>/eclipse/plugins/org.eclipse.ui_2.0.1
/.
Espera-se que o JRE esteja localizado em <install>/eclipse/jre/bin/javaw.exe
.
Se estiver localizado noutro lado, o caminho absoluto deverá ser especificado utilizando a opção -vm
na linha de comandos, por exemplo, -vm C:\j2jre1.3.0\jre\bin\javaw.exe
.
Em qualquer dos casos, o instalador deverá adicionar esta opção à linha de comandos do atalho da área de trabalho que cria.
Por extensão entende-se um conjunto de funções instalável separadamente e os conectores que podem associar-se, e que podem ser utilizados por um ou mais produtos baseados no Eclipse instalados no mesmo computador. Em contraste com um produto, uma extensão não está contida dentro de si própria; uma extensão não inclui um produto executável, a plataforma Eclipse, um JRE.
Sem ter em conta os casos gerais, parta do princípio que uma extensão consiste numa função única. A primeira entrada no script de criação do instalador é um directório, <extension
>, que contém as respectivas funções e conectores. Parte-se do princípio que uma extensão não tem quaisquer ficheiros relacionados com o Eclipse; se tivesse, estariam na <extension>/
, e não em <extension>/eclipse/
. Como referência, a estrutura fundamental deste directório seria semelhante a:
<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/
O conteúdo exacto do directório de entrada <extension
> determina quais os ficheiros que serão eventualmente instalados no computador do utilizador final.
As entradas finais no script de criação do instalador são as cadeias de id e versão para a função da extensão, por exemplo, "com.example.wiley.anvil
" e "1.0.0
". Estas cadeias têm um significado especial para o instalador, aparecendo nos nomes de ficheiros e directórios, e no conteúdo dos ficheiros do marcador criados no momento da instalação.
Um instalador de extensões é semelhante a um instalador de produtos na maior parte das funções. As áreas em que diferem encontram-se realçadas a seguir:
No momento da instalação, o instalador comporta-se de modo padrão:
Se a localização especificada no passo 5 for <install
>, o instalador copia todos os ficheiros no directório <extension>
para o directório <install
> no passo 11.
Ficheiro de entrada | Ficheiro instalado |
<extension>/* |
<install>/* |
Para o passo 7, qualquer produto do Eclipse pode ser um candidato. O produto baseado no Eclipse pode ser reconhecido pela presença de um ficheiro <product install>/eclipse/.eclipseproduct
; o utilizador deverá poder pedir uma pesquisa de disco limitada para os produtos instalados (um botão "procurar produtos instalados"), ou poderia deslocar-se para um directório que contém um produto (isto é, um botão "procurar").
O instalador deverá executar verificações de compatibilidade no passo 8 por correspondência de padrão simples contra sub-directórios no directório <product install>/eclipse/features
. Por exemplo, a presença de uma pasta correspondente "org.eclipse.jdt_2.*
" significa que o JDT está incluído no produto instalado.
O ficheiro do marcador criado no passo 10, <install>/eclipse/.eclipseextension
, é utilizado para marcar um directório no qual a extensão baseada no Eclipse foi instalada, principalmente para instaladores de extensão a localizar (análogo a um ficheiro do marcador .eclipseproduct
do produto). Este ficheiro de marcador é um ficheiro de formato java.io.Properties (codificação de caracteres ISO 8859-1 com o carácter de escape "\") e contém as seguintes informações que identificam a extensão perante o utilizador e distinguem uma extensão baseada no Eclipse de outra:
name=Wiley Anvil Enterprise Edition
id=com.example.wiley.anvilfeature
version=1.0.0
Os valores das propriedades "id" e "version" são entradas no script de criação do instalador; provavelmente, o nome da extensão é conhecido e está codificado por programa. (Os produtos não iriam aceder normalmente a este ficheiro de marcador; apenas os instaladores de produto e extensão o gravam ou lêem.)
Após instalar todos os ficheiros, a estrutura de nível superior do directório de instalação iria conter os seguintes ficheiros e sub-directórios:
<install>/
eclipse/
.eclipseextension
features/
plugins/
A única diferença significativa de um instalador de produtos é que um instalador de extensões também cria ficheiros de ligação noutros produtos baseados no Eclipse que já estão instalados no computador do utilizador. (Isto faz com que o utilizador não tenha de associar manualmente a nova extensão dentro de cada produto utilizando o gestor de actualizações do Eclipse.)
O ficheiro de ligação criado no passo 14 é <product install>/eclipse/links/com.example.wiley.anvilfeature.link
; isto é, o ficheiro tem o mesmo nome do directório da função da extensão menos o sufixo do número da versão. Um ficheiro de ligação é um ficheiro de formato java.io.Properties (codificação de caracteres ISO 8859-1 com o carácter de escape "\").
A chave é "path" e o valor é o caminho absoluto da extensão instalada, <install>
;, por exemplo, uma entrada pode assemelhar-se a "path=C:\\Program Files\\Wiley\\Anvil
".
O instalador é responsável por converter a partir da codificação de caracteres original para Unicode e adicionando caracteres de escape "\" onde seja necessário. Os caracteres de escape são normalmente necessários, uma vez que <install>
contém normalmente caracteres especiais (como "\") e pode mencionar directórios com caracteres que não do latim nos respectivos nomes. O produto lê os ficheiros de ligação quando arranca. O instalador mantém um registo de quaisquer ficheiros de ligação que cria, por isso, podem ser localizados quando a extensão é actualizada ou desinstalada.
No momento da desinstalação, o instalador deverá comportar-se de modo padrão:
instalação
>, e todos os ficheiros em <install
>/eclipse/features
e <install
>/eclipse/plugins
incluindo aqueles colocados por terceiros, que não este instalador (por exemplo, o gestor de actualizações do Eclipse). Quando uma extensão é desinstalada, todos os ficheiros de conector e funções deverão ser eliminados; não existem ficheiros de dados importantes para manter nestes sub-directórios. Isto permite ao utilizador desinstalar uma extensão por completo, incluindo quaisquer actualizações aplicadas pelo gestor de actualizações do Eclipse.
Quando a extensão já está instalada no computador do utilizador, o instalador deverá permitir uma actualização do serviço ou da versão a aplicar à extensão instalada.
No momento da instalação, o instalador deverá comportar-se de modo padrão:
No passo 2, uma extensão instalada pode ser reconhecida pela presença de um directório "eclipse
", de imediato, que contém um ficheiro chamado ".eclipseextension
".
O ascendente do directório "eclipse
" é um directório de instalação da extensão, isto é, <install>/eclipse/.eclipseextension
.
A informação contida dentro deste ficheiro de marcador deverá ser mostrado ao utilizador para a confirmação de que está a ser actualizada a extensão correcta (podem existir várias extensões baseadas no Eclipse no computador do utilizador).
Para o passo 7, o instalador não deverá eliminar ou substituir nenhum dos ficheiros que instalou originalmente; em vez disso, deverá adicionar apenas os ficheiros para as novas versões de funções e conector, e possivelmente gravar novamente o ficheiro do marcador <install>/eclipse/.eclipseextension
. Manter as versões antigas fornece ao utilizador a opção de sair da actualização. Tal como na instalação de um produto, não é necessário abrir os ficheiros em <install>/eclipse/plugins/com.example.wiley.otherplugin_1.0.0
/ se este sub-directório existir também após a actualização; se qualquer um dos ficheiros do conector for alterado, o número de versão do conector seria revisto, fazendo com que os ficheiros para o conector actualizado fossem instalados num directório paralelo <install>/eclipse/plugins/com.example.wiley.otherplugin_1.0.1
/.