Hosting Package on Chocolatey

In this article, we will take a brief look at the key stages of Chocolatey package creation.

Prerequisites

Before getting started with the creation of  a Chocolatey package, make sure you need to: 

• have Chocolatey installed;
• read the What are Chocolatey Packages? section of the Chocolatey documentation;
  
• know how a package works. Specifically, you are aware that:
  
  • a package contains a *.nuspec file. This defines the package. (Docs);
    
  • a package may contain embedded software;
    
  • a package may contain an installation script.

A Chocolatey package comprises of the following main elements:

1. A *.nuspec file. This step is obligatory.
2. The chocolateyInstall.ps1 file.
3. Any application files to include (it is highly recommended that you are the author in this case or you have the right to distribute files). The *.exe files in the package/downloaded to the package folder from chocolateyInstall.ps1 will have a link to the command line.
4. chocolateyUninstall.ps1  for uninstalling your package.

I recommend you to take a look at the video showing the package creation.  Please note that the video features a bit outdated contents of the chocolateyInstall.ps1. At the moment, chocolateyInstall.ps1 looks like the following:

$packageName = 'windirstat
$fileType = 'exe'
$url = 'http://prdownloads.sourceforge.net/windirstat/windirstat1_1_2_setup.exe'
$silentArgs = '/S'

Install-ChocolateyPackage $packageName $fileType $silentArgs $url

The Chocolatey Windows package manager uses the same infrastructure as NuGet, that is the Visual Studio package manager. Therefore, the packages are based on the same principles, including that one stating that the package description (specification) must be stored in the XML format, known as Nuspec.

The *.nuspec file contains such basic information as the version, license, maintainer, and package dependencies. Chocolatey includes additional optional functionality at the very top of the NuGet *.nuspec file. Thus,  the best way to determine the currently supported features is to create a test package, and look at the generated *.nuspec file:

choco new testpackage

Note: If your package uses the recently introduced functionality, you might want to include a dependency indicating the lowest Chocolatey version that supports the required functionality. Otherwise, the installation could fail for the users who have an older Chocolatey version installed.

You can indicate the Chocolatey dependency like any other dependency, e.g.:

<dependencies> 
<dependency id="chocolatey" version="0.9.8.21" /> 
</dependencies>

Quick Start Guide

1. Generate a new package:
   • The  choco new -h command will help you to set up the package options.
   • Once you figured out all options, you can proceed with generating your template.
2. Edit the template accordingly:
   • cd package-name
   • Edit the package-name. nuspec configuration file.
   • Edit the ./tools/chocolateyInstall.ps1 install script.
     • Make sure you configured the installer silent mode. Use Universal Silent Switch Finder, which is available as a Choco package: choco install ussf.
     • You need to save your files with the UTF–8 character encoding without BOM.
3. Build the package:
   • Still in the package directory.
   • choco pack
     • “Successfully created package-name.1.1.0.nupkg”.
4. Test the package:
   • Testing should be performed on a virtual machine.
   • In your package directory, use:
     • choco install package-name -s
package-name is the id element in the nuspec
5. Push the package to the Chocolatey community package repository:
   • Get a Chocolatey account:
     • Register.
   • Copy the API key from your Chocolatey account.
   • choco apikey -k [API_KEY_HERE] -source https://push.chocolatey.org/
   • choco push package-name.1.1.0.nupkg -s https://push.chocolatey.org/ – the *.nupkg file can be omitted if it is the only one in the directory.

Examples

Here are some simple examples.

Note: The provided examples may require an update of checksums and newer package concepts. Run choco new when creating packages as it contains the most up-to-date notes.

chocolateyInstall.ps1 for .exe installer

$name = 'Package Name'
$installerType = 'exe'
$url  = 'http://path/to/download/installer.exe'
$silentArgs = '/VERYSILENT'

Install-ChocolateyPackage $name $installerType $silentArgs $url

Note: You need to set up the command line switch to make the installer silent, e.g. ./VERYSILENT The switch name varies, depending on the installer.

chocolateyInstall.ps1 for .msi installer

NOTE: You need to maintain the compatibility with Posh v2. Not each supported OS is on Posh v2 (nor comes OOB with Posh v3+). The best practice is to work with the widest compatibility of systems out there.

$packageName = 'Package Name'
$installerType = 'msi'
$url = 'http://path/to/download/installer_x86.msi'
$url64 = 'http://path/to/download/installer_x64.msi'
$silentArgs = '/quiet'
$validExitCodes = @(0,3010)

Install-ChocolateyPackage $packageName $installerType $silentArgs $url $url64  -validExitCodes $validExitCodes

Testing Your Package

Note 1: I strongly recommend performing testing on a virtual machine, not on your working machine.

Note 2: The package testing can be done in the same way as the verifier. Take a look at Chocolatey Verifier Testing.

To test the newly built package, open a command-line shell, and navigate to the directory where the *.nupkg file is located. Then type the following:

choco install packageName -dv -s .

This command will install the package right out of your source. If you find things you need to fix, use --force (-f) to remove and reinstall the package from the updated *.nupkg. If you are specifically testing chocolateyBeforeModify.ps1, you need to test the upgrade and uninstall scenarios. You need to install a version of the package with this file first because similar t0 uninstall, before modify runs from the installed package, not the package you are installing (like chocolateyInstall.ps1 does).

Note 1: Force --force (-f) should be used only during the subsequent testing when you are reinstalling the same package that you’ve changed and should not be used in regular use scenarios. It definitely should not be in scripts.

Note 2: If you use a Semver dash in your package version (such as 1.0.0-beta), you need to use the -pre switch. Otherwise, you will get the ‘Unable to find package‘ errors from the choco install. You can also specify -version 1.0.0-beta to install the exact version.

The dot character points to the current directory. You can specify multiple directories separated by a semicolon.

Push Your Package

To push your package after you have built and tested it, type the following:

choco push packageName.nupkg -s sourceLocation

Where:

• packageName.nupkg is the name of the nupkg that was built with a version number as a part of the package name;
• sourceLocation is the location of the source you want to push to (e.g. -s https://chocolatey.org/ for the Chocolatey community feed).

You need to have an API key for the https://chocolatey.org/ set. Take a look at choco push.

You can also log into chocolatey.org and upload your package from there (not recommended for the packages over 2MB).

References

You may use the following resources to find out more  about the creation and distribution of a Chocolatey package:

• https://chocolatey.org/docs/create-packages
• https://github.com/chocolatey-community/chocolatey-test-environmChocolateyent