Domine o Chocolatey! Crie o Seu Primeiro Pacote

Publicado em por

Se trabalha com administração de sistemas ou simplesmente gosta de automatizar a gestão de software no seu ambiente Windows, é provável que já conheça ou utilize o Chocolatey. Este gestor de pacotes para Windows simplifica imensamente a instalação, atualização e remoção de aplicações.

No entanto, o que fazer quando o software que precisa de gerir não está disponível no repositório oficial do Chocolatey? Ou quando tem software interno, versões específicas de programas, ou configurações personalizadas que precisam de ser distribuídas de forma consistente? A resposta é simples: criar o seu próprio pacote Chocolatey.

Criar pacotes Chocolatey personalizados permite-lhe ter controlo total sobre o processo de instalação e desinstalação de qualquer aplicação. Neste guia prático, vamos explorar os passos essenciais para criar um pacote Chocolatey básico, desde a estrutura inicial até ao teste final.

Pré-requisitos

Antes de mergulharmos na criação do seu primeiro pacote Chocolatey, certifique-se de que tem o seguinte à mão:

  • Chocolatey Instalado e Configurado: Obviamente, precisa do Chocolatey a funcionar no seu sistema. Se ainda não o tem, pode seguir a documentação oficial em chocolatey.org/install. Certifique-se de que a linha de comandos do Chocolatey (`choco`) está acessível.
  • Editor de Texto: Necessita de um editor de texto simples ou um editor de código mais avançado (como Notepad++, VS Code, Sublime Text, etc.) para criar e editar os ficheiros do pacote.
  • Algum Conhecimento Básico de PowerShell (Opcional, mas Útil): Os scripts de instalação e desinstalação do Chocolatey são escritos em PowerShell. Embora usemos funções auxiliares que simplificam muitas tarefas, um conhecimento básico de PowerShell será benéfico para personalizações mais complexas.
  • O Software que Pretende Empacotar: Tenha o instalador ou os ficheiros do software que quer transformar num pacote Chocolatey.

Com estes pré-requisitos cumpridos, está pronto para começar a criar o seu pacote Chocolatey.

Passo 1: Criar a Estrutura da Pasta do Pacote

Todo o pacote Chocolatey segue uma estrutura de pastas específica. Esta organização ajuda o Chocolatey a encontrar os ficheiros de metadados e os scripts de instalação/desinstalação. A estrutura básica é a seguinte:

Crie uma pasta com o nome do seu pacote e a versão que está a criar. Por exemplo, se estiver a empacotar um programa chamado “Meu Programa” na versão 1.0.0, a pasta seria:

meu-programa.1.0.0
/

Dentro desta pasta principal, irá criar dois elementos essenciais:

  • Um ficheiro com o nome do pacote e a extensão .nuspec. Este ficheiro contém todos os metadados do seu pacote.
  • Uma pasta chamada tools. Esta pasta irá conter os scripts PowerShell que o Chocolatey executa para instalar e desinstalar o software.

A estrutura final deverá ser algo parecido com isto:

meu-programa.1.0.0/
    ├── meu-programa.nuspec
    └── tools/

É dentro da pasta tools que irá colocar os seus scripts de instalação (chocolateyInstall.ps1) e desinstalação (chocolateyUninstall.ps1), bem como quaisquer ficheiros adicionais que precise para a instalação (como instaladores .exe ou .msi, ficheiros de configuração, etc.). Certifique-se de que o nome do ficheiro .nuspec corresponde ao nome da pasta principal (sem a versão).

Passo 2: Criar o Ficheiro .nuspec

O ficheiro .nuspec é o coração do seu pacote Chocolatey. É um ficheiro XML que descreve o pacote, fornecendo informações como o nome, versão, descrição, autor, dependências e outros metadados importantes. O Chocolatey utiliza estas informações para gerir o pacote.

Abra o ficheiro meu-programa.nuspec (ou o nome que escolheu) no seu editor de texto e adicione a seguinte estrutura básica:

