Skip to content

Chocolatey Packages

Jump to bottom
Ana María Martínez Gómez edited this page Nov 6, 2024 · 2 revisions

This repository contains the source code for the Chocolatey packages supporting the following analysis environment projects:

Read Chocolatey documentation to learn about what Chocolatey packages are and about the general package creation proces.

Package Structure

Packages consist of:

  1. The tool directory with the naming convention toolname.vm or tool-name.vm
  2. Within the tool directory:
    1. A nuspec file named as the tool directory with the .nuspec extension pre-prended (toolname.vm.nuspec or tool-name.vm.nuspec)
    2. A directory named tools
  3. Within the tools directory:
    1. A file named chocolateyinstall.ps1
    2. A file named chocolateyuninstall.ps1

Below is an overview of what each file is for:

  • nuspec file: package description in XML format
  • chocolateyinstall.ps1: PowerShell script with instructions to download and install your tool
  • chocolateyuninstall.ps1: PowerShell script with instructions to uninstall your tool

A tool package should use directories and files using all lowercase names.

The following section documents the structure of the nuspec file file. Check also the Coding Conventions page.

nuspec

Our packages are expected to be installed automatically by a script, so simplicity and maintainability are more important than providing detailed information in the .nuspec file. Because of that, the .nuspec file must only contain the fields below:

Template

<?xml version="1.0" encoding="utf-8"?>
<package xmlns="http://schemas.microsoft.com/packaging/2015/06/nuspec.xsd">
  <metadata>
    <id>application-name.vm</id>
    <version>0.0.0</version>
    <description>short description</description>
    <authors>Author1, Author2</authors>
    <dependencies>
      <dependency id="common.vm" />
    </dependencies>
  </metadata>
</package>

Fields

id

The id should have the following format: toolName.vm

version

Non-metapackages

For packages that install tools via URLs and use three or fewer version segments, use the tool's version string. For tools that use four version segments, use the tool's version segments one through three and the current date in the format YYYYMMDD for the fourth segment.

For example:

2.1 -> 2.1
2.1.3 -> 2.1.3
2.1.3.4 -> 2.1.3.20220221

What if there is no clear version?

  • If the tool/code does NOT specify a version or installs several tools, use the scheme 0.0.0.YYYYMMDD.

When do I update the a package's version string?

The version needs to be increased every time you modify an existing package. For example, if you fix a bug in a package, you need to update the nuspec version string. Our guidance is to add the current date to the 4th segment using the format YYYYMMDD. For example, 1.6.2 becomes 1.6.2.20220113 and 3.02 becomes 3.02.0.20220113. If the date is already in the 4th segment, you can increment it to the next day (e.g., 20220113 -> 20220114) and when the PR is merged it should be good to go.

Metapackages

A metapackage is a package that installs and configures other packages via dependencies. For metapackages, use the version scheme 0.0.0.YYYYMMDD (e.g., 0.0.0.20210521) and only include metadata relevant to the metapackage itself in the .nuspec file -- nothing specific to the packages it installs (since there can be many).

Version Exception!!

  • When a metapackage is named after and installs/configures a specific tool (for instance cygwin.vm that installs/configures cygwin) lock the dependency version (e.g., version="[3.2.0]") and use the locked version as the metapackage's version. If the dependency's version uses the 4th segment (e.g., version="[2.0.1.20210213]") update the metapackage's version to use the current date (YYYYMMDD) in the 4th segment (i.e., <version>2.0.1.20220224</version>). Additionally, when a change is made to a metapackage, always use the current date in the 4th segment.

description

The description should be short and not include version specific details or other information that is likely to change in a future version.

authors

Authors of the software comma separated.

dependencies

common.vm should be included in the dependencies for every package. Specify the version if you require a minimum version (for example because the package uses a newly introduced function). For example, the following syntax requires common.vm >= 0.0.0.20240607:

<dependency id="common.vm" version="0.0.0.20240607" />

In general, fix dependencies to avoid that an update breaks the package. For example, the following syntax requires the exact version0.0.0.20240607 of notepadplusplus:

<dependency id="notepadplusplus" version="[8.4.5]" />

Ensure you do not use a fix version for common.vm (using brackets) or any other package that could cause a conflict or circular dependency.

For dependencies that are not likely to break with minor updates and that are required by many packages, we have introduced special metapackages with a relaxed version fixed to prevent dependency incompatibilities. Ensure you use the special metapackages instead of using the package they install directly. For example:

  • python3.vm: <dependency id="python3" version="[3.10.0, 3.11.0)" />
  • nodejs.vm: <dependency id="nodejs" version="[20.7.0, 20.8.0)" />

For some dependencies that get updated often without improving the tool functionality, we also use a relaxed fixed version to prevent our bot from updating them as the updates are very noisy. Examples:

  • sfextract.vm: <dependency id="dotnet-6.0-sdk" version="[6.0.400, 6.1)" />

See NuGet version ranges documentation for more information.

Documentation

Daily testing

Clone this wiki locally