Chocolatey Package Manager

You may use Chocolatey marks/logos without a license only if your use qualifies as "Nominative Use" and meets all the following requirements:

1. The mark is used only to refer to the Chocolatey project, framework, and/or technology.
2. The mark is not used as part of your product, brand, domain, URL, or service name.
3. The mark appears less prominent than your own company or product name.
4. The reference does not create a sense of endorsement, sponsorship, or ownership by Chocolatey or RealDimensions Software, LLC.
5. The use is necessary to fully describe your services or products and is limited to only as much of the mark as is necessary for identification.

After building the source, follow these steps to install Chocolatey on a non-Windows system:

1. Locate Build Output: Copy (or link) the contents of ./code_drop/temp/_PublishedApps/choco to your preferred installation directory. On Linux, the recommended directory is /opt/chocolatey.
2. Set Environment Variable: Export the ChocolateyInstall environment variable to point to your installation directory.
3. Setup Wrapper:
   • Copy ./docker/choco_wrapper to a directory in your $PATH.
   • Rename the file to choco.
   • If your installation directory is NOT /opt/chocolatey, you must edit the wrapper file to point to the correct path.

To build a Linux-based Docker image that runs Chocolatey using Mono, follow these steps:

1. Clone the repository: git clone https://github.com/chocolatey/choco.git.
2. Navigate to the repository root.
3. Build the image using the Dockerfile.linux.
4. Run the image and test the installation by running choco -h.

You can customize the build using --build-arg to specify different build scripts (e.g., for official or debug versions).

# Build the image
docker build -t choco:latest-linux -f docker/Dockerfile.linux .

# Run the image
docker run -ti --rm choco:latest-linux /bin/bash

# Test installation
choco -h

To run Chocolatey, your system must meet the following requirements:

• .NET Framework: 4.8 or higher
• PowerShell: 2.0 or higher
• Operating System: Windows Server 2008 R2+ or Windows 10+

For details on the support lifecycle and specific supported operating systems, refer to the official documentation.

The Chocolatey CLI codebase includes unit, integration, and end-to-end tests.

Test Types

• Unit and Integration Tests: These are NUnit tests. They can be run directly within Visual Studio or as part of the standard build process.
• End-to-End Tests: These use the Pester framework.

Recommendation for E2E Tests

Because Pester tests can make actual changes to your system, it is highly recommended to run them within a dedicated virtual machine using the provided Vagrant file. Detailed instructions are available in the TESTING.md file.

To build the Chocolatey CLI on Windows, you must first generate the SolutionVersion.cs file by running the build script.

Prerequisites

• .NET Framework 4.8
• .NET Framework 4.8 Dev Pack
• Visual Studio 2019 or Visual Studio 2019 Build Tools
• .NET SDK (must be able to install .NET Global tools via dotnet tool install)

Note: You can use the setup.ps1 script at the repository root to install these requirements.

Build Process

1. Run build.bat.

Important: The build process assumes the Chocolatey CLI is already installed on the machine to generate the final Chocolatey package. If you want to build without creating packages, use the --shouldRunChocolatey=false option.

Summary of Commands

# Standard build
.uild.bat

# Build without creating Chocolatey packages
.uild.bat --shouldRunChocolatey=false

.\build.bat --shouldRunChocolatey=false

If a contribution targeting develop needs to be applied to a specific hotfix or release branch instead, use git rebase --onto to reapply the commits to the target branch. This avoids asking the contributor to rebase themselves.

# Example: Retargeting a PR to a hotfix branch
# Replace <github_pull_id> with the actual PR ID
# Replace <hotfix_branch_name> with the target branch (e.g., hotfix/0.2.2)

git fetch upstream pull/<github_pull_id>/head:pr<github_pull_id>
git checkout pr<github_pull_id>
git rebase --onto <hotfix_branch_name> develop
build.bat
# ... perform additional testing ...
git checkout <hotfix_branch_name>
git fetch upstream
git merge pr<github_pull_id> --log --no-ff
git branch -d pr<github_pull_id>
git push upstream

Building Chocolatey on non-Windows platforms requires Mono and the .NET SDK.

Prerequisites

• Mono: Version 6.6 or newer.
• .NET SDK: Version 6.0 or newer (required for build scripts and Dotnet Global Tools used in Cake).
• Git: Version 2.22+ (if building from a Git repository).
• MonoDevelop: Recommended for source development.

Preparation

1. Set permissions for shell scripts:

   chmod +x *.sh

2. (macOS/Linux) Consider adding the following to your ~/.profile to configure pkg-config for Mono:

   export PKG_CONFIG_PATH=/opt/local/lib/pkgconfig:/Library/Frameworks/Mono.framework/Versions/Current/lib/pkgconfig:$PKG_CONFIG_PATH

Build Process

Run the provided shell script:

./build.sh

Note: Artifacts produced on Mono are similar to Windows but may have minor build script failures that can be safely ignored.

To build a Windows-based Docker image that runs Chocolatey on .NET, follow these steps on a Windows system:

1. Clone the repository: git clone https://github.com/chocolatey/choco.git.
2. Navigate to the repository root.
3. Ensure Chocolatey is available by either building it on the host or placing a pre-built .nupkg in .\code_drop\Packages\Chocolatey.
4. Build the image using the Dockerfile.windows.
5. Run the image and test the installation by running choco -h.

Note: If you encounter errors like Can't add file x to tar: archive/tar: missed writing 794 bytes, ensure that Visual Studio is closed during the build process.

# Build the image
docker build -t choco:latest-windows -f docker/Dockerfile.windows .

# Run the image
docker run -ti --rm choco:latest-windows cmd.exe

# Test installation
choco -h

While Chocolatey open source code is licensed under Apache 2.0, the Chocolatey marks and logos are not covered by the Apache 2.0 license. You may redistribute the software, but you cannot use the marks without express written permission from RealDimensions Software, LLC.

Prohibited uses without written permission include:

• Merchandising (e.g., T-shirts, mugs).
• Using marks on or in relation to a software product built on top of Chocolatey.
• Using marks in an attention-getting or branding manner.
• Using marks in a way that implies affiliation, approval, endorsement, or sponsorship by RealDimensions Software, LLC.

To implement a new feature, create a branch from develop. When the feature is complete, merge it back into develop using --no-ff to preserve the merge commit, then delete the local and remote feature branches.

# Creating a feature branch
git checkout -b myfeature develop

# Finishing a feature branch
git checkout develop
git merge --no-ff myfeature
git branch -d myfeature
git push origin --delete myfeature # if feature branch pushed to fork repository
git push upstream develop
git push origin develop