<?xml version="1.0" encoding="utf-8"?>
<package xmlns="http://schemas.microsoft.com/packaging/2015/06/nuspec.xsd">
  <metadata>
    <!-- Metadados do Pacote -->
  </metadata>
  <!-- Ficheiros a incluir no pacote (opcional) -->
  <!-- <files>...</files> -->
</package>

Dentro da tag <metadata>, irá adicionar os detalhes específicos do seu pacote. Aqui estão algumas das tags mais comuns e importantes que deve incluir:

  • <id>: O identificador único do pacote. Deve ser minúsculo e sem espaços. Ex: meu-programa.
  • <version>: A versão do pacote. Siga um formato de versionamento padrão (ex: 1.0.0, 1.0.0.20231120).
  • <title>: O título amigável do pacote, como aparece para o utilizador. Ex: Meu Programa.
  • <authors>: O nome do autor(es) do pacote. Ex: Eu.
  • <owners>: O nome do(s) proprietário(s) do pacote (geralmente o mesmo que o autor, mas pode ser uma equipa ou organização). Ex: Eu.
  • <description>: Uma descrição detalhada do software ou do que o pacote faz. Use esta tag para explicar a finalidade do pacote.
  • <summary>: Um resumo conciso do pacote (geralmente uma ou duas frases).
  • <tags>: Palavras-chave separadas por espaços que ajudam a categorizar e encontrar o pacote. Ex: meu-programa exemplo software.
  • <dependencies>: (Opcional) Especifica outros pacotes Chocolatey dos quais este pacote depende. Útil se o seu software requer outras ferramentas já empacotadas.

Aqui fica um exemplo completo do ficheiro meu-programa.nuspec com estes campos preenchidos:

<?xml version="1.0" encoding="utf-8"?>
<package xmlns="http://schemas.microsoft.com/packaging/2015/06/nuspec.xsd">
  <metadata>
    <id>meu-programa</id>
    <version>1.0.0</version>
    <title>Meu Programa</title>
    <authors>Eu</authors>
    <owners>Eu</owners>
    <description>
      Este pacote instala o Meu Programa, uma aplicação simples
      para demonstrar a criação de pacotes Chocolatey personalizados.
      Permite fazer coisas fixes e é muito fácil de usar.
    </description>
    <summary>Um programa simples para demonstrar a criação de pacotes Chocolatey.</summary>
    <tags>meu-programa exemplo tutorial</tags>
    <!-- Pode adicionar outras tags como releaseNotes, projectUrl, etc. -->
  </metadata>
  <!--  A tag <files> é usada para incluir ficheiros adicionais no pacote,  como o instalador do software, ficheiros de configuração, etc.  Estes ficheiros serão copiados para a pasta 'tools' do pacote nupkg.  -->
  <!-- Exemplo: Incluir um instalador chamado 'MeuProgramaInstaller.exe' -->
  <!-- <files>
      <file src="caminho/para/o/MeuProgramaInstaller.exe" target="tools" />
  </files> -->
</package>

Guarde este ficheiro. Ele fornece ao Chocolatey todas as informações necessárias sobre o seu pacote.

Passo 3: Criar os Scripts de Instalação e Desinstalação

A pasta tools é onde a mágica acontece. É aqui que coloca os scripts PowerShell que o Chocolatey irá executar para instalar e desinstalar o software. Os nomes recomendados para estes scripts são:

  • chocolateyInstall.ps1: Executado quando o pacote é instalado (`choco install`).
  • chocolateyUninstall.ps1: Executado quando o pacote é desinstalado (`choco uninstall`).

Estes scripts têm acesso a uma série de funções auxiliares do Chocolatey que simplificam tarefas comuns, como descarregar ficheiros, executar instaladores, adicionar entradas ao “Programas e Funcionalidades”, gerir variáveis de ambiente, etc.

Vamos criar scripts simples que usam as funções auxiliares para instalar e desinstalar um programa (assumindo que tem um instalador na pasta tools ou que o programa já existe e só precisa de ser gerido).

chocolateyInstall.ps1 (Exemplo Básico para um Instalador .exe ou .msi):

Este script localiza o instalador dentro da pasta tools do pacote e executa-o. As funções auxiliares do Chocolatey tratam de muitos detalhes, como esperar que o instalador termine e adicionar/remover entradas no registo para gestão.

