Última modificação em 6 de maio de 2002, segunda-feira, às 11:15
Os produtos baseados no Eclipse precisam ser instalados corretamente no computador do usuário final. Ferramentas fornecidas com finalidades especiais, como o InstallShield e o RPM, são sempre utilizadas para construir instaladores executáveis que automatizam a instalação, atualização e desinstalação. Esta nota descreve como gravar um instalador de um produto baseado no Eclipse e de extensões instaláveis separadamente, para produtos baseados no Eclipse.
Assumimos que uma equipe de desenvolvimento de produto seja responsável pelo fornecimento de ingredientes brutos que precisarão chegar aos computadores dos usuários finais fornecidos como um instalador executável. A criação de instaladores executáveis é feita através de scripts, assim como as ações do tempo de instalação necessárias para interagir com os arquivos do usuário final e de depósito em seus computadores. Esta nota descreve em detalhes o que esses instaladores precisam fazer e como devem funcionar.
Esta nota deve ser tratada como uma receita para a pessoa responsável pela gravação de um instalador de produtos baseados no Eclipse. Dois bons motivos pelos quais recomendamos que todos os gravadores de instaladores sigam nossa receita são:
Um instalador de produto deve ser independente - o tipo de coisa que poderia ser distribuída em um CD e instalada em qualquer máquina com um sistema operacional adequado.
O Eclipse requer um JRE (Java Runtime Environment) Java2 para executar o código Java. JREs são softwares licenciados, obtidos em fornecedores Java. Uma empresa poderá incluir um JRE em seu produto e instalá-lo no computador do usuário final juntamente com o produto, se obtiver licença do fornecedor de JRE para redistribuí-lo. A alternativa é requerer a pré-instalação do JRE no computador do usuário final, associada à hora da instalação do produto. De uma ou outra maneira, um produto baseado no Eclipse requer um JRE adequado e o instalador do produto deve desempenhar a função de instalar um JRE ou de localizar e efetuar o link em um JRE preexistente.
Suponha que um JRE tenha que ser instalado com o produto. Um diretório contendo
o JRE é uma entrada para o script de criação do instalador. Indique este diretório
<JRE>. Este diretório deve ter uma estrutura de diretórios JRE padrão,
com o executável Java localizado em jre/bin/java.exe
e a biblioteca de classe
em jre/lib/rt.jar
abaixo do diretório <JRE>.
Para referência, a estrutura desse diretório é a seguinte:
<JRE>/
jre/
bin/
java.exe
lib/
rt.jar
Há arquivos (e subdiretórios) adicionais nesses diretórios; mostramos apenas um exemplo da estrutura geral. Os nomes em itálico são específicos do produto.
A segunda entrada para o script de criação do instalador é um diretório, <product
head
>,
contendo o launcher executável específico do produto e os arquivos não relacionados ao
Eclipse. Para referência, a estrutura
desse diretório seria a seguinte (itálico indica nomes de arquivos que
variam de produto para produto):
<product head>/
A terceira entrada para o script de criação do instalador é um diretório, <
acmeproduct.exe
product
body
>,
contendo os recursos e plug-ins desenvolvidos para o produto. Para referência, a estrutura
desse diretório seria a seguinte:
<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 para o script de criação do instalador é um diretório, <platform
>,
contendo os recursos e plug-ins da própria plataforma Eclipse e ferramentas de terceiros incluídas.
Este diretório também inclui o launcher executável padrão do Eclipse, eclipse.exe
,
(denominado eclipse
no ambiente operacional Unix), seu associado startup.jar
e outros arquivos da plataforma Eclipse
requeridos na raiz da instalação. Para referência, a estrutura
desse diretório seria a seguinte:
<platform>
O conteúdo exato dos diretórios 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/
(mais diretórios de plug-in org.eclipse.*)
JRE
>, <product
head
>, <product body
> e <platform
> determina quais arquivos
serão eventualmente instalados no computador do usuário final.
As entradas finais para o script de criação do instalador são as cadeias de
id e versão do recurso principal do produto; por ex., "com.example.acme.acmefeature"
e "1.0.0
";
e o nome do executável do produto; por ex., "acmeproduct
.exe
".
Para produtos que não requerem seu próprio executável do produto, este seria o
caminho do launcher executável padrão do Eclipse "eclipse/eclipse.exe
".
Essas cadeias possuem significado
especial para o instalador, aparecendo em nomes de arquivos e diretórios e no
conteúdo de arquivos marcadores criados na hora da instalação.
Na hora da instalação, o comportamento do instalador deve ser o padrão (outros detalhes depois da lista de etapas):
Se a localização especificada na etapa 5 for <install
>,
o instalador copiará todos os arquivos dos diretórios <JRE
>, <platform>,
<product
>
e <product plug-ins>
para <install
>.
Arquivo de entrada | Arquivo instalado |
<JRE>/* |
<install>/eclipse/* |
<product head>/* |
<install>/* |
<product body>/* |
<install>/* |
<platform>/* |
<install>/* |
O arquivo marcador criado na etapa 8 <install>/eclipse/.eclipseproduct
é utilizado para marcar um diretório no qual um produto com base no Eclipse foi
instalado, principalmente para que os instaladores de extensão possam localizá-lo. Este arquivo marcador é um arquivo formatado java.io.Properties
(codificação de caracteres ISO 8859-1 com o caractere de escape "\") e que
contém as seguintes informações que identificam o produto para o usuário e distingue
um produto baseado no Eclipse de 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 para o script de criação do instalador; o nome do produto é presumivelmente conhecido e conectado fisicamente. (Geralmente, os produtos não acessam esse arquivo marcador; apenas os instaladores de produtos e extensões gravam ou fazem a leitura dele.)
A etapa 6 requer a verificação de um arquivo <install>/eclipse/.eclipseproduct
ou <install>/eclipse/.eclipseextension
existente. Um
produto não pode ser instalado exatamente no mesmo lugar de outro produto ou extensão.
Após a instalação de todos os arquivos, a estrutura de nível superior do diretório de instalação conteria os seguintes arquivos e subdiretórios (e talvez outros):
<install>/
Se o instalador de um produto solicitar do usuário informações sobre licença, como o
nome do proprietário registrado e a chave de licença, elas deverão ser feitas
no diálogo "Sobre" do produto (etapa 10).
acmeproduct.exe
eclipse/
.eclipseproduct
eclipse.exe
startup.jar
features/
plugins/
jre/
Isso é feito gravando-se as respostas do usuário no arquivo "about.mapping
"
no plug-in do recurso principal. Por exemplo, em <install>/plugins/com.example.acme.acmefeature_1.0.0/about.mapping
.
O arquivo "about.mapping
" já poderá existir na entrada de <product
head
>
ou pode precisar ser criado pelo instalador na hora da instalação.
As chaves são números; o valor da chave "n" é substituída
pela subcadeia "{n}
" na propriedade "aboutText
".
Por exemplo, se uma chave de licença fosse o campo número 0, um arquivo "about.mapping
"
contendo uma linha como "0=T42-24T-ME4U-U4ME
" deveria
ser criada.
Observe Bem
O arquivo "about.mapping
" é um arquivo formatado java.io.Properties
(codificação de caracteres ISO 8859-1 com o caractere de escape "\").
Quando a codificação de caracteres original for diferente de ISO 8859-1 na hora da instalação,
o instalador será responsável pela conversão da codificação de caracteres original em
Unicode e pela inclusão de caracteres de escape "\", onde necessário. A colocação de escapes é necessária
quando as cadeias contêm caracteres especiais (como "\") ou caracteres não latinos. Por exemplo, o campo número 1 contendo as 3 primeiras letras do alfabeto
grego seria gravado como "1=\u03B1\u03B2\u03B3
".
Na etapa 12, o instalador do produto lança o executável do produto, <install>/acmeproduct.exe
,
com a opção -initialize especial [exact details TBD]. Isso faz com que a plataforma do Eclipse execute
silenciosamente todo o processamento inicial demorado e armazene os resultados em cache para que,
quando o usuário iniciar o produto, ele apareça prontamente em um estado pronto para ser
negociado.
Na hora da desinstalação, o comportamento do desinstalador deve ser o padrão:
install
>
e todos os arquivos de <install
>/eclipse/features
e <install
>/eclipse/plugins
, incluindo os colocados lá por outros,
que não este instalador (por ex., pelo gerenciador de atualização do Eclipse)Quando o produto é desinstalado, os arquivos depositados na
hora da instalação devem ser excluídos, junto com os recursos atualizados e plug-ins criados
pelo gerenciador de atualização do Eclipse. Importante: Na hora da desinstalação, pode haver
outros diretórios e arquivos no diretório <install>
,
particularmente <install>/eclipse/workspace/
,
<install>/eclipse/links/
e <install>/eclipse/platform.cfg
,
contendo dados importantes
que deverão ser retidos quando o produto for desinstalado. O usuário deve conseguir
desinstalar e reinstalar um produto na mesma localização, sem perder dados
importantes.
Quando o produto já estiver instalado no computador do usuário, o instalador deve permitir a aplicação de uma atualização de serviço ou upgrade de versão.
Na hora da instalação, o comportamento do instalador deve ser o padrão:
Na etapa 2, um produto instalado pode ser reconhecido imediatamente pela presença de um diretório "eclipse
"
contendo um arquivo chamado ".eclipseproduct
".
O pai do diretório "eclipse
" é um diretório de instalação
do produto; por ex., <install>/eclipse/.eclipseproduct
.
As informações contidas nesse arquivo marcador devem ser mostradas ao usuário para
confirmação de que o produto correto está sendo atualizado (pode haver vários
produtos baseados no Eclipse no computador do usuário).
O instalador deve executar verificações de compatibilidade na etapa 3 por correspondência de padrões
simples nos subdiretórios do diretório <install>/eclipse/features
. Por
exemplo, a presença de uma pasta correspondente a "com.example.acme.otherfeature_1.0.1
"
asseguraria que uma determinada atualização de serviço teria sido aplicada no produto
instalado.
Na etapa 7, o instalador pode excluir ou substituir qualquer um dos arquivos que tenha
instalado originalmente e incluir mais arquivos. Importante: Vários arquivos e diretórios,
incluindo <install>/eclipse/workspace/
e <install>/eclipse/platform.cfg
,
podem ser co-localizados com a instalação e conter arquivos de dados importantes
que precisam ficar retidos
quando se está fazendo upgrade do produto.
Em situações de upgrade, há uma boa chance de que a maioria dos arquivos abaixo <install>/eclipse/plugins/
sejam os mesmos (o mesmo para <install>/eclipse/features/
).
Há uma boa oportunidade para otimização em <install>/eclipse/plugins/
desde que o nome do subdiretório, que incorpora o número de versão do plug-in (ou fragmento),
seja alterado se e somente se um dos arquivos abaixo dele for alterado. Em outras
palavras, não haverá necessidade de tocar nos arquivos em <install>/eclipse/plugins/org.eclipse.ui_2.0.0
/
se esse subdiretório também existir depois do upgrade; se algum dos arquivos do plug-in
tivesse que ser alterado, o número de versão do plug-in seria revisado, fazendo com que os arquivos
do plug-in com upgrade fossem instalados em um diretório paralelo <install>/eclipse/plugins/org.eclipse.ui_2.0.1
/.
Observe também que o executável do produto não deve ser lançado com -initialize no caso de reinstalação, pois isso poderia perder dados de configuração importantes do usuário.
Espera-se que o JRE esteja localizado em <install>/eclipse/jre/bin/javaw.exe
.
Se estiver localizado em outro local, o caminho absoluto deverá ser especificado com a opção -vm
na linha de comandos; por ex., -vm C:\j2jre1.3.0\jre\bin\javaw.exe
.
Em qualquer um dos casos, o instalador deverá incluir esta opção na linha de comandos do atalho do desktop
criado.
Extensão significa um conjunto instalável separadamente de recursos e seus plug-ins que podem ser associados e utilizados a partir de um ou mais produtos baseados no Eclipse instalados no mesmo computador. Comparando-se com um produto, uma extensão não é independente; ela não inclui um executável do produto, a plataforma do Eclipse, um JRE.
Sem perder a generalidade, suponha que uma extensão consista em um único
recurso. A primeira entrada para o script de criação do instalador é um diretório, <extension
>,
contendo seu recurso e plug-ins. Estamos supondo que uma extensão não tenha
arquivos relacionados ao Eclipse; se tivesse, estariam em <extension>/
e não em <extension>/eclipse/
. Para referência, a estrutura
desse diretório seria a seguinte:
<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 exato do diretório de entrada <extension
>
determina quais arquivos
serão eventualmente instalados no computador do usuário final.
As entradas finais para o script de criação do instalador são as cadeias de
id e versão do recurso da extensão; por ex., "com.example.wiley.anvil
"
e "1.0.0
". Essas cadeias possuem significado
especial para o instalador, aparecendo em nomes de arquivos e diretórios e no
conteúdo de arquivos marcadores criados na hora da instalação.
Um instalador de extensão é semelhante a um instalador de produto na maioria dos aspectos. As áreas em que são diferentes são destacadas abaixo:
Na hora da instalação, o comportamento do instalador é o padrão:
Se a localização especificada na etapa 5 for <install
>,
o instalador copiará todos os arquivos do diretório <extension>
para o <install
> na etapa 11.
Arquivo de entrada | Arquivo instalado |
<extension>/* |
<install>/* |
Na etapa 7, qualquer produto Eclipse pode ser um candidato. O produto baseado no Eclipse
pode ser reconhecido pela presença de um arquivo <product install>/eclipse/.eclipseproduct
;
o usuário deve ser capaz de solicitar uma pesquisa limitada de produtos instalados
no disco (um botão "procurar produtos instalados") ou navegar
em um diretório que contenha um produto (por ex., um botão "procurar").
O instalador deve executar verificações de compatibilidade na etapa 8 por correspondência de padrões
simples nos subdiretórios do diretório <product install>/eclipse/features
. Por exemplo, a presença de uma pasta correspondente a "org.eclipse.jdt_2.*
"
significa que o JDT está incluído no produto instalado.
O arquivo marcador criado na etapa 10, <install>/eclipse/.eclipseextension
,
é utilizado para marcar um diretório no qual uma extensão baseada no Eclipse foi
instalada, principalmente para que os instaladores de extensão possam localizá-lo.
(semelhante ao arquivo marcador .eclipseproduct
de um produto). Este
arquivo marcador é um arquivo formatado java.io.Properties
(codificação de caracteres ISO 8859-1 com o caractere de escape "\") e que
contém as seguintes informações que identificam a extensão para o usuário e distingue
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 para o script de criação do instalador; o nome da extensão é presumivelmente conhecido e conectado fisicamente. (Geralmente, os produtos não acessam esse arquivo marcador; apenas os instaladores de produtos e extensões gravam ou fazem a leitura dele.)
Após a instalação de todos os arquivos, a estrutura de nível superior do diretório de instalação conteria os seguintes arquivos e subdiretórios:
<install>/
eclipse/
.eclipseextension
features/
plugins/
A única diferença significativa de um instalador de produto é que um instalador de extensão também cria arquivos de link em outros produtos baseados no Eclipse já instalados no computador do usuário. (Isso evita que o usuário tenha que associar manualmente a nova extensão de cada produto utilizando o gerenciador de atualização do Eclipse.)
O arquivo de link criado na etapa 14 é o <product install>/eclipse/links/com.example.wiley.anvilfeature.link
;
ou seja, o arquivo tem o mesmo nome do diretório de recurso da extensão menos
o sufixo de número de versão. Um arquivo de link é um arquivo formatado java.io.Properties
(codificação de caracteres ISO 8859-1 com o caractere de escape "\").
A chave é "path" e o valor é o caminho absoluto da extensão
instalada, <install>
; por ex., uma entrada pode ser semelhante a "path=C:\\Program
Files\\Wiley\\Anvil
".
O instalador é responsável pela conversão
da codificação de caracteres
original em Unicode e pela inclusão de caracteres de escape "\", onde necessário. Geralmente, a
colocação de escapes é necessária, uma vez que <install>
normalmente contém caracteres especiais (como "\")
e pode mencionar diretórios com caracteres não latinos em seus nomes. O produto lê
os arquivos de link ao inicializar. O instalador mantém um registro de todos os arquivos
de link criados para que possam ser localizados quando a extensão for atualizada ou
desinstalada.
Na hora da desinstalação, o comportamento do desinstalador deve ser o padrão:
install
>
e todos os arquivos de <install
>/eclipse/features
e <install
>/eclipse/plugins
, incluindo os colocados lá por outros,
que não este instalador (por ex., pelo gerenciador de atualização do Eclipse)Quando uma extensão é desinstalada, todos os arquivos de plug-ins e de recursos devem ser excluídos; não há arquivos de dados importantes que devam ser mantidos nesses subdiretórios. Isso permite a desinstalação completa da extensão, incluindo as atualizações aplicadas pelo gerenciador de atualização do Eclipse.
Quando a extensão já estiver instalada no computador do usuário, o instalador deve permitir a aplicação de uma atualização de serviço ou upgrade de versão.
Na hora da instalação, o comportamento do instalador deve ser o padrão:
Na etapa 2, uma extensão instalada pode ser reconhecida imediatamente pela presença de um diretório "eclipse
"
contendo um arquivo chamado ".eclipseextension
".
O pai do diretório "eclipse
" é um diretório de instalação
da extensão; por ex., <install>/eclipse/.eclipseextension
.
As informações contidas nesse arquivo marcador devem ser mostradas ao usuário para
confirmação de que a extensão correta está sendo atualizada (pode haver várias
extensões baseadas no Eclipse no computador do usuário).
Na etapa 7, o instalador não deve excluir ou sobrepor nenhum dos arquivos
instalados originalmente; em vez disso, deve incluir apenas os arquivos de novas
versões de recursos e plug-in e, possivelmente, regravar o arquivo marcador <install>/eclipse/.eclipseextension
. Manter as versões antigas dá ao usuário
a opção de recuperar-se da atualização. Assim como com o upgrade de uma instalação do produto,
não há necessidade de tocar nenhum arquivo de <install>/eclipse/plugins/com.example.wiley.otherplugin_1.0.0
/
se esse subdiretório também existir depois do upgrade; se algum dos arquivos do plug-in
tivesse que ser alterado, o número de versão do plug-in seria revisado, fazendo com que os arquivos
do plug-in com upgrade fossem instalados em um diretório paralelo <install>/eclipse/plugins/com.example.wiley.otherplugin_1.0.1
/.