Como Gravar um Instalador do Eclipse

Última modificação em 18 de junho de 2004, sexta-feira às 15h20

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:

Script de Criação do Instalador do Produto

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 ativador 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>/
  acmeproduct.exe

A terceira entrada para o script de criação do instalador é um diretório, <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 ativador 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>
  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.*)

O conteúdo exato dos diretórios de entrada <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 ativador 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):

  1. avisar o usuário para sair de todos os programas
  2. apresentar o produto a ser instalado
  3. se apropriado, perguntar ao usuário o nome do proprietário registrado e a chave de licença
  4. exibir o contrato de licença do produto e solicitar a aceitação do usuário
  5. recomendar uma localização para instalação do produto no disco (mas permitir que o usuário substitua este padrão)
  6. verificar se um produto ou extensão já não está armazenado na localização especificada
  7. solicitar que o usuário confirme todos os detalhes da instalação
  8. criar arquivo marcador para marcar a raiz da instalação do produto
  9. copiar arquivos para o disco  (consulte abaixo)
  10. se apropriado, inserir o nome do proprietário registrado e a chave de licença na descrição de "Sobre"
  11. criar um atalho no desktop para executar o executável do produto
  12. criar uma entrada apropriada para que o usuário desinstale o produto
  13. lançar o executável do produto com a opção -initialize para executar o processamento inicial
  14. oferecer a exibição das notas sobre o release do produto (arquivo "readme")

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>/
  acmeproduct.exe
  eclipse/
    .eclipseproduct
    eclipse.exe
    startup.jar
    features/
    plugins/
    jre/

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).

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.

Comportamento do Desinstalador

Na hora da desinstalação, o comportamento do desinstalador deve ser o padrão:

  1. avisar o usuário para sair de todos os programas, especialmente do produto que está sendo desinstalado
  2. solicitar confirmação do usuário de que o produto será desinstalado
  3. remover todos os arquivos instalados do diretório <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)
  4. remover o atalho do executável do produto no desktop
  5. remover a entrada do desinstalador do produto
  6. informar ao usuário sobre os arquivos não removidos

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/configuration/, 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.

Comportamento do Instalador com o Produto já Instalado

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:

  1. avisar o usuário para sair de todos os programas, especialmente do produto que está sendo atualizado
  2. localizar o produto instalado a ser atualizado, procurando no disco uma instalação existente do produto, se necessário ou deixando que o usuário a localize
  3. determinar onde este instalador é uma atualização compatível
  4. se apropriado, perguntar ao usuário o nome do proprietário registrado e a chave de licença
  5. exibir o contrato de licença atualizado do produto e solicitar a aceitação do usuário
  6. solicitar que o usuário confirme todos os detalhes da atualização
  7. atualizar arquivos no disco  (consulte abaixo)
  8. se necessário, alterar o atalho do desktop para executar o executável do produto
  9. deve incluir arquivos modificados ou recém-incluídos na lista de remoção na hora da desinstalação (onde possível)
  10. oferecer a exibição das notas sobre o release do produto (arquivo "readme")

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/, <install>/eclipse/configuration, podem ser co-localizados com a instalação e conter arquivos de dados importantes que precisam ser retidos ao se fazer 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/. 

Associando um JRE Instalado em Outro Local

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.

Script de Criação do Instalador da Extensão

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:

  1. avisar o usuário para sair de todos os programas
  2. apresentar a extensão a ser instalada
  3. se apropriado, perguntar ao usuário o nome do proprietário registrado e a chave de licença
  4. exibir o contrato de licença da extensão e solicitar a aceitação do usuário
  5. recomendar uma localização para instalação da extensão no disco (mas permitir que o usuário substitua este padrão)
  6. verificar se um produto ou uma extensão diferente já não está armazenado na localização especificada
  7. perguntar ao usuário quais produtos utilizarão esta extensão (pesquisar no disco; procurar; ou ignorar)
  8. opcionalmente, determinar se a extensão é compatível com os produtos selecionados
  9. solicitar que o usuário confirme todos os detalhes da instalação
  10. criar arquivo marcador para marcar a raiz da instalação da extensão
  11. copiar arquivos para o disco  (consulte abaixo)
  12. inserir o nome do proprietário registrado e a chave de licença na descrição de "Sobre"
  13. criar uma entrada apropriada para que o usuário desinstale a extensão
  14. gravar arquivo de link em cada um dos produtos selecionados para associar a extensão ao produto
  15. oferecer a exibição das notas sobre o release da extensão (arquivo "readme")

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.

Comportamento do Desinstalador

Na hora da desinstalação, o comportamento do desinstalador deve ser o padrão:

  1. avisar o usuário para sair de todos os programas, especialmente dos produtos que estão utilizando a extensão sendo desinstalada
  2. solicitar confirmação do usuário de que a extensão será desinstalada
  3. remover todos os arquivos instalados do diretório <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)
  4. se possível, remover o arquivo de link dos produtos aos quais ele tinha sido incluído 
  5. remover a entrada do desinstalador da extensão
  6. informar ao usuário sobre os arquivos não removidos

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.

Comportamento do Instalador com a Extensão já Instalada

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:

  1. avisar o usuário para sair de todos os programas, especialmente dos produtos que estão utilizando a extensão sendo atualizada
  2. localizar a extensão instalada a ser atualizada, procurando no disco uma instalação existente da extensão, se necessário ou deixando que o usuário a localize
  3. determinar onde este instalador é uma atualização compatível
  4. se apropriado, perguntar ao usuário o nome do proprietário registrado e a chave de licença
  5. exibir o contrato de licença atualizado do produto e solicitar a aceitação do usuário
  6. solicitar que o usuário confirme todos os detalhes da atualização
  7. atualizar arquivos no disco  (consulte abaixo)
  8. deve incluir arquivos modificados ou recém-incluídos na lista de remoção na hora da desinstalação (onde possível)
  9. oferecer a exibição das notas sobre o release da extensão (arquivo "readme")

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/.