# Obtém o caminho para a pasta 'tools' dentro do pacote
$toolsDir   = "$(Split-Path -parent $MyInvocation.MyCommand.Definition)"

# Define os argumentos para a função de instalação
$packageArgs = @{
  packageName = 'MeuPrograma'
  # Nome do pacote (deve corresponder ao id do .nuspec)
  fileType = 'exe'         
  # Tipo de ficheiro do instalador (pode ser 'msi' ou 'exe')  

  url = "$toolsDir\MeuProgramaInstaller.exe" 
  # Caminho para o instalador dentro da pasta tools  
  # url64 = "$toolsDir\MeuProgramaInstaller64.exe" 
  # Opcional: para instaladores de 64 bits  
  silentArgs    = '/S'          

  # Argumentos de instalação silenciosa para o instalador (varia por programa!)  
  validExitCodes= @(0, 3010)    

  # Códigos de saída que indicam sucesso na instalação (varia por programa!)  
  softwareName  = 'Meu Programa*' 

  # Nome do software como aparece em "Programas e Funcionalidades" (use curingas se necessário)
}

# Chama a função auxiliar para instalar o pacote
Install-ChocolateyPackage @packageArgs
# Pode adicionar código adicional aqui se necessário, por exemplo:

# - Copiar ficheiros de configuração
# - Criar atalhos
# - Configurar variáveis de ambiente
# Copy-Item "$toolsDir\config.ini" "C:\ProgramData\MeuPrograma\"
# Install-ChocolateyShortcut -shortcutFilePath "$env:PUBLIC\Desktop\Meu Programa.lnk" -targetPath "C:\Program Files\Meu Programa\MeuPrograma.exe"

Importante:

Os argumentos silentArgs e validExitCodes são cruciais e *variam para cada software*. Precisa de consultar a documentação do software que está a empacotar para descobrir os argumentos de instalação silenciosa corretos e os códigos de saída de sucesso.

chocolateyUninstall.ps1 (Exemplo Básico para um Instalador .exe ou .msi):

Este script utiliza a função auxiliar de desinstalação, que tenta encontrar o software instalado com base no nome e executar o desinstalador silenciosamente.

# Define os argumentos para a função de desinstalação
$packageArgs = @{
  packageName  = 'MeuPrograma'
  # Nome do pacote (deve corresponder ao id do .nuspec)
  softwareName = 'Meu Programa*'
  # Nome do software como aparece em "Programas e Funcionalidades" (use curingas se necessário)
  fileType = 'exe'
  # Tipo de ficheiro do desinstalador (geralmente o mesmo que o instalador)
  # url = "$toolsDir\MeuProgramaUninstaller.exe"
  # Opcional: se o desinstalador for um ficheiro separado  
  silentArgs = '/S'
  # Argumentos de desinstalação silenciosa (varia por programa!)
  validExitCodes= @(0, 3010)
  # Códigos de saída que indicam sucesso na desinstalação (varia por programa!)
}
# Chama a função auxiliar para desinstalar o pacote
Uninstall-ChocolateyPackage @packageArgs
# Pode adicionar código adicional aqui se necessário, por exemplo:
# - Remover ficheiros de configuração
# - Remover atalhos# 
Remove-Item "C:\ProgramData\MeuPrograma\" -Recurse -Force
# Remove-Item "$env:PUBLIC\Desktop\Meu Programa.lnk"

Tal como no script de instalação, os argumentos silentArgs e validExitCodes para a desinstalação também dependem do software.

Se o seu pacote não instala um programa tradicional (por exemplo, apenas copia ficheiros ou configura algo), os seus scripts PowerShell serão diferentes, usando comandos básicos do PowerShell para copiar, criar pastas, executar comandos arbitrários, etc. As funções auxiliares do Chocolatey podem ser muito úteis mesmo nestes casos, como Install-ChocolateyZipPackage para extrair ZIPs ou Install-ChocolateyConfiguration para aplicar configurações DSC.

Lembre-se de colocar o instalador do software (MeuProgramaInstaller.exe neste exemplo) na pasta tools, ao lado dos scripts .ps1.

Passo 4: Empacotar o Pacote

Depois de ter a estrutura de pastas, o ficheiro .nuspec e os scripts na pasta tools, está pronto para criar o ficheiro de pacote .nupkg. Este ficheiro é um arquivo ZIP renomeado que contém todos os elementos do seu pacote na estrutura correta.

Abra a linha de comandos (cmd.exe ou PowerShell) e navegue para a pasta que contém a pasta principal do seu pacote (meu-programa.1.0.0 neste exemplo). Em seguida, execute o seguinte comando:

choco pack meu-programa.nuspec

Este comando lê o ficheiro .nuspec, verifica a estrutura, inclui os ficheiros especificados na tag <files> (se existirem) e todos os ficheiros na pasta tools, e cria o ficheiro meu-programa.1.0.0.nupkg na mesma pasta onde executou o comando.

Se tudo correr bem, verá uma mensagem indicando que o pacote foi criado com sucesso.

Passo 5: Testar o Pacote

Testar o seu pacote é um passo crucial antes de o distribuir ou publicar. Deve testar a instalação e a desinstalação para garantir que tudo funciona como esperado e que não há efeitos secundários indesejados.

Para testar a instalação localmente, navegue na linha de comandos para a pasta onde o ficheiro .nupkg foi criado e execute:

choco install meu-programa -source . --debug --verbose
  • meu-programa: É o ID do seu pacote (do ficheiro .nuspec).
  • -source .: Indica ao Chocolatey para procurar o pacote na pasta atual.
  • --debug --verbose: Opções úteis para ver detalhes do que o Chocolatey e os scripts estão a fazer, o que ajuda na resolução de problemas.

Verifique se o software foi instalado corretamente. Abra a aplicação, veja se está listada em “Programas e Funcionalidades”, e confirme se as configurações adicionais nos scripts foram aplicadas.

Para testar a desinstalação, use o comando:

choco uninstall meu-programa --debug --verbose

Verifique se o software foi removido completamente. Veja se desapareceu de “Programas e Funcionalidades” e se os ficheiros e pastas relevantes foram limpos (a menos que o software deixe propositadamente ficheiros de configuração para trás).

Repita o processo de teste várias vezes e em diferentes ambientes (se possível) para garantir a robustez do seu pacote.

Passo 6: Publicar o Pacote (Opcional)

Depois de testar exaustivamente o seu pacote e ter a certeza de que funciona corretamente, pode optar por publicá-lo.

  • Repositório Chocolatey Oficial (chocolatey.org): Se o software que empacotou é de uso geral e cumpre as diretrizes de moderação, pode submeter o seu pacote para o repositório oficial. Isto torna-o acessível a todos os utilizadores do Chocolatey em todo o mundo. Requer a criação de uma conta e a utilização do comando choco push.
  • Feed Interno/Privado: Muitas organizações criam os seus próprios feeds NuGet (que o Chocolatey pode usar) para distribuir pacotes internos ou personalizados apenas dentro da rede da empresa. Ferramentas como o Chocolatey Server, Nexus Repository, ou Artifactory podem ser usadas para isto.

A publicação é um tópico mais avançado e não será detalhado neste guia básico. O importante é saber que tem opções para partilhar os seus pacotes depois de os criar e testar.

Conclusão

Criar o seu próprio pacote Chocolatey pode parecer intimidante no início, mas como viu, o processo básico envolve apenas alguns passos: estruturar pastas, definir metadados no ficheiro .nuspec, escrever scripts simples em PowerShell usando funções auxiliares, empacotar com choco pack e, crucialmente, testar exaustivamente.

Dominar a arte de criar pacote Chocolatey permite-lhe automatizar a gestão de software personalizado ou interno, poupando tempo e garantindo consistência. Agora que tem uma compreensão básica, sinta-se à vontade para experimentar, explorar as funções auxiliares mais avançadas do Chocolatey e criar pacotes para o software que mais utiliza.

Pronto para criar o seu primeiro pacote? Partilhe as suas experiências ou dúvidas nos comentários abaixo!

Pode fazer uma doação para ajudar a mater o site, Obrigado!