diff --git a/astro.config.mjs b/astro.config.mjs index c0dd7476ab3..8081e414b23 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -178,7 +178,7 @@ export default defineConfig({ '/en-us/chocolatey-gui/setup/installation/chocolateygui': '/en-us/chocolatey-gui/setup/installation/', '/en-us/chocolatey-gui/setup/installation/chocolatey-gui': '/en-us/chocolatey-gui/setup/installation/', '/en-us/chocolatey-gui/setup/uninstallation/chocolatey-gui': '/en-us/chocolatey-gui/setup/uninstallation/', - '/docs/chocolatey-install-ps1': '/en-us/chocolatey-install-ps1/', + '/docs/chocolatey-install-ps1': '/en-us/create/package-scripts/', '/docs/chocolatey-story': '/en-us/chocolatey-story/', '/docs/chocolatey-vs-ninite': '/en-us/chocolatey-vs-ninite/', '/docs/community-packages-disclaimer': '/en-us/community-repository/community-packages-disclaimer/', @@ -354,4 +354,4 @@ export default defineConfig({ '/en-us/create/functions/test-processadminrights': '/en-us/create/cmdlets/test-processadminrights/', '/en-us/create/functions/update-sessionenvironment': '/en-us/create/cmdlets/update-sessionenvironment/', } -}); \ No newline at end of file +}); diff --git a/src/content/docs/en-us/chocolatey-install-ps1.mdx b/src/content/docs/en-us/chocolatey-install-ps1.mdx deleted file mode 100644 index d88ad9173bc..00000000000 --- a/src/content/docs/en-us/chocolatey-install-ps1.mdx +++ /dev/null @@ -1,40 +0,0 @@ ---- -order: 71 -xref: chocolatey-install-ps1 -title: ChocolateyInstall PowerShell Script -description: Information about the chocolateyinstall.ps1 file which is used to by Chocolatey to install the package contents -showInSidebar: false ---- -import Callout from '@choco/components/Callout.astro'; -import Iframe from '@choco/components/Iframe.astro'; -import Xref from '@components/Xref.astro'; - -Chocolatey uses PowerShell as a package install provider and will look for this file in the package. If it finds it, it will execute the contents of the file, attaching the helper modules. Check out the for more information on each of the helpers you can include. - -It really is just PowerShell, so you can use regular PowerShell here and it should run fine. - - - Please maintain compatibility with Posh v2. Not every OS we support is on Posh v2 (nor comes OOB with Posh v3+). It's best to work with the widest compatibility of systems out there. - - -## When is the script triggered? - -If present in a package, the `ChocolateyInstall.ps1` script will be triggered at the following points: - -* When a package is installed for the first time, after the package contents have been extracted. -* In an scenario, the install script for the new package will be run after any `chocolateyBeforeModify.ps1` script associated with the previous version of the package. - -### Example? - -This is what it takes to install [StExBar](https://community.chocolatey.org/packages/stexbar): - -```powershell -$name = 'StExBar' -$url = 'http://stexbar.googlecode.com/files/StExBar-1.8.3.msi' -$url64 = 'http://stexbar.googlecode.com/files/StExBar64-1.8.3.msi' -$silent = '/quiet' - -Install-ChocolateyPackage $name 'msi' $silent $url $url64 -``` - -The Install-ChocolateyPackage helper uses the url, msi, and silent args to download and silently install and update StExBar. diff --git a/src/content/docs/en-us/community-repository/creating-community-repository-packages.mdx b/src/content/docs/en-us/community-repository/creating-community-repository-packages.mdx new file mode 100644 index 00000000000..c61096bf32b --- /dev/null +++ b/src/content/docs/en-us/community-repository/creating-community-repository-packages.mdx @@ -0,0 +1,517 @@ +--- +order: 20 +xref: create-packages-for-ccr +title: Creating Packages for the Chocolatey Community Repository. +description: How to create packages for the Chocolatey Community Repository. +--- +import Callout from '@choco/components/Callout.astro'; +import Iframe from '@choco/components/Iframe.astro'; +import Xref from '@components/Xref.astro'; + +# Creating Chocolatey Packages + +## Summary + +See first. + + + When you host internal packages, those packages can embed software and/or point to internal shares. You are not subject to software distribution rights like the packages on the community feed, so you can create packages that are more reliable and secure. + + +First you should determine if you are making a self-contained package or (also) using automation scripts. You should also consider creating for the best maintainability over time. + +1. Run `choco new -h` to get a feel for what you can pass e.g `choco new bob` (to create a package named `bob`) +1. Note all the rules below. This will help you, especially in publishing to the community feed (https://chocolatey.org) + +### Self-Contained? + +If you have a self-contained package, you can remove the automation scripts +entirely and just include the runtime executables, they will automatically get shimmed, +which puts them on the path. Ensure you have the +the application though. You should read up on the Shim Generation section +below though to familiarize yourself on what to do with GUI applications +and/or ignoring shims (also known as batch redirects). + +### Including the Software Installer in the Package + +Sometimes called embedding the binaries, there are functions in the automation scripts you can call that will use the installers directly from the package instead of downloading first. This makes for the most reliable and deterministic packages, but ensure you have the the software first if publishing to a public location (like the community package repository). + +### Automation Scripts + +You have a powerful use of Chocolatey, as you are using PowerShell. So you can do just about anything you need. Choco has some very handy that you can use, these are sometimes called +. + +## Table of Contents + +1. [Rules](#rules-to-be-observed-before-publishing-packages) +1. [Encoding](#character-encoding) +1. Learning about NuGet (and Chocolatey) Packages in general - [Information](#okay-how-do-i-create-packages) and [Nuspec](#nuspec) +1. [Description/Release Notes Recommendations](#package-description-and-release-notes) +1. [Limit Windows Versions](#install-only-on-some-versions-of-windows) +1. [Install paths](#installation-paths) +1. [Upgrading](#upgrading) and [Uninstalling](#uninstalling) +1. [Naming your package](#naming-your-package) +1. [Versioning](#versioning-recommendations) (and [package fix version notation](#package-fix-version-notation)) +1. [Icons](#package-icon-guidelines) +1. [Exclude executables from shims](#how-do-i-exclude-executables-from-getting-batch-redirects) +1. [Make shim for GUI application](#how-do-i-set-up-batch-redirects-for-applications-that-have-a-gui) +1. [Localization](#internationalization-and-localization-of-packages) +1. [Building](#build-your-package) / [Testing](#testing-your-package) / [Pushing](#push-your-package) +1. +1. + +## Quick Start Guide + +If you think you got what it takes and just want to know the basic steps to get a package out, there is a special for you. + + + This doesn't exempt you from observing the rules, requirements and guidelines (noted below). + + +## Rules to be Observed Before Publishing Packages + +There are a few rules that you have to follow before pushing packages to chocolatey.org: + +1. **Don't package illegal software.** Packages of software that is illegal in most countries in the world are prohibited to publish on Chocolatey.org. This applies in particular to software that violates the copyright, pirated software and activation cracks. Remember that this also affects software that is especially designed to accomplish software piracy. +1. **Do not include software in a package that you don't have the right to distribute.** Please see for more information. Any package found not in compliance with this will be removed immediately. Instead you can download binaries from official distribution locations at runtime. +1. **Packaging commercial or trial software?** Clearly state this in the package description. Does it require an activation key? Is there a trial period if you don't have a key? How long is this trial period? +1. **Only post publicly relevant packages.** You should consider whether this package is useful for others. If that is not the case, it shouldn't be published on Chocolatey.org. Reasons for that can be if the package would require a very customized configuration. You can host your personal packages on [MyGet](https://www.myget.org/) and still be able to install them with Chocolatey using the `-source` parameter. +1. **Do not publish junk or malware** packages. +1. **Don't package software _containing_ malware.** Packages of software that comes with bundled adware, spyware or other unrelated software that installs even in silent mode, are not allowed. But if you can figure out how to install the desired software without this unrelated software, it is allowed to publish the package. That can be accomplished for example with additional command line switches or by adding specific values to the registry. Examples of packages which make use of this are [PDFCreator](https://github.com/stack72/MyChocolateyPackages/tree/master/PDFCreator) and [CCleaner](https://github.com/tonigellida/chocolateyautomaticpackages/tree/master/ccleaner). +1. **Don't package software that is already packaged**. Use the search function in the [Chocolatey Community Repository](https://community.chocolatey.org/packages) and look if there is already a package for the desired software. If you would like to improve the already existing package or if you have suggestions, just contact the package maintainer or open a pull request at the maintainer’s package repository. +1. **Don't include other required software if there's a package of it.** If a package requires other software of which there is already a package, the already existing package should be used as [dependency](http://docs.nuget.org/create/nuspec-reference#specifying-dependencies) instead. +1. **Split dependencies into multiple packages.** Try to split up packages as much as possible. If for example a program comes with additional modules/installers that are optional, make different packages for them instead of including all the things into one package. This idea is already widely applied for Linux packages, because it leads to a more lightweight system and reduces potential issues and conflicts. +1. **Use a simple intuitive lowercase name for the package**. See the [package naming guidelines](#naming-your-package) for details. (If you are a reviewer/moderator, this is considered a guideline). + +Is your package unqualified for the Chocolatey feed, but you like to be able to install it through Chocolatey? One alternative would be to host your package on MyGet. See . + +## Character Encoding + +- **Use the UTF-8 character encoding** for the `*.nuspec` and `*.ps1` files. If you don’t respect this rule, some characters are not displayed correctly in the [Chocolatey Community Repository](http://community.chocolatey.org/packages), because if defaults to `UTF-8`. +- **Byte Order Mark (BOM) is optional for `*.nuspec`.**. A `BOM` is not required but it won't hurt anything if it is found. +- **PowerShell scripts need to be saved in UTF-8 with `BOM`**. PowerShell is ignoring the standards and needs a `BOM` in order to recognize scripts as `UTF-8`. Otherwise it processes non `ASCII` characters incorrectly. +- Don’t use the default Windows Editor. While newer versions of Notepad have improved its ability to handle line endings and UTF-8 w/out BOM, it is still behind in capabilities as compared to other editors. Alternatives: + - [Visual Studio Code](https://community.chocolatey.org/packages/vscode) + - [Notepad++](http://community.chocolatey.org/packages/notepadplusplus) + - [Geany](http://community.chocolatey.org/packages/geany) +- Use this **XML declaration**: ``. + + + There is a lot of confusion in the world of character encodings: For example, `ANSI` is an incorrect term for the internal Windows character encodings, e. g. `Windows-1252`. But you should not use this encoding family anyway. + + +## What Version of the Software Should I Package? + +The main release of a product versions are usually sufficient. If there are also beta versions available and you would rather have that, then please create both the official release and the beta (and set the beta as a prerelease when pushing the item to community.chocolatey.org). Regular users of packages may want to use official releases only and not betas. + + + Both of these have the SAME package id, just different versions. + + +## How do I Create Packages? + +There are three main elements to a Chocolatey package. Only the nuspec is required (#1 below). + +1. +1. - check out the +1. any application files to include (it is highly suggested that you are the author in this case or you have the right to ). EXE files in the package/downloaded to package folder from chocolateyInstall.ps1 will get a link to the command line. +1. chocolateyUninstall.ps1, for uninstalling your package. See for functions available in your script. + + + If your package does not have compatibility with the then you must include checks for the required PowerShell version and error if it is not installed. Alternatively, to add a dependency for the required Powershell version. + + +There is a video showing the creation of a package: [http://www.youtube.com/watch?v=Wt_unjS_SUo](http://www.youtube.com/watch?v=Wt_unjS_SUo) +The video is a bit outdated in showing the contents of the chocolateyInstall.ps1. Have a look at what the [chocolateyInstall.ps1](https://github.com/ferventcoder/chocolatey-packages/blob/master/manual/windirstat/tools/chocolateyInstall.ps1) looks like now: + +```powershell +$packageName = 'windirstat' +$fileType = 'exe' +$url = 'http://prdownloads.sourceforge.net/windirstat/windirstat1_1_2_setup.exe' +$silentArgs = '/S' + +Install-ChocolateyPackage $packageName $fileType $silentArgs $url +``` + +## When Will my Custom Scripts be Run? + +The table below shows which scripts are available, and which command(s) will cause them to be run. + +Script Name | Install | Upgrade | Uninstall +-----------------------------------------------|---------|---------|---------- +chocolateyBeforeModify.ps1 | | Yes | Yes +chocolateyInstall.ps1 | Yes | Yes | +chocolateyUninstall.ps1 | | | Yes + + + In the upgrade scenario, the chocolateyInstall.ps1 script will be the one included in the new package. The chocolateyBeforeModify.ps1 script will be the one from the previously installed package. + + +## Nuspec + +The `Chocolatey` Windows package manager uses the same infrastructure as [NuGet](http://nuget.org/), the Visual Studio package manager by Outercurve Foundation (sponsored by Microsoft). Therefore packages are based on the same principles. One of those is a package description (specification) in `xml` format, known as the `Nuspec`. + +The `Nuspec` contains basic information such as the version, license, maintainer, and package dependencies. `Chocolatey` includes additional optional functionality on top of [NuGet's Nuspec format](http://docs.nuget.org/docs/reference/nuspec-reference) - the best way to determine currently supported features is to create a test package, and look at the generated nuspec file. + +`choco new testpackage` + + + If your package uses recently introduced functionality, you might want to include `chocolatey` as a dependency with the version being the lowest version that has the introduced functionality. Otherwise the installation could fail for users with an older version of `Chocolatey` installed. + + +You can indicate the `Chocolatey` dependency like any other dependency. For example: + +```xml + + + +``` + +Logically, the version is based on the lowest compatible version. But if you don't know and used a lot of sorcery in your package, depend on the version of `Chocolatey` that you succesfully tested your package on. + +**See also:** [NuGet Version Reference](http://docs.nuget.org/docs/reference/versioning) + +## How do I Create a New Package? + +- **Generate new package**: + - `choco new -h` will get you started seeing options available to you. + - Once you figured out all of your options, you should move forward with generating your template. + +## Install Only on Some Versions of Windows + +Right now if the software the package installs is only supported on particular versions of Windows, you should absolutely fail the package. An installed package indicates success. If you pass a warning message but don't also throw an error, that means the package installed successfully. Folks using the package are going to be confused because they will then expect that the underlying software is also installed. The software itself may throw a cryptic error, which will lead to questions from the community about why it is broken (when it is just unsupported). Do yourself a favor and check the version of Windows and throw an error if it is not a supported version. Under no circumstances should you bypass with a warning, because a warning is still a success. + +There is at least one noted exception to this and that is low-level packages that are meant as dependencies that need to be present even if they do not install anything. These are things like KBs that only need to be installed on some versions of Windows. If the package failed and it was a dependency of a higher level package that installed software, it would cause issues attempting to install that software on different versions of Windows. Since about 5% of the packages apply to this exception, stick with the above thoughts for packages. + + + We will ultimately enhance the nuspec and take care of this for you automatically. Until we get there, follow the above avenue. + + +## Installation Paths + +As the package maintainer, you decide where the packaged application is installed or extracted to. Depending on your type of application (see _"What distinction does Chocolatey make between an installable and a portable application?"_ at the bottom of the ) there are a couple of suitable locations (not listed in any particular order): + +### 1. The default installation path of your .msi/.exe setup file + +The original creator probably had a reason for choosing a specific default installation path. +If you think, the user should be able to customize this path and you, the package maintainer, know how to pass a custom path on to the installer, then you should use `%ChocolateyBinRoot%`. + +### 2. The Package Directory in `%ChocolateyInstall%\lib\mypackage` + +You can extract the application within the package directory itself (or even ship an extracted version with the package). This allows Chocolatey to automatically find executables and put those on `%path%`. + +### 3. Path Provided by the `Get-ToolsLocation` Helper + + + It was previously possible to use the helper `Get-BinRoot` for backwards compatibility. This is still possible in v1.0.0, however its use is not recommended as the function is now deprecated, and will be removed in v2.0.0. + + +The path returned by the helper `Get-ToolsLocation` can be used as the parent directory for the installation. `Get-ToolsLocation` will return the value of the environment variable `%ChocolateyToolsLocation%`. If the value does not contain a drive reference, the system drive will be prepended. If the environment variable is not set, the default path (`C:\tools`) will be returned. + +As an example, [GeoServer](https://github.com/AdmiringWorm/chocolatey-packages/blob/0f3b93ab7b067b265a06349a68297d07b1598e64/automatic/geoserver/tools/chocolateyuninstall.ps1#L8) uses `%ChocolateyToolsLocation%`. If the environment variable is not set, it will be set to `c:\tools` and GeoServer will install to `C:\tools\GeoServer` by default. If `%ChocolateyToolsLocation%` is set to "C:\Common\bin", GeoServer installs to `C:\Common\bin\GeoServer`. + +`%ChocolateyToolsLocation%` gives the Chocolatey user a way of controlling where packages are installed. If you want to allow customizing the installation path, then this is currently the way to go. + +### Make it clear in the package description + +No matter how you decide, you are advised to state the default installation directory in your package description. This prevents confusion about where the application will end up being installed. + +If you allow customizing the installation path, then append instructions on how to do that, too. + +### Windows Environment Variables + +Chocolatey installations are advised to be performed while running "as administrator". Because of this it is important that you understand that some windows environment variables will be pinned to the administrator user and not the installation user at least +one circumstance. + +On many systems there are multiple accounts. The issue can occur on a system where there is an admin user with an account type of "Administrator", let's call this user **admin**. There is another user with an account type of "Standard User" lets call this second user **user**. + + + "Administrator" and "Standard User" are the 2 account types that Windows 10 supports. + + +When **admin** chooses to run a `cmd` shell with elevated privileges by right clicking and selecting "Run as administrator". **admin** will be warned by "User Access Control" that they are elevating privileges via a dialog that **admin** can dismiss. The command shell will run the shell with administrator rights from the **admin** account. All good! + +When **user** chooses to run a `cmd` shell by right clicking and selecting "Run as administrator", **user** will be asked to enter the credentials for **admin** account to gain administrator rights. **user** will need to enter **admin**'s credentials and then the command shell will run the shell with administrator rights from the **admin** account. Wait... what? + +Yes, really. An elevated command shell for **user** will run as if it is the **admin** user! + +That means that when your installer depends on any environment variables to find install locations there is a scenario where the environment variables are from a different user (e.g. **admin**) than the user installing the package. + +The known affected environment variables are: `APPDATA`, `LOCALAPPDATA`, `TEMP`, `TMP`, `USERNAME`, `USERPROFILE` + +Example Settings for a user named "administrator": + +``` +APPDATA=C:\Users\administrator\AppData\Roaming +LOCALAPPDATA=C:\Users\administrator\AppData\Local +TEMP=C:\Users\administrator\AppData\Local\Temp +TMP=C:\Users\administrator\AppData\Local\Temp +USERNAME=administrator +USERPROFILE=C:\Users\administrator +``` + +A simple way around this is to ask the user to set environment variables that can override environment variables. Or alternatively, instruct your users to set the necessary environment variables in the elevated privileges command shell. + +Example instructions: + +> Within the administrator command shell you will need to set 2 environment variables: +> +> ``` +> set LOCALAPPDATA=C:\Users\\AppData\Local +> set USERPROFILE=C:\Users\ +> ``` + +## Upgrading + +Prior to choco version 0.9.10, there is no dedicated automation script for upgrade scenarios. Instead, your script should support installing/upgrading on top of any previous versions of your package. + +More recent versions of choco (0.9.10+) give you the option of supplying a `chocolateyBeforeModify.ps1` script. +If applicable, the version of this script from the currently installed package will be run before subsequent +chocolateyInstall or chocolateyUninstall scripts. + +## Uninstalling + +Uninstalling is handled by a `chocolateyUninstall.ps1` script, which should be in your package's `tools` directory, next to . All the usual are available. If your package doesn't uninstall cleanly, people will get grumpy because they'll have to manually clean up after you. Be a good human being and write an uninstaller. + +## Dependency Chaining + +You can make packages that depend on other packages just by adding those dependencies to the nuspec. Take a look at [ferventcoder.chocolatey.utilities nuspec](https://github.com/ferventcoder/chocolatey-packages/blob/master/manual/ferventcoder.chocolatey.utilities/ferventcoder.chocolatey.utilities.nuspec). + +## Avoid Folders Named "content" + +Do not use a folder named "content" in your package. NuGet attaches a special meaning to this folder and will not allow you to have dependencies on packages that have content folders without also having a content folder. It's turtles all the way down until we or NuGet removes this limitation. + +## Naming Your Package + +The **title** of your package (`` tag in the nuspec) should be the same as the name of the application. +Follow the official spelling, use upper and lower case and don’t forget the spaces. +Examples of correct package titles are: _Google Chrome_, _CCleaner_, _PuTTY_ and _FileZilla_. +The title will appear on the left side in the package list of the Chocolatey Community Repository, followed by the version. + +There are some guidelines in terms of the package **ID** (`<id>` tag in the nuspec): + +* **Use only lowercase letters**, even if you used uppercase letters in the package title. + (This is considered a guideline because it is correctable in other ways). + Once a package is submitted (even prior moderation), the Chocolatey Community Repository will always show the id with the casing of the first package version. + In addition, changing the casing of the package id may have negative side effects on dependencies (note: this last statement needs verified). +* If the original application name consists of compound words without spaces (CamelCase), just as _MKVToolNix_, _TightVNC_ and _VirtualBox_, the package id’s are simply the same (but **lowercase** of course): `mkvtoolnix`, `tightvnc`, and `virtualbox`. +* If the name of the application contains multiple words separated by spaces, such as _MusicBrainz Picard_ or _Adobe Reader_, replace the spaces with the hyphen-minus character “-” (U+002D), or just omit them. + **Don’t use dots**. + Dots should be used only if the original application name contains dots (for example, _Paint.NET_). + Hence the correct id’s of the previously mentioned applications can be `musicbrainz-picard` or `adobereader`. + We recommended you use the hyphen method when there are long package names to ensure they remain readable. +* For sub-packages, use the hyphen-minus character “-” (U+002D) as the separator, not a dot. + Sub-packages are intended for separate packages that include extensions, modules or additional features/files for other applications. + Therefore `keepass-langfiles` is a proper package id, because it adds the language files for the main application which in this case is _KeePass_. + Another example is `libreoffice-help` for the help pack for _LibreOffice_, the open source office suite. +* If you want to package an open source application, first search for any pre-existing packages on services like [Repology](https://repology.org/). + If there are already published packages for the application on another repository, **use the same package id**. + This will make it easier for users which work with multiple platforms, so they don't have to remember and use different package names. +* Do not use `chocolatey` in your package ID as this indicates an official package. You can use `choco` instead, but you must include the word 'Unofficial' in the package title. + +These guidelines are already commonly applied on packages for all major Linux distributions, because they lead to a more consistent user experience for software repositories, result in easier to remember package IDs, and reduce unnecessary considerations on naming packages for package creators. + +Note that some packages in the Chocolatey Community Repository don't follow these guidelines; many of these were created before these guidelines were introduced. +New packages should follow the guidelines to improve the overall experience for users going forward. + +If you are going to offer a package that has both an installer and an archive (zip or executable only) version of the application, create three packages - see <Xref title="Portable vs Installable" value="faqs" anchor="what-distinction-does-chocolatey-make-between-an-installable-and-a-portable-application" /> and <Xref title="Install, Portable, and Meta/Virtual Packages" value="faqs" anchor="what-is-the-difference-between-packages-no-suffix-as-compared-to.install.portable" />. + +### Naming Packages to Allow for Side-by-Side Installation + +For some software, it is expected that users may want multiple different versions installed simultaneously. +This has commonly been seen with software like Python which offer some kind of runtime dependency that other scripts or applications depend on. + +In the past, Chocolatey CLI supported a "side-by-side" installation method which could be used for this purpose to install multiple distinct versions side-by-side, on the same machine. +This has been deprecated and is no longer supported in version 2.0.0 due to many issues with the use and implementation of the feature. + +#### If the Software You're Creating a Package for Expects **Side-by-Side Installations of Different Versions** + +1. Create _separate package IDs_ for each major version (or major + minor version, depending on the expectations of users) which include the version number in the ID. + For example, if the package ID would be `python`, the package for major version 2 would be `python2`, or a package for specifically the 2.7 branch might be `python27` or `python2-7`. + These individual versioned packages can be updated as normal, as long as that major and/or minor version is still receiving further updates. +1. Create a <Xref title="**metapackage**" value="getting-started" anchor="terminology" /> for the overall product with a package version for each of the versioned packages. + In other words, create another package (this time without a version number in the ID), which contains only a `nuspec` file and add a dependency on the versioned package. + Following the above example for Python, we'd create a package with the ID `python` at version `2.0.0` that takes a dependency on the `python2` package. +1. New versions of the metapackage should be published for "sub-versions" of the dependency package as well. + For example, if Python version `3` is released, we'd create a new version of the `python` package with its version set to `3.0.0`, which depends on a new `python3` package. + +#### If the Software You're Creating a Package for Expects **Side-by-Side Installations of the Same Version** + +A possible example might be where multiple different instances of the software are being installed into different install directories. + +Chocolatey does not currently support this functionality. +This functionality can be mimicked by making use of `--force` to forcibly overwrite an already-installed package and providing an argument or package parameter that the package can use to direct the installation to install into a different directory. +However, Chocolatey will only be aware of the most-recently installed copy of the software, and will only be able to provide updates to that single installation of the software in most cases. +As a result, this particular configuration is not supported. + +A potential workaround for users maintaining their own package repositories is to maintain separate instances of the same package under different package IDs, where each package ships the same software, but is scripted to install to a different directory. +For example, you can create a `python3-localtoolsfolder` and a `python3-programfilesfolder` package which have the same contents, with only slight differences in the parameters passed to the install functions to ensure they install in the desired locations. +The recommended naming conventions here are similar to sub-packages, where the package is named after the primary package ID followed by a dash and a discriminator, likely named after the install location or referencing the purpose of the additional package(s). + +## Package Description and Release Notes + +The `<description>` of the package should contain a short text or at least a few words about the software for which the package is made. Here are a few things that should be respected: + +- The description should always be written in English, even if the packaged software does not provide an UI in English. You can also include the software’s description in its original language, but insert it after the English description. +- The description should not just contain a repetition of the package name. +- It should not just consist of a link where more information can be found. For that purpose there’s already `<projectUrl>`. +- The contents of `<description>` and also `<releaseNotes>` are parsed as Markdown, so don’t insert line breaks in the middle of sentences. Remember to add empty lines to separate paragraphs and add an empty line before a list. + +## Versioning Recommendations + +Versioning can be both simple and complicated. The best recommendation is to use the same versioning that the installable/portable application uses. With Chocolatey you get four version segments. If the application only uses 1, 2 or 3 version segments, follow suit. + +If the 4th segment is used, some folks like to drop the segment altogether and use that as only the package fix notation using one of the notations in the next section. There is no recommendations at this time. + +### Package Fix Version Notation + +Package fix version notation ONLY applies when you are making a fix to the package because the existing version of a package is incorrect in some way. So if the software is `1.1.0`, in a normal scenario the package version should be `1.1.0`. If you find that the `1.1.0` package has an issue and you need to fix the package but keep the same version of the software, that is where package fix version notation comes into play. You would end up with both a `1.1.0` package and a `1.1.0.YYYYMMDD` version of the package. + +<Callout type="info"> + This doesn't apply to packages on the community feed (aka https://community.chocolatey.org/packages) that are still under review (not yet approved). Please read the instructions given in email for resubmitting the same version. +</Callout> + +If you need to fix an approved package for some reason, you can use the fourth version element (aka segment) for a package fix notation. There are two recommended methods of package fix version notation: + +- **Date (Year/Month/Day)** - Some folks use year month day package fix notation (yyyyMMdd as in 20120627 seen as 1.2.0.20120627) +- Sequential - **Not recommended** - Some folks use sequential numbering (0, then 1, etc as in 0 for no fix, 1 for first fix and so on seen as 1.2.0.0 and 1.2.0.1). + +Date Package Fix Version Notation is recommended because one can ascertain what it is immediately upon seeing it, where sequential is not obvious on sight whether it is part of the software versioning or something special with the package. + +Package fix version notation is only acceptable in the fourth segment. Do not use any of the other segments for package fix notation. If an application only uses 1 or 2 version segments, add zeros into the other segments until you get to the 4th segment (i.e. 1.0.0.20120627). + +When the fourth segment is already used, it is recommended to add two zeroes (00) to the end of the version. Then when you need to fix, you just increment that number. So if the package was ruby and the version was 2.0.0-p353, the package is 2.0.0.35300 (adding the two zeroes at the end). Then a fix would be 2.0.0.35301 and so on. + +<Callout type="warning"> + If you decide to add a secondary set of numbers to the fourth segment, you MUST ALWAYS include that secondary set of numbers while the other three version segments are the same. The reason - if you fix `.1` to `.100`, then release `.2`, `.100` is greater than `.2` because versioning doesn't look at the ".", only the number in the element. So `100` is greater than `2`. +</Callout> + +## Internationalization and Localization of Packages + +For Chocolatey, internationalization and localization of packages is very important, because it has users from all over the world. Many applications support multiple languages, but they use several different methods to achieve that. Therefore, there is no standard how internationalization/localization has to be integrated into packages. However, here are a few examples of packages that use various techniques. You can use them as inspiration for new packages: + +* The ideal situation is when an application determines the user's system language and automatically installs with that language. Then you don't have to take any action relating to localization, because the application already handles that. Examples of such applications are [VLC Media Player](https://community.chocolatey.org/packages/vlc) and [LibreOffice](https://community.chocolatey.org/packages/libreoffice). +* When an application provides different installers for different languages, you should determine the system language and download the appropriate installer. The package for [Mozilla Firefox](https://community.chocolatey.org/packages/Firefox) ([source code](https://github.com/chocolatey-community/chocolatey-packages/tree/master/automatic/Firefox)) uses this method. +* Sometimes an application installer or executable has already integrated all supported languages, but doesn't automatically select the system language during a silent install. Often you can pass an additional install parameter to select the desired language. This is used for example in the [CCleaner](https://community.chocolatey.org/packages/ccleaner) package ([source code](https://github.com/tonigellida/chocolateyautomaticpackages/tree/master/ccleaner)). +* Some application use separate language files which must be downloaded separately and put somewhere in the application directory. It is best when you create a separate package for the language files. If your package id is `packageid`, then call it `packageid-langfiles`. The [language files package for KeePass](https://community.chocolatey.org/packages/keepass-langfiles) is an example how this can be achieved. + +## Package Icon Guidelines + +If there is an icon which is suitable for your package, you can specify it in the `<iconUrl>` tag in the nuspec. But there are a few things you should consider: + +* **Avoid hotlinking icons from sites where you don’t have control over the file.** If you have a packages repository (recommended), use your own copy of the icon and put it there. +* **Use a static CDN for icon URLs that permits you to serve files hosted in a repository on GitHub.** Some CDN services cache files permanently and it's therefore best to use a specific tag or commit URL, not a branch URL. While we don't make any recommendations about specific services, the more popular ones used by maintainers are [jsDelivr](https://www.jsdelivr.com/), [Statically](https://statically.io/) and [Githack](https://raw.githack.com/). +* **Avoid using GitHub raw links** (`https://raw.githubusercontent.com/...`). They are not intended to be used as CDN. +* **Use the software’s icon if one is available, not the logo.** This blog post explains the difference between logos and icons: http://blog.designcrowd.com/article/353/differences-between-logos-and-icons. If the software of your package doesn’t have an icon, but a logo with text and an image, you can extract the image with your favorite image editor and use that as package icon. An example is [MySQL’s dolphin](https://community.chocolatey.org/packages/mysql). +* **Use package icons with at least 128 pixels in width or height** if available. However, avoid very high resolutions, because this would only unnecessarily increase the page load time. If there are only icons with less than 128 pixels available, choose the icon with the highest resolution you can find without upscaling it. Don’t use low resolution favicons as package icons. +* Use icons with transparent background if available. +* Don’t use distorted or blurry icons. +* The package list in the Chocolatey Community Repository shows the icons with a maximum of 48 pixels in width/height. Application logos with very detailed graphics that are barely visible at that dimension are not suitable as package icons. +* **PNG is the preferred format** for raster package icons. Avoid ICO, GIF and JPEG graphics. +* Good sources for package icons are the official desktop icons of the corresponding application you want to make a package of. The icons can be extracted from the app executables using tools like [BeCyIconGrabber](https://community.chocolatey.org/packages/becyicongrabber). Remember to take the icon with 128 px or more and save it as PNG file. + +The icon shown on the community.chocolatey.org package page is saved, and served, locally to mitigate against cross scripting attacks and to prevent getting _non HTTPS assets_ errors on the website. Sometimes the page loads faster than the image can be served and the default image gets cached and as a result the new package icon may not be shown until you clear the browser cache for community.chocolatey.org and wait 3 hours before reloading the page. + +<a name="how-do-i-exclude-executables-from-getting-batch-redirects"></a> + +## How Do I Exclude Executables from Getting Shims? + +If you have executables in the package or brought into the package folder during PowerShell run and you want to exclude them you need to create an empty file named exactly like (**case sensitive**) the executable with `.ignore` suffixed on the end in the same directory where the executable is or will be. + +Example: In the case of `Bob.exe` you would create a file named `Bob.exe.ignore` and that file would not get a redirect batch link. The Chocolatey package has an example of that. To further expand, `bob.exe.ignore` would not work because it doesn't have the correct casing. + +Here's a great [programmatic example](https://github.com/ferventcoder/chocolatey-packages/blob/6ea7c087bd999d428a564b5d7e236ae998ef72e9/automatic/git.commandline/tools/chocolateyInstall.ps1#L13-L20): + +```powershell +$files = get-childitem $installDir -include *.exe -recurse + +foreach ($file in $files) { + #generate an ignore file + New-Item "$file.ignore" -type file -force | Out-Null +} +``` + +<a name="how-do-i-set-up-batch-redirects-for-applications-that-have-a-gui"></a> +## How do I set up shims for applications that have a GUI? +If you don't want to see a hanging window when you open an application from the command line that was set up with Chocolatey, you want to create a file next to the executable that is named exactly the same (**case sensitive**) with `.gui` suffixed on the end. + +Example: In the case of `Bob.exe` you would create a file named `Bob.exe.gui` and that file would be set up as a GUI application so the window will call it and then move on without waiting for it to finish. Again, `bob.exe.gui` would not work because it doesn't have the correct casing. + +## Build Your Package + +Open a command line in the directory where the nuspec is and type <Xref title="`choco pack`" value="choco-command-pack" />. That's it. + +## Testing Your Package + +<Callout type="info"> + We strongly suggest the following should be performed in a VM and not on your machine. +</Callout> + +<Callout type="info"> + Testing your package can be done in the same way as the verifier - take a look at [Chocolatey Verifier Testing](https://github.com/chocolatey-community/chocolatey-test-environment). +</Callout> + +To test the package you just built, open a command line shell and navigate to the directory where the `*.nupkg` file is located. Then type: + +```powershell +choco install packageName --debug --verbose --source . +``` + +This will install the package right out of your source. As you find things you may need to fix, using `--force` (`-f`) will remove and reinstall the package from the updated `*.nupkg`. If you are specifically testing `chocolateyBeforeModify.ps1`, you need to be testing upgrade and uninstall scenarios. You need to install a version of the package with this file **first** as before modify is like uninstall, it runs from the installed package, not the package you are installing (like `chocolateyInstall.ps1` does). + +<Callout type="info"> + Using Force `--force` (`-f`) should only be done in subsequent testing where you are reinstalling the same package that you've changed and should NOT be used in regular use scenarios. It should definitely not be in scripts. +</Callout> + +<Callout type="info"> + If you are using a Semver dash in your package version (such as 1.0.0-beta), you will need to use the `--pre` switch or else you will get *Unable to find package* errors from `choco install`. You can also specify `-version 1.0.0-beta` to try to install that exact version. +</Callout> + +`.` points to the current directory. You can specify multiple directories separated by a semicolon; + +When your `nuspec` specifies dependencies that are not in your source, you should add their paths to the source directory. E.g. in the case of Chocolatey itself: + +```xml +<dependencies> + <dependency id="chocolatey" version="0.9.8.20" /> +</dependencies> +``` + +You'll need to append the API path like so: +`--source "'.;https://community.chocolatey.org/api/v2/'"` (note the double quotes bookending the apostrophes here, use `%cd%` in cmd.exe or `$pwd` in Powershell.exe if `.` doesn't resolve). See <Xref title="passing options with quotes" value="choco-commands" anchor="how-to-pass-options-switches" />. + +<Callout type="info"> + If you need to do this, please ensure you run `choco pack` first. This method of passing a source won't work calling a nuspec or nupkg directly as it will override the source passed to the local folder. +</Callout> + +You can also use the `--debug` switch on `choco install` to provide more information. + +<Callout type="info"> + Do not call install with `.nupkg` - pointing to a file explicitly overrides source. You must call your install with the package name, not the nupkg file and location. You've already specified for choco to look in a local source with `--source "'.;https://community.chocolatey.org/api/v2/'"`. Call `choco install dude --source "'.;https://community.chocolatey.org/api/v2/'"`, not `choco install .\dude.nupkg --source "'.;https://community.chocolatey.org/api/v2/'"`. +</Callout> + +### Alternative Testing Strategy + +You can also type `choco install --force --debug --verbose path/to/nuspec` and choco will build the nupkg and attempt to install it. + +<Callout type="info"> + This is not recommended if you are passing install arguments or package parameters due to some weirdness, and definitely does not work with passed sources as it need to override that with the local folder once it builds the package. Most likely you will want to stick with the recommended strategy. +</Callout> + +## Push Your Package + +To push your package after you have built and tested it, you type `choco push packageName.nupkg --source sourceLocation` where **packageName.nupkg** is the file name of the nupkg that was built and **sourceLocation** is the location of the source you want to push to (for example, `--source "'https://push.chocolatey.org/'"` for the Chocolatey Community Repository). +You must either have set an API key for the target URL, or provide an API key directly to the `push` command via the `--api-key` option. +For example, if pushing to the Chocolatey Community Repository, you will need to have previously set an API key for `https://push.chocolatey.org/` (`choco apikey add --source "'https://push.chocolatey.org/'" --key "'API_KEY_HERE'"`). +For more information, see the reference documentation for <Xref title="`choco push`" value="choco-command-push" />. + +As of Chocolatey CLI v2.0.0, you can set the `defaultPushSource` configuration value if you frequently push packages to the same source. +For example: `choco config set --name defaultPushSource --value https://push.chocolatey.org/` + +## Automatic Packaging? + +Yes - <Xref title="Automatic Packaging" value="automatic-packaging" /> + +## Becoming a Primary Maintainer of an Existing Package + +See <Xref title="Package Maintainer Handover" value="package-maintainer-handover" /> diff --git a/src/content/docs/en-us/create/cmdlets/index.mdx b/src/content/docs/en-us/create/cmdlets/index.mdx index 437840774a1..2855901ee75 100644 --- a/src/content/docs/en-us/create/cmdlets/index.mdx +++ b/src/content/docs/en-us/create/cmdlets/index.mdx @@ -1,14 +1,16 @@ --- -order: 35 +order: 45 xref: powershell-cmdlet-reference -title: PowerShell Cmdlet Reference -description: PowerShell Cmdlet Helpers Reference +title: Chocolatey PowerShell Cmdlet Reference +description: Chocolatey PowerShell Cmdlet Reference --- import Xref from '@components/Xref.astro'; # PowerShell Cmdlet Helpers Reference -See also: <Xref title="PowerShell Functions Reference" value="powershell-reference" /> +> :choco-info: **NOTE** +> +> As we migrate our PowerShell functions to cmdlets, please see the <Xref title="PowerShell Functions Reference" value="powershell-reference" />. ## Summary diff --git a/src/content/docs/en-us/create/create-packages-quick-start.mdx b/src/content/docs/en-us/create/create-packages-quick-start.mdx index b33d95085e3..bf06d2a9e2e 100644 --- a/src/content/docs/en-us/create/create-packages-quick-start.mdx +++ b/src/content/docs/en-us/create/create-packages-quick-start.mdx @@ -1,8 +1,8 @@ --- -order: 20 +order: 10 xref: create-packages-quick-start title: Quick Start -description: The quick start guide on creating Chocolatey packages +description: The quick start guide to creating Chocolatey packages. --- import Callout from '@choco/components/Callout.astro'; import Iframe from '@choco/components/Iframe.astro'; diff --git a/src/content/docs/en-us/create/create-packages.mdx b/src/content/docs/en-us/create/create-packages.mdx index 7a1f2cfb309..f7798e0ec19 100644 --- a/src/content/docs/en-us/create/create-packages.mdx +++ b/src/content/docs/en-us/create/create-packages.mdx @@ -1,517 +1,157 @@ --- -order: 10 +order: 20 xref: create-packages -title: Create Packages -description: How to start creating your own Chocolatey packages +title: Creating Packages +description: How to create Chocolatey packages. --- import Callout from '@choco/components/Callout.astro'; import Iframe from '@choco/components/Iframe.astro'; import Xref from '@components/Xref.astro'; -# Creating Chocolatey Packages +Before you start, ensure you understand <Xref title="what Chocolatey Packages are" value="getting-started" anchor="what-are-chocolatey-packages" />. -## Summary - -See <Xref title="What are Chocolatey Packages?" value="getting-started" anchor="what-are-chocolatey-packages" /> first. - -<Callout type="info"> - When you host internal packages, those packages can embed software and/or point to internal shares. You are not subject to software distribution rights like the packages on the community feed, so you can create packages that are more reliable and secure. -</Callout> - -First you should determine if you are making a self-contained package or (also) using automation scripts. You should also consider creating <Xref title="automatic packages" value="automatic-packaging" /> for the best maintainability over time. - -1. Run `choco new -h` to get a feel for what you can pass e.g `choco new bob` (to create a package named `bob`) -1. Note all the rules below. This will help you, especially in publishing to the community feed (https://chocolatey.org) - -### Self-Contained? - -If you have a self-contained package, you can remove the automation scripts -entirely and just include the runtime executables, they will automatically get shimmed, -which puts them on the path. Ensure you have the <Xref title="legal right to distribute" value="legal" /> -the application though. You should read up on the Shim Generation section -below though to familiarize yourself on what to do with GUI applications -and/or ignoring shims (also known as batch redirects). - -### Including the Software Installer in the Package - -Sometimes called embedding the binaries, there are functions in the automation scripts you can call that will use the installers directly from the package instead of downloading first. This makes for the most reliable and deterministic packages, but ensure you have the <Xref title="legal right to distribute" value="legal" /> the software first if publishing to a public location (like the community package repository). - -### Automation Scripts - -You have a powerful use of Chocolatey, as you are using PowerShell. So you can do just about anything you need. Choco has some very handy <Xref title="built-in functions" value="powershell-reference" /> that you can use, these are sometimes called -<Xref title="helpers" value="powershell-reference" />. - -## Table of Contents - -1. [Rules](#rules-to-be-observed-before-publishing-packages) -1. [Encoding](#character-encoding) -1. Learning about NuGet (and Chocolatey) Packages in general - [Information](#okay-how-do-i-create-packages) and [Nuspec](#nuspec) -1. [Description/Release Notes Recommendations](#package-description-and-release-notes) -1. [Limit Windows Versions](#install-only-on-some-versions-of-windows) -1. [Install paths](#installation-paths) -1. [Upgrading](#upgrading) and [Uninstalling](#uninstalling) -1. [Naming your package](#naming-your-package) -1. [Versioning](#versioning-recommendations) (and [package fix version notation](#package-fix-version-notation)) -1. [Icons](#package-icon-guidelines) -1. [Exclude executables from shims](#how-do-i-exclude-executables-from-getting-batch-redirects) -1. [Make shim for GUI application](#how-do-i-set-up-batch-redirects-for-applications-that-have-a-gui) -1. [Localization](#internationalization-and-localization-of-packages) -1. [Building](#build-your-package) / [Testing](#testing-your-package) / [Pushing](#push-your-package) -1. <Xref title="Maintainer magic - automatically updating packaging" value="automatic-packaging" /> -1. <Xref title="Taking over existing package" value="package-maintainer-handover" /> +Run `choco new -h` to get a feel for what you can pass e.g `choco new bob` (to create a package named `bob`). Once you have the new templated package, you can follow the information on this page to update the files and create your Chocolatey package. ## Quick Start Guide -If you think you got what it takes and just want to know the basic steps to get a package out, there is a special <Xref title="Quick Start Guide" value="create-packages-quick-start" /> for you. - -<Callout type="info"> - This doesn't exempt you from observing the rules, requirements and guidelines (noted below). -</Callout> - -## Rules to be Observed Before Publishing Packages - -There are a few rules that you have to follow before pushing packages to chocolatey.org: - -1. **Don't package illegal software.** Packages of software that is illegal in most countries in the world are prohibited to publish on Chocolatey.org. This applies in particular to software that violates the copyright, pirated software and activation cracks. Remember that this also affects software that is especially designed to accomplish software piracy. -1. **Do not include software in a package that you don't have the right to distribute.** Please see <Xref title="Distribution Rights" value="legal" anchor="distributions" /> for more information. Any package found not in compliance with this will be removed immediately. Instead you can download binaries from official distribution locations at runtime. -1. **Packaging commercial or trial software?** Clearly state this in the package description. Does it require an activation key? Is there a trial period if you don't have a key? How long is this trial period? -1. **Only post publicly relevant packages.** You should consider whether this package is useful for others. If that is not the case, it shouldn't be published on Chocolatey.org. Reasons for that can be if the package would require a very customized configuration. You can host your personal packages on [MyGet](https://www.myget.org/) and still be able to install them with Chocolatey using the `-source` parameter. -1. **Do not publish junk or malware** packages. -1. **Don't package software _containing_ malware.** Packages of software that comes with bundled adware, spyware or other unrelated software that installs even in silent mode, are not allowed. But if you can figure out how to install the desired software without this unrelated software, it is allowed to publish the package. That can be accomplished for example with additional command line switches or by adding specific values to the registry. Examples of packages which make use of this are [PDFCreator](https://github.com/stack72/MyChocolateyPackages/tree/master/PDFCreator) and [CCleaner](https://github.com/tonigellida/chocolateyautomaticpackages/tree/master/ccleaner). -1. **Don't package software that is already packaged**. Use the search function in the [Chocolatey Community Repository](https://community.chocolatey.org/packages) and look if there is already a package for the desired software. If you would like to improve the already existing package or if you have suggestions, just contact the package maintainer or open a pull request at the maintainer’s package repository. -1. **Don't include other required software if there's a package of it.** If a package requires other software of which there is already a package, the already existing package should be used as [dependency](http://docs.nuget.org/create/nuspec-reference#specifying-dependencies) instead. -1. **Split dependencies into multiple packages.** Try to split up packages as much as possible. If for example a program comes with additional modules/installers that are optional, make different packages for them instead of including all the things into one package. This idea is already widely applied for Linux packages, because it leads to a more lightweight system and reduces potential issues and conflicts. -1. **Use a simple intuitive lowercase name for the package**. See the [package naming guidelines](#naming-your-package) for details. (If you are a reviewer/moderator, this is considered a guideline). - -Is your package unqualified for the Chocolatey feed, but you like to be able to install it through Chocolatey? One alternative would be to host your package on MyGet. See <Xref title="Hosting Chocolatey Packages on MyGet" value="hosting-chocolatey-packages-on-myget" />. - -## Character Encoding - -- **Use the UTF-8 character encoding** for the `*.nuspec` and `*.ps1` files. If you don’t respect this rule, some characters are not displayed correctly in the [Chocolatey Community Repository](http://community.chocolatey.org/packages), because if defaults to `UTF-8`. -- **Byte Order Mark (BOM) is optional for `*.nuspec`.**. A `BOM` is not required but it won't hurt anything if it is found. -- **PowerShell scripts need to be saved in UTF-8 with `BOM`**. PowerShell is ignoring the standards and needs a `BOM` in order to recognize scripts as `UTF-8`. Otherwise it processes non `ASCII` characters incorrectly. -- Don’t use the default Windows Editor. While newer versions of Notepad have improved its ability to handle line endings and UTF-8 w/out BOM, it is still behind in capabilities as compared to other editors. Alternatives: - - [Visual Studio Code](https://community.chocolatey.org/packages/vscode) - - [Notepad++](http://community.chocolatey.org/packages/notepadplusplus) - - [Geany](http://community.chocolatey.org/packages/geany) -- Use this **XML declaration**: `<?xml version="1.0" encoding="utf-8"?>`. - -<Callout type="info"> - There is a lot of confusion in the world of character encodings: For example, `ANSI` is an incorrect term for the internal Windows character encodings, e. g. `Windows-1252`. But you should not use this encoding family anyway. -</Callout> - -## What Version of the Software Should I Package? - -The main release of a product versions are usually sufficient. If there are also beta versions available and you would rather have that, then please create both the official release and the beta (and set the beta as a prerelease when pushing the item to community.chocolatey.org). Regular users of packages may want to use official releases only and not betas. - -<Callout type="info"> - Both of these have the SAME package id, just different versions. -</Callout> +If you think you got what it takes and just want to know the basic steps to create a Chocolatey package, please see the <Xref title="Quick Start Guide" value="create-packages-quick-start" />. ## How do I Create Packages? -There are three main elements to a Chocolatey package. Only the nuspec is required (#1 below). - -1. <Xref title="Nuspec" value="create-packages" anchor="nuspec" /> -1. <Xref title="chocolateyInstall.ps1" value="chocolatey-install-ps1" /> - check out the <Xref title="helper reference" value="powershell-reference" /> -1. any application files to include (it is highly suggested that you are the author in this case or you have the right to <Xref title="distribute files" value="legal" />). EXE files in the package/downloaded to package folder from chocolateyInstall.ps1 will get a link to the command line. -1. chocolateyUninstall.ps1, for uninstalling your package. See <Xref title="helper reference" value="powershell-reference" /> for functions available in your script. - -<Callout type="info"> - Please maintain compatibility with Posh v2. Not every OS we support is on Posh v2 (nor comes OOB with Posh v3+). It's best to work with the widest compatibility of systems out there. -</Callout> - -There is a video showing the creation of a package: [http://www.youtube.com/watch?v=Wt_unjS_SUo](http://www.youtube.com/watch?v=Wt_unjS_SUo) -The video is a bit outdated in showing the contents of the chocolateyInstall.ps1. Have a look at what the [chocolateyInstall.ps1](https://github.com/ferventcoder/chocolatey-packages/blob/master/manual/windirstat/tools/chocolateyInstall.ps1) looks like now: - -```powershell -$packageName = 'windirstat' -$fileType = 'exe' -$url = 'http://prdownloads.sourceforge.net/windirstat/windirstat1_1_2_setup.exe' -$silentArgs = '/S' - -Install-ChocolateyPackage $packageName $fileType $silentArgs $url -``` - -## When Will my Custom Scripts be Run? - -The table below shows which scripts are available, and which command(s) will cause them to be run. - -Script Name | Install | Upgrade | Uninstall ------------------------------------------------|---------|---------|---------- -chocolateyBeforeModify.ps1 | | Yes | Yes -chocolateyInstall.ps1 | Yes | Yes | -chocolateyUninstall.ps1 | | | Yes - -<Callout type="info"> - In the upgrade scenario, the chocolateyInstall.ps1 script will be the one included in the new package. The chocolateyBeforeModify.ps1 script will be the one from the previously installed package. -</Callout> - -## Nuspec - -The `Chocolatey` Windows package manager uses the same infrastructure as [NuGet](http://nuget.org/), the Visual Studio package manager by Outercurve Foundation (sponsored by Microsoft). Therefore packages are based on the same principles. One of those is a package description (specification) in `xml` format, known as the `Nuspec`. - -The `Nuspec` contains basic information such as the version, license, maintainer, and package dependencies. `Chocolatey` includes additional optional functionality on top of [NuGet's Nuspec format](http://docs.nuget.org/docs/reference/nuspec-reference) - the best way to determine currently supported features is to create a test package, and look at the generated nuspec file. - -`choco new testpackage` - -<Callout type="info"> - If your package uses recently introduced functionality, you might want to include `chocolatey` as a dependency with the version being the lowest version that has the introduced functionality. Otherwise the installation could fail for users with an older version of `Chocolatey` installed. -</Callout> - -You can indicate the `Chocolatey` dependency like any other dependency. For example: - -```xml - <dependencies> - <dependency id="chocolatey" version="0.9.8.21" /> - </dependencies> -``` - -Logically, the version is based on the lowest compatible version. But if you don't know and used a lot of sorcery in your package, depend on the version of `Chocolatey` that you succesfully tested your package on. - -**See also:** [NuGet Version Reference](http://docs.nuget.org/docs/reference/versioning) - -## How do I Create a New Package? - -- **Generate new package**: - - `choco new -h` will get you started seeing options available to you. - - Once you figured out all of your options, you should move forward with generating your template. - -## Install Only on Some Versions of Windows - -Right now if the software the package installs is only supported on particular versions of Windows, you should absolutely fail the package. An installed package indicates success. If you pass a warning message but don't also throw an error, that means the package installed successfully. Folks using the package are going to be confused because they will then expect that the underlying software is also installed. The software itself may throw a cryptic error, which will lead to questions from the community about why it is broken (when it is just unsupported). Do yourself a favor and check the version of Windows and throw an error if it is not a supported version. Under no circumstances should you bypass with a warning, because a warning is still a success. - -There is at least one noted exception to this and that is low-level packages that are meant as dependencies that need to be present even if they do not install anything. These are things like KBs that only need to be installed on some versions of Windows. If the package failed and it was a dependency of a higher level package that installed software, it would cause issues attempting to install that software on different versions of Windows. Since about 5% of the packages apply to this exception, stick with the above thoughts for packages. +There are three components of a Chocolatey package: -<Callout type="info"> - We will ultimately enhance the nuspec and take care of this for you automatically. Until we get there, follow the above avenue. -</Callout> - -## Installation Paths +1. [Package metadata file (`.nuspec`)](#package-metadata-nuspec-file). (**Required**). +1. <Xref title="chocolateyInstall.ps1" value="package-scripts" /> script which does the installation and upgrading of your package. See the <Xref title="Chocolatey PowerShell functions reference" value="powershell-reference" /> for more information on PowerShell functions and cmdlets that can be used. +1. Files to include such as the software installer, registry key or license files, standalone executable binaries, etc. Ensure you have <Xref title="distribution rights if your package is for the Chocolatey Community Repository" value="legal" />. +1. `chocolateyUninstall.ps1` script which uninstalls your package. See the <Xref title="Chocolatey PowerShell reference" value="powershell-reference" /> for more information on PowerShell functions and cmdlets that can be used. -As the package maintainer, you decide where the packaged application is installed or extracted to. Depending on your type of application (see _"What distinction does Chocolatey make between an installable and a portable application?"_ at the bottom of the <Xref title="FAQ" value="faqs" />) there are a couple of suitable locations (not listed in any particular order): +For more information, read our comprehensive <Xref title="packaging documentation" value="package-creation" />, our [back-to-basics blog post on Creating Chocolatey Packages, Step-By-Step, the Easy Way!](https://blog.chocolatey.org/2024/03/creating-chocolatey-packages-step-by-step) or, watch the YouTube livestream: -### 1. The default installation path of your .msi/.exe setup file +<Iframe ratio="16x9" link="https://www.youtube.com/embed/2VRK2RQ3-Ao" title=" Creating Chocolatey Packages, Step-By-Step, the Easy Way! +Creating Chocolatey Packages, Step-By-Step, the Easy Way!" /> -The original creator probably had a reason for choosing a specific default installation path. -If you think, the user should be able to customize this path and you, the package maintainer, know how to pass a custom path on to the installer, then you should use `%ChocolateyBinRoot%`. +## Internationalization and Localization of Packages -### 2. The Package Directory in `%ChocolateyInstall%\lib\mypackage` +For Chocolatey, internationalization and localization of packages is very important, because it has users from all over the world. Many applications support multiple languages, but they use several different methods to achieve that. Therefore, there is no standard how internationalization/localization has to be integrated into packages. However, here are a few examples of packages that use various techniques. You can use them as inspiration for new packages: -You can extract the application within the package directory itself (or even ship an extracted version with the package). This allows Chocolatey to automatically find executables and put those on `%path%`. +* The ideal situation is when an application determines the user's system language and automatically installs with that language. Then you don't have to take any action relating to localization, because the application already handles that. Examples of such applications are [VLC Media Player](https://community.chocolatey.org/packages/vlc) and [LibreOffice](https://community.chocolatey.org/packages/libreoffice). +* When an application provides different installers for different languages, you should determine the system language and download the appropriate installer. The package for [Mozilla Firefox](https://community.chocolatey.org/packages/Firefox) ([source code](https://github.com/chocolatey-community/chocolatey-packages/tree/master/automatic/Firefox)) uses this method. +* Sometimes an application installer or executable has already integrated all supported languages, but doesn't automatically select the system language during a silent install. Often you can pass an additional install parameter to select the desired language. This is used for example in the [CCleaner](https://community.chocolatey.org/packages/ccleaner) package ([source code](https://github.com/tonigellida/chocolateyautomaticpackages/tree/master/ccleaner)). +* Some application use separate language files which must be downloaded separately and put somewhere in the application directory. It is best when you create a separate package for the language files. If your package id is `packageid`, then call it `packageid-langfiles`. The [language files package for KeePass](https://community.chocolatey.org/packages/keepass-langfiles) is an example how this can be achieved. -### 3. Path Provided by the `Get-ToolsLocation` Helper +## Package Metadata `.nuspec` File <Callout type="warning"> - It was previously possible to use the helper `Get-BinRoot` for backwards compatibility. This is still possible in v1.0.0, however its use is not recommended as the function is now deprecated, and will be removed in v2.0.0. -</Callout> - -The path returned by the helper `Get-ToolsLocation` can be used as the parent directory for the installation. `Get-ToolsLocation` will return the value of the environment variable `%ChocolateyToolsLocation%`. If the value does not contain a drive reference, the system drive will be prepended. If the environment variable is not set, the default path (`C:\tools`) will be returned. - -As an example, [GeoServer](https://github.com/AdmiringWorm/chocolatey-packages/blob/0f3b93ab7b067b265a06349a68297d07b1598e64/automatic/geoserver/tools/chocolateyuninstall.ps1#L8) uses `%ChocolateyToolsLocation%`. If the environment variable is not set, it will be set to `c:\tools` and GeoServer will install to `C:\tools\GeoServer` by default. If `%ChocolateyToolsLocation%` is set to "C:\Common\bin", GeoServer installs to `C:\Common\bin\GeoServer`. - -`%ChocolateyToolsLocation%` gives the Chocolatey user a way of controlling where packages are installed. If you want to allow customizing the installation path, then this is currently the way to go. - -### Make it clear in the package description - -No matter how you decide, you are advised to state the default installation directory in your package description. This prevents confusion about where the application will end up being installed. - -If you allow customizing the installation path, then append instructions on how to do that, too. - -### Windows Environment Variables - -Chocolatey installations are advised to be performed while running "as administrator". Because of this it is important that you understand that some windows environment variables will be pinned to the administrator user and not the installation user at least -one circumstance. - -On many systems there are multiple accounts. The issue can occur on a system where there is an admin user with an account type of "Administrator", let's call this user **admin**. There is another user with an account type of "Standard User" lets call this second user **user**. - -<Callout type="info"> - "Administrator" and "Standard User" are the 2 account types that Windows 10 supports. + <Xref title="Additional rules apply" value="create-packages-for-ccr" /> if you are creating packages for the [Chocolatey Community Repository](https://community.chocolatey.org). </Callout> -When **admin** chooses to run a `cmd` shell with elevated privileges by right clicking and selecting "Run as administrator". **admin** will be warned by "User Access Control" that they are elevating privileges via a dialog that **admin** can dismiss. The command shell will run the shell with administrator rights from the **admin** account. All good! - -When **user** chooses to run a `cmd` shell by right clicking and selecting "Run as administrator", **user** will be asked to enter the credentials for **admin** account to gain administrator rights. **user** will need to enter **admin**'s credentials and then the command shell will run the shell with administrator rights from the **admin** account. Wait... what? - -Yes, really. An elevated command shell for **user** will run as if it is the **admin** user! - -That means that when your installer depends on any environment variables to find install locations there is a scenario where the environment variables are from a different user (e.g. **admin**) than the user installing the package. - -The known affected environment variables are: `APPDATA`, `LOCALAPPDATA`, `TEMP`, `TMP`, `USERNAME`, `USERPROFILE` - -Example Settings for a user named "administrator": - -``` -APPDATA=C:\Users\administrator\AppData\Roaming -LOCALAPPDATA=C:\Users\administrator\AppData\Local -TEMP=C:\Users\administrator\AppData\Local\Temp -TMP=C:\Users\administrator\AppData\Local\Temp -USERNAME=administrator -USERPROFILE=C:\Users\administrator -``` - -A simple way around this is to ask the user to set environment variables that can override environment variables. Or alternatively, instruct your users to set the necessary environment variables in the elevated privileges command shell. - -Example instructions: - -> Within the administrator command shell you will need to set 2 environment variables: -> -> ``` -> set LOCALAPPDATA=C:\Users\<USERNAME>\AppData\Local -> set USERPROFILE=C:\Users\<USERNAME> -> ``` - -## Upgrading - -Prior to choco version 0.9.10, there is no dedicated automation script for upgrade scenarios. Instead, your <Xref title="chocolateyInstall.ps1" value="chocolatey-install-ps1" /> script should support installing/upgrading on top of any previous versions of your package. - -More recent versions of choco (0.9.10+) give you the option of supplying a `chocolateyBeforeModify.ps1` script. -If applicable, the version of this script from the currently installed package will be run before subsequent -chocolateyInstall or chocolateyUninstall scripts. - -## Uninstalling - -Uninstalling is handled by a `chocolateyUninstall.ps1` script, which should be in your package's `tools` directory, next to <Xref title="chocolateyInstall.ps1" value="chocolatey-install-ps1" />. All the usual <Xref title="helper reference" value="powershell-reference" /> are available. If your package doesn't uninstall cleanly, people will get grumpy because they'll have to manually clean up after you. Be a good human being and write an uninstaller. - -## Dependency Chaining - -You can make packages that depend on other packages just by adding those dependencies to the nuspec. Take a look at [ferventcoder.chocolatey.utilities nuspec](https://github.com/ferventcoder/chocolatey-packages/blob/master/manual/ferventcoder.chocolatey.utilities/ferventcoder.chocolatey.utilities.nuspec). - -## Avoid Folders Named "content" - -Do not use a folder named "content" in your package. NuGet attaches a special meaning to this folder and will not allow you to have dependencies on packages that have content folders without also having a content folder. It's turtles all the way down until we or NuGet removes this limitation. - -## Naming Your Package - -The **title** of your package (`<title>` tag in the nuspec) should be the same as the name of the application. -Follow the official spelling, use upper and lower case and don’t forget the spaces. -Examples of correct package titles are: _Google Chrome_, _CCleaner_, _PuTTY_ and _FileZilla_. -The title will appear on the left side in the package list of the Chocolatey Community Repository, followed by the version. - -There are some guidelines in terms of the package **ID** (`<id>` tag in the nuspec): - -* **Use only lowercase letters**, even if you used uppercase letters in the package title. - (This is considered a guideline because it is correctable in other ways). - Once a package is submitted (even prior moderation), the Chocolatey Community Repository will always show the id with the casing of the first package version. - In addition, changing the casing of the package id may have negative side effects on dependencies (note: this last statement needs verified). -* If the original application name consists of compound words without spaces (CamelCase), just as _MKVToolNix_, _TightVNC_ and _VirtualBox_, the package id’s are simply the same (but **lowercase** of course): `mkvtoolnix`, `tightvnc`, and `virtualbox`. -* If the name of the application contains multiple words separated by spaces, such as _MusicBrainz Picard_ or _Adobe Reader_, replace the spaces with the hyphen-minus character “-” (U+002D), or just omit them. - **Don’t use dots**. - Dots should be used only if the original application name contains dots (for example, _Paint.NET_). - Hence the correct id’s of the previously mentioned applications can be `musicbrainz-picard` or `adobereader`. - We recommended you use the hyphen method when there are long package names to ensure they remain readable. -* For sub-packages, use the hyphen-minus character “-” (U+002D) as the separator, not a dot. - Sub-packages are intended for separate packages that include extensions, modules or additional features/files for other applications. - Therefore `keepass-langfiles` is a proper package id, because it adds the language files for the main application which in this case is _KeePass_. - Another example is `libreoffice-help` for the help pack for _LibreOffice_, the open source office suite. -* If you want to package an open source application, first search for any pre-existing packages on services like [Repology](https://repology.org/). - If there are already published packages for the application on another repository, **use the same package id**. - This will make it easier for users which work with multiple platforms, so they don't have to remember and use different package names. -* Do not use `chocolatey` in your package ID as this indicates an official package. You can use `choco` instead, but you must include the word 'Unofficial' in the package title. - -These guidelines are already commonly applied on packages for all major Linux distributions, because they lead to a more consistent user experience for software repositories, result in easier to remember package IDs, and reduce unnecessary considerations on naming packages for package creators. - -Note that some packages in the Chocolatey Community Repository don't follow these guidelines; many of these were created before these guidelines were introduced. -New packages should follow the guidelines to improve the overall experience for users going forward. - -If you are going to offer a package that has both an installer and an archive (zip or executable only) version of the application, create three packages - see <Xref title="Portable vs Installable" value="faqs" anchor="what-distinction-does-chocolatey-make-between-an-installable-and-a-portable-application" /> and <Xref title="Install, Portable, and Meta/Virtual Packages" value="faqs" anchor="what-is-the-difference-between-packages-no-suffix-as-compared-to.install.portable" />. - -### Naming Packages to Allow for Side-by-Side Installation - -For some software, it is expected that users may want multiple different versions installed simultaneously. -This has commonly been seen with software like Python which offer some kind of runtime dependency that other scripts or applications depend on. - -In the past, Chocolatey CLI supported a "side-by-side" installation method which could be used for this purpose to install multiple distinct versions side-by-side, on the same machine. -This has been deprecated and is no longer supported in version 2.0.0 due to many issues with the use and implementation of the feature. - -#### If the Software You're Creating a Package for Expects **Side-by-Side Installations of Different Versions** - -1. Create _separate package IDs_ for each major version (or major + minor version, depending on the expectations of users) which include the version number in the ID. - For example, if the package ID would be `python`, the package for major version 2 would be `python2`, or a package for specifically the 2.7 branch might be `python27` or `python2-7`. - These individual versioned packages can be updated as normal, as long as that major and/or minor version is still receiving further updates. -1. Create a <Xref title="**metapackage**" value="getting-started" anchor="terminology" /> for the overall product with a package version for each of the versioned packages. - In other words, create another package (this time without a version number in the ID), which contains only a `nuspec` file and add a dependency on the versioned package. - Following the above example for Python, we'd create a package with the ID `python` at version `2.0.0` that takes a dependency on the `python2` package. -1. New versions of the metapackage should be published for "sub-versions" of the dependency package as well. - For example, if Python version `3` is released, we'd create a new version of the `python` package with its version set to `3.0.0`, which depends on a new `python3` package. - -#### If the Software You're Creating a Package for Expects **Side-by-Side Installations of the Same Version** - -A possible example might be where multiple different instances of the software are being installed into different install directories. +See the documentation on the contents of the <Xref title="package metadata" value="package-metadata" /> -Chocolatey does not currently support this functionality. -This functionality can be mimicked by making use of `--force` to forcibly overwrite an already-installed package and providing an argument or package parameter that the package can use to direct the installation to install into a different directory. -However, Chocolatey will only be aware of the most-recently installed copy of the software, and will only be able to provide updates to that single installation of the software in most cases. -As a result, this particular configuration is not supported. - -A potential workaround for users maintaining their own package repositories is to maintain separate instances of the same package under different package IDs, where each package ships the same software, but is scripted to install to a different directory. -For example, you can create a `python3-localtoolsfolder` and a `python3-programfilesfolder` package which have the same contents, with only slight differences in the parameters passed to the install functions to ensure they install in the desired locations. -The recommended naming conventions here are similar to sub-packages, where the package is named after the primary package ID followed by a dash and a discriminator, likely named after the install location or referencing the purpose of the additional package(s). - -## Package Description and Release Notes - -The `<description>` of the package should contain a short text or at least a few words about the software for which the package is made. Here are a few things that should be respected: - -- The description should always be written in English, even if the packaged software does not provide an UI in English. You can also include the software’s description in its original language, but insert it after the English description. -- The description should not just contain a repetition of the package name. -- It should not just consist of a link where more information can be found. For that purpose there’s already `<projectUrl>`. -- The contents of `<description>` and also `<releaseNotes>` are parsed as Markdown, so don’t insert line breaks in the middle of sentences. Remember to add empty lines to separate paragraphs and add an empty line before a list. - -## Versioning Recommendations - -Versioning can be both simple and complicated. The best recommendation is to use the same versioning that the installable/portable application uses. With Chocolatey you get four version segments. If the application only uses 1, 2 or 3 version segments, follow suit. - -If the 4th segment is used, some folks like to drop the segment altogether and use that as only the package fix notation using one of the notations in the next section. There is no recommendations at this time. - -### Package Fix Version Notation - -Package fix version notation ONLY applies when you are making a fix to the package because the existing version of a package is incorrect in some way. So if the software is `1.1.0`, in a normal scenario the package version should be `1.1.0`. If you find that the `1.1.0` package has an issue and you need to fix the package but keep the same version of the software, that is where package fix version notation comes into play. You would end up with both a `1.1.0` package and a `1.1.0.YYYYMMDD` version of the package. - -<Callout type="info"> - This doesn't apply to packages on the community feed (aka https://community.chocolatey.org/packages) that are still under review (not yet approved). Please read the instructions given in email for resubmitting the same version. -</Callout> - -If you need to fix an approved package for some reason, you can use the fourth version element (aka segment) for a package fix notation. There are two recommended methods of package fix version notation: +## How do I Create a New Package? -- **Date (Year/Month/Day)** - Some folks use year month day package fix notation (yyyyMMdd as in 20120627 seen as 1.2.0.20120627) -- Sequential - **Not recommended** - Some folks use sequential numbering (0, then 1, etc as in 0 for no fix, 1 for first fix and so on seen as 1.2.0.0 and 1.2.0.1). +See our documentation on how to <Xref title="package anything with Chocolatey CLI" value="package-anything" />. -Date Package Fix Version Notation is recommended because one can ascertain what it is immediately upon seeing it, where sequential is not obvious on sight whether it is part of the software versioning or something special with the package. +## Package Scripts -Package fix version notation is only acceptable in the fourth segment. Do not use any of the other segments for package fix notation. If an application only uses 1 or 2 version segments, add zeros into the other segments until you get to the 4th segment (i.e. 1.0.0.20120627). +### Package Installation -When the fourth segment is already used, it is recommended to add two zeroes (00) to the end of the version. Then when you need to fix, you just increment that number. So if the package was ruby and the version was 2.0.0-p353, the package is 2.0.0.35300 (adding the two zeroes at the end). Then a fix would be 2.0.0.35301 and so on. +<Xref title="Installing a package" value="choco-command-install" /> is achieved using a <Xref title="Chocolatey package script" value="package-scripts" />: `chocolateyInstall.ps1`. -<Callout type="warning"> - If you decide to add a secondary set of numbers to the fourth segment, you MUST ALWAYS include that secondary set of numbers while the other three version segments are the same. The reason - if you fix `.1` to `.100`, then release `.2`, `.100` is greater than `.2` because versioning doesn't look at the ".", only the number in the element. So `100` is greater than `2`. -</Callout> +#### Installation Paths -## Internationalization and Localization of Packages +When you create a package, you decide where it will be installed or extracted to. Depending on the <Xref title="type of application" value="faqs" anchor="what-distinction-does-chocolatey-make-between-an-installable-and-a-portable-application" />, there are a couple of suitable locations (not listed in any particular order): -For Chocolatey, internationalization and localization of packages is very important, because it has users from all over the world. Many applications support multiple languages, but they use several different methods to achieve that. Therefore, there is no standard how internationalization/localization has to be integrated into packages. However, here are a few examples of packages that use various techniques. You can use them as inspiration for new packages: +1. **The default installation path**. The software author probably had a good reason for choosing a specific installation path. If the end-user should be able to customize this path and you, the package maintainer, know how to pass a custom path to the installer, then you should add a <Xref title="package parameter" value="parse-package-parameters" />. +2. **The Chocolatey package directory**. You can install or extract to the package directory `$env:ChocolateyInstall\lib\<PACKAGENAME>`. This allows Chocolatey to automatically find executables and put those on `PATH`. +3. **Path provided by the `Get-ToolsLocation` <Xref title="Chocolatey PowerShell function" value="get-toolslocation" />**. Using `Get-ToolsLocation` gives the end-user a way of controlling where packages are installed. If you want to allow customizing the installation path, then this is a good way to go. -* The ideal situation is when an application determines the user's system language and automatically installs with that language. Then you don't have to take any action relating to localization, because the application already handles that. Examples of such applications are [VLC Media Player](https://community.chocolatey.org/packages/vlc) and [LibreOffice](https://community.chocolatey.org/packages/libreoffice). -* When an application provides different installers for different languages, you should determine the system language and download the appropriate installer. The package for [Mozilla Firefox](https://community.chocolatey.org/packages/Firefox) ([source code](https://github.com/chocolatey-community/chocolatey-packages/tree/master/automatic/Firefox)) uses this method. -* Sometimes an application installer or executable has already integrated all supported languages, but doesn't automatically select the system language during a silent install. Often you can pass an additional install parameter to select the desired language. This is used for example in the [CCleaner](https://community.chocolatey.org/packages/ccleaner) package ([source code](https://github.com/tonigellida/chocolateyautomaticpackages/tree/master/ccleaner)). -* Some application use separate language files which must be downloaded separately and put somewhere in the application directory. It is best when you create a separate package for the language files. If your package id is `packageid`, then call it `packageid-langfiles`. The [language files package for KeePass](https://community.chocolatey.org/packages/keepass-langfiles) is an example how this can be achieved. +### Package Upgrade -## Package Icon Guidelines +<Xref title="Upgrading a package" value="choco-command-upgrade" /> is achieved using a <Xref title="Chocolatey package script" value="package-scripts" />: `chocolateyBeforeModify.ps1`. -If there is an icon which is suitable for your package, you can specify it in the `<iconUrl>` tag in the nuspec. But there are a few things you should consider: +### Package Uninstallation -* **Avoid hotlinking icons from sites where you don’t have control over the file.** If you have a packages repository (recommended), use your own copy of the icon and put it there. -* **Use a static CDN for icon URLs that permits you to serve files hosted in a repository on GitHub.** Some CDN services cache files permanently and it's therefore best to use a specific tag or commit URL, not a branch URL. While we don't make any recommendations about specific services, the more popular ones used by maintainers are [jsDelivr](https://www.jsdelivr.com/), [Statically](https://statically.io/) and [Githack](https://raw.githack.com/). -* **Avoid using GitHub raw links** (`https://raw.githubusercontent.com/...`). They are not intended to be used as CDN. -* **Use the software’s icon if one is available, not the logo.** This blog post explains the difference between logos and icons: http://blog.designcrowd.com/article/353/differences-between-logos-and-icons. If the software of your package doesn’t have an icon, but a logo with text and an image, you can extract the image with your favorite image editor and use that as package icon. An example is [MySQL’s dolphin](https://community.chocolatey.org/packages/mysql). -* **Use package icons with at least 128 pixels in width or height** if available. However, avoid very high resolutions, because this would only unnecessarily increase the page load time. If there are only icons with less than 128 pixels available, choose the icon with the highest resolution you can find without upscaling it. Don’t use low resolution favicons as package icons. -* Use icons with transparent background if available. -* Don’t use distorted or blurry icons. -* The package list in the Chocolatey Community Repository shows the icons with a maximum of 48 pixels in width/height. Application logos with very detailed graphics that are barely visible at that dimension are not suitable as package icons. -* **PNG is the preferred format** for raster package icons. Avoid ICO, GIF and JPEG graphics. -* Good sources for package icons are the official desktop icons of the corresponding application you want to make a package of. The icons can be extracted from the app executables using tools like [BeCyIconGrabber](https://community.chocolatey.org/packages/becyicongrabber). Remember to take the icon with 128 px or more and save it as PNG file. +<Xref title="Uninstalling a package" value="choco-command-uninstall" /> is achieved using a <Xref title="Chocolatey package script" value="package-scripts" />: `chocolateyUninstall.ps1`. All the usual <Xref title="helper reference" value="powershell-reference" /> are available. -The icon shown on the community.chocolatey.org package page is saved, and served, locally to mitigate against cross scripting attacks and to prevent getting _non HTTPS assets_ errors on the website. Sometimes the page loads faster than the image can be served and the default image gets cached and as a result the new package icon may not be shown until you clear the browser cache for community.chocolatey.org and wait 3 hours before reloading the page. +<a name="when-will-my-custom-scripts-be-run"></a> +### When Do Package Scripts Run? -<a name="how-do-i-exclude-executables-from-getting-batch-redirects"></a> +See the documentation on <Xref title="package scripts" value="package-scripts" />. -## How Do I Exclude Executables from Getting Shims? +## Package Content -If you have executables in the package or brought into the package folder during PowerShell run and you want to exclude them you need to create an empty file named exactly like (**case sensitive**) the executable with `.ignore` suffixed on the end in the same directory where the executable is or will be. +Include the Software installer in the package, sometimes called embedding the binaries. The <Xref title="package scripts" value="package-scripts" /> can use <Xref title="Chocolatey provided PowerShell" value="powershell-reference" /> that will use the installers directly from the package instead of downloading first. This makes for the most reliable and deterministic packages, but ensure you have the <Xref title="legal right to distribute" value="legal" /> the software first if publishing to a public location (like the [Chocolatey Community Repository](https://community.chocolatey.org)). -Example: In the case of `Bob.exe` you would create a file named `Bob.exe.ignore` and that file would not get a redirect batch link. The Chocolatey package has an example of that. To further expand, `bob.exe.ignore` would not work because it doesn't have the correct casing. +### Avoid Folders Named "content" -Here's a great [programmatic example](https://github.com/ferventcoder/chocolatey-packages/blob/6ea7c087bd999d428a564b5d7e236ae998ef72e9/automatic/git.commandline/tools/chocolateyInstall.ps1#L13-L20): +Do not use a folder named `content` in your package. NuGet attaches a special meaning to this folder and will not allow you to have dependencies on packages that have content folders without also having a content folder. -```powershell -$files = get-childitem $installDir -include *.exe -recurse +## Package Dependencies -foreach ($file in $files) { - #generate an ignore file - New-Item "$file.ignore" -type file -force | Out-Null -} -``` +You can make <Xref title="packages that depend on other packages" value="package-dependencies" /> just by adding those dependencies to the package metadata `.nuspec` file. +<a name="how-do-i-exclude-executables-from-getting-shims"></a> <a name="how-do-i-set-up-batch-redirects-for-applications-that-have-a-gui"></a> -## How do I set up shims for applications that have a GUI? -If you don't want to see a hanging window when you open an application from the command line that was set up with Chocolatey, you want to create a file next to the executable that is named exactly the same (**case sensitive**) with `.gui` suffixed on the end. +## Automatically Adding Executables to the PATH Using Shims -Example: In the case of `Bob.exe` you would create a file named `Bob.exe.gui` and that file would be set up as a GUI application so the window will call it and then move on without waiting for it to finish. Again, `bob.exe.gui` would not work because it doesn't have the correct casing. +See the <Xref title="documentation on shimming" value="shim" />. ## Build Your Package -Open a command line in the directory where the nuspec is and type <Xref title="`choco pack`" value="choco-command-pack" />. That's it. +The <Xref title="pack command" value="choco-command-pack" /> is used to build a package. From the directory where the `.nuspec` you created is, and run `choco pack`. That's it. ## Testing Your Package <Callout type="info"> - We strongly suggest the following should be performed in a VM and not on your machine. + We strongly suggest the following should be performed in a virtual machine and not on your computer. </Callout> <Callout type="info"> - Testing your package can be done in the same way as the verifier - take a look at [Chocolatey Verifier Testing](https://github.com/chocolatey-community/chocolatey-test-environment). + Testing your package can be done using the [Chocolatey Test Environment](https://github.com/chocolatey-community/chocolatey-test-environment). This is the same environment used by <Xref title="Package Verifier" value="package-verifier-service" />, used on the [Chocolatey Community Repository](https://community.chocolatey.org). </Callout> -To test the package you just built, open a command line shell and navigate to the directory where the `*.nupkg` file is located. Then type: +To test the package you just built, navigate to the directory where the newly built Chocolatey package `.nupkg` file is, and run: ```powershell -choco install packageName --debug --verbose --source . +choco install <PACKAGENAME> --debug --verbose --source . ``` -This will install the package right out of your source. As you find things you may need to fix, using `--force` (`-f`) will remove and reinstall the package from the updated `*.nupkg`. If you are specifically testing `chocolateyBeforeModify.ps1`, you need to be testing upgrade and uninstall scenarios. You need to install a version of the package with this file **first** as before modify is like uninstall, it runs from the installed package, not the package you are installing (like `chocolateyInstall.ps1` does). +Where: + +- `<PACKAGENAME>` is the name of the package you built. +- The `.` after `--source` uses the current directory. You can specify multiple directories separated by a semicolon, for example `--source "'.;c:\package\temp'"`. + +This will install the package from the folder it was created in. As you find things you may need to fix, using `--force` (`-f`) will remove and reinstall the package from the updated Chocolatey package. If you are specifically testing `chocolateyBeforeModify.ps1`, you need to be testing upgrade and uninstall scenarios. You need to install a version of the package with this file **first** as the `chocolateyBeforeModify.ps1` script runs from the installed package, not the package you are installing (like `chocolateyInstall.ps1` does). <Callout type="info"> - Using Force `--force` (`-f`) should only be done in subsequent testing where you are reinstalling the same package that you've changed and should NOT be used in regular use scenarios. It should definitely not be in scripts. + Using Force `--force` (`-f`) should only be done in subsequent testing where you are reinstalling the same package that you've changed and should not be used in regular use scenarios. It should definitely not be in scripts. </Callout> <Callout type="info"> - If you are using a Semver dash in your package version (such as 1.0.0-beta), you will need to use the `--pre` switch or else you will get *Unable to find package* errors from `choco install`. You can also specify `-version 1.0.0-beta` to try to install that exact version. + If you are using a Semver dash in your package version (such as `1.0.0-beta`), you will need to use the `--pre` option or you will get **Unable to find package** errors. You can also specify the exact version with the `--version 1.0.0-beta` option. </Callout> -`.` points to the current directory. You can specify multiple directories separated by a semicolon; - -When your `nuspec` specifies dependencies that are not in your source, you should add their paths to the source directory. E.g. in the case of Chocolatey itself: +When your package metadata `.nuspec` file specifies dependencies that are not in your local folder, you should add their paths to the `--source`. For example, for dependencies specified like this in the package:E.g. in the case of Chocolatey itself: ```xml <dependencies> - <dependency id="chocolatey" version="0.9.8.20" /> + <dependency id="chocolatey" version="2.0.0" /> </dependencies> ``` -You'll need to append the API path like so: +You'll need to append the Chocolatey Community Repository API path like so: `--source "'.;https://community.chocolatey.org/api/v2/'"` (note the double quotes bookending the apostrophes here, use `%cd%` in cmd.exe or `$pwd` in Powershell.exe if `.` doesn't resolve). See <Xref title="passing options with quotes" value="choco-commands" anchor="how-to-pass-options-switches" />. -<Callout type="info"> - If you need to do this, please ensure you run `choco pack` first. This method of passing a source won't work calling a nuspec or nupkg directly as it will override the source passed to the local folder. -</Callout> - -You can also use the `--debug` switch on `choco install` to provide more information. - -<Callout type="info"> - Do not call install with `.nupkg` - pointing to a file explicitly overrides source. You must call your install with the package name, not the nupkg file and location. You've already specified for choco to look in a local source with `--source "'.;https://community.chocolatey.org/api/v2/'"`. Call `choco install dude --source "'.;https://community.chocolatey.org/api/v2/'"`, not `choco install .\dude.nupkg --source "'.;https://community.chocolatey.org/api/v2/'"`. -</Callout> - -### Alternative Testing Strategy - -You can also type `choco install --force --debug --verbose path/to/nuspec` and choco will build the nupkg and attempt to install it. - -<Callout type="info"> - This is not recommended if you are passing install arguments or package parameters due to some weirdness, and definitely does not work with passed sources as it need to override that with the local folder once it builds the package. Most likely you will want to stick with the recommended strategy. -</Callout> - ## Push Your Package -To push your package after you have built and tested it, you type `choco push packageName.nupkg --source sourceLocation` where **packageName.nupkg** is the file name of the nupkg that was built and **sourceLocation** is the location of the source you want to push to (for example, `--source "'https://push.chocolatey.org/'"` for the Chocolatey Community Repository). -You must either have set an API key for the target URL, or provide an API key directly to the `push` command via the `--api-key` option. -For example, if pushing to the Chocolatey Community Repository, you will need to have previously set an API key for `https://push.chocolatey.org/` (`choco apikey add --source "'https://push.chocolatey.org/'" --key "'API_KEY_HERE'"`). -For more information, see the reference documentation for <Xref title="`choco push`" value="choco-command-push" />. - -As of Chocolatey CLI v2.0.0, you can set the `defaultPushSource` configuration value if you frequently push packages to the same source. -For example: `choco config set --name defaultPushSource --value https://push.chocolatey.org/` +To push your package after you have built and tested it, you type `choco push <PACKAGE .NUPKG FILE> --source <PACKAGE REPOSITORY> --api-key <PACKAGE REPOSITORY API KEY>` where: -## Automatic Packaging? +1. `<PACKAGE .NUPKG FILE> is the file name of the Chocolatey package `.nupkg` file that was built. +1. `<PACKAGE REPOSITORY>` is the source URL of your package repository you want to push to (for example, `--source "'https://push.chocolatey.org/'"` for the Chocolatey Community Repository). As of Chocolatey CLI v2.0.0, you can set the `defaultPushSource` configuration value if you frequently push packages to the same source. For example: `choco config set --name defaultPushSource --value https://push.chocolatey.org/`. +1. `<PACKAGE REPOSITORY API KEY>` is the API key for the source URL. Alternatively you can <Xref title="add that key permanently" value="choco-command-apikey" /> using the `choco apikey` command. -Yes - <Xref title="Automatic Packaging" value="automatic-packaging" /> +For more information, see the <Xref title="documentation" value="choco-command-push" /> for the `choco push` command. -## Becoming a Primary Maintainer of an Existing Package +## Automatic Packaging -See <Xref title="Package Maintainer Handover" value="package-maintainer-handover" /> +See the <Xref title="Automatic Packaging documentation" value="automatic-packaging" /> for more information. diff --git a/src/content/docs/en-us/create/functions/index.mdx b/src/content/docs/en-us/create/functions/index.mdx index ae11cedc5c7..086d6415e5b 100644 --- a/src/content/docs/en-us/create/functions/index.mdx +++ b/src/content/docs/en-us/create/functions/index.mdx @@ -1,185 +1,185 @@ ---- -order: 40 -xref: powershell-reference -title: PowerShell Functions Reference -description: PowerShell Functions aka Helpers Reference ---- -import Xref from '@components/Xref.astro'; - -# PowerShell Functions aka Helpers Reference - -{/* This documentation file is automatically generated from the files at $sourceFunctions using $($sourceLocation)GenerateDocs.ps1. Contributions are welcome at the original location(s). */} - -## Summary - -In your Chocolatey packaging, you have the ability to use these functions (and others with Chocolatey's <Xref title="PowerShell Extensions" value="extensions" />) to work with all aspects of software management. Keep in mind Chocolatey's automation scripts are just PowerShell, so you can do manage anything you want. - -> :choco-info: **NOTE** -> -> These scripts are for package scripts, not for use directly in PowerShell. This is in the create packages section, not the using Chocolatey section. - -## Main Functions - -These functions call other functions and many times may be the only thing you need in your <Xref title="chocolateyInstall.ps1 file" value="chocolatey-install-ps1" />. - -* <Xref title="Install-ChocolateyPackage" value="install-chocolateypackage" /> -* <Xref title="Install-ChocolateyZipPackage" value="install-chocolateyzippackage" /> -* <Xref title="Install-ChocolateyPowershellCommand" value="install-chocolateypowershellcommand" /> -* <Xref title="Install-ChocolateyVsixPackage" value="install-chocolateyvsixpackage" /> - -## More Functions - -### Administrative Access Functions - -When creating packages that need to run one of the following commands below, one should add the tag `admin` to the nuspec. - -* <Xref title="Install-ChocolateyPackage" value="install-chocolateypackage" /> -* <Xref title="Start-ChocolateyProcessAsAdmin" value="start-chocolateyprocessasadmin" /> -* <Xref title="Install-ChocolateyInstallPackage" value="install-chocolateyinstallpackage" /> -* <Xref title="Install-ChocolateyPath" value="install-chocolateypath" /> - when specifying machine path -* <Xref title="Install-ChocolateyEnvironmentVariable" value="install-chocolateyenvironmentvariable" /> - when specifying machine path -* <Xref title="Install-ChocolateyExplorerMenuItem" value="install-chocolateyexplorermenuitem" /> -* <Xref title="Install-ChocolateyFileAssociation" value="install-chocolateyfileassociation" /> -* <Xref title="Uninstall-ChocolateyPath" value="uninstall-chocolateypath" /> - when specifying machine path - -### Non-Administrator Safe Functions - -When you have a need to run Chocolatey without Administrative access required (non-default install location), you can run the following functions without administrative access. - -These are the functions from above as one list. - -* <Xref title="Install-ChocolateyZipPackage" value="install-chocolateyzippackage" /> -* <Xref title="Install-ChocolateyPowershellCommand" value="install-chocolateypowershellcommand" /> -* <Xref title="Get-ChocolateyPath" value="get-chocolateypath" /> -* <Xref title="Get-ChocolateyWebFile" value="get-chocolateywebfile" /> -* <Xref title="Get-ChocolateyUnzip" value="get-chocolateyunzip" /> -* <Xref title="Install-ChocolateyPath" value="install-chocolateypath" /> - when specifying user path -* <Xref title="Install-ChocolateyEnvironmentVariable" value="install-chocolateyenvironmentvariable" /> - when specifying user path -* <Xref title="Install-ChocolateyPinnedTaskBarItem" value="install-chocolateypinnedtaskbaritem" /> -* <Xref title="Install-ChocolateyShortcut" value="install-chocolateyshortcut" /> -* <Xref title="Uninstall-ChocolateyPath" value="uninstall-chocolateypath" /> - when specifying user path -* <Xref title="Update-SessionEnvironment" value="update-sessionenvironment" /> -* <Xref title="Get-PackageParameters" value="get-packageparameters" /> - -## Complete List (alphabetical order) - - * <Xref title='Format-FileSize' value='format-filesize' /> - * <Xref title='Get-ChecksumValid' value='get-checksumvalid' /> - * <Xref title='Get-ChocolateyConfigValue' value='get-chocolateyconfigvalue' /> - * <Xref title='Get-ChocolateyPath' value='get-chocolateypath' /> - * <Xref title='Get-ChocolateyUnzip' value='get-chocolateyunzip' /> - * <Xref title='Get-ChocolateyWebFile' value='get-chocolateywebfile' /> - * <Xref title='Get-FtpFile' value='get-ftpfile' /> - * <Xref title='Get-OSArchitectureWidth' value='get-osarchitecturewidth' /> - * <Xref title='Get-PackageParameters' value='get-packageparameters' /> - * <Xref title='Get-ToolsLocation' value='get-toolslocation' /> - * <Xref title='Get-UACEnabled' value='get-uacenabled' /> - * <Xref title='Get-UninstallRegistryKey' value='get-uninstallregistrykey' /> - * <Xref title='Get-VirusCheckValid' value='get-viruscheckvalid' /> - * <Xref title='Get-WebFile' value='get-webfile' /> - * <Xref title='Get-WebFileName' value='get-webfilename' /> - * <Xref title='Get-WebHeaders' value='get-webheaders' /> - * <Xref title='Install-BinFile' value='install-binfile' /> - * <Xref title='Install-ChocolateyEnvironmentVariable' value='install-chocolateyenvironmentvariable' /> - * <Xref title='Install-ChocolateyExplorerMenuItem' value='install-chocolateyexplorermenuitem' /> - * <Xref title='Install-ChocolateyFileAssociation' value='install-chocolateyfileassociation' /> - * <Xref title='Install-ChocolateyInstallPackage' value='install-chocolateyinstallpackage' /> - * <Xref title='Install-ChocolateyPackage' value='install-chocolateypackage' /> - * <Xref title='Install-ChocolateyPinnedTaskBarItem' value='install-chocolateypinnedtaskbaritem' /> - * <Xref title='Install-ChocolateyPowershellCommand' value='install-chocolateypowershellcommand' /> - * <Xref title='Install-ChocolateyShortcut' value='install-chocolateyshortcut' /> - * <Xref title='Install-ChocolateyVsixPackage' value='install-chocolateyvsixpackage' /> - * <Xref title='Install-ChocolateyZipPackage' value='install-chocolateyzippackage' /> - * <Xref title='Install-Vsix' value='install-vsix' /> - * <Xref title='Set-PowerShellExitCode' value='set-powershellexitcode' /> - * <Xref title='Start-ChocolateyProcessAsAdmin' value='start-chocolateyprocessasadmin' /> - * <Xref title='Uninstall-BinFile' value='uninstall-binfile' /> - * <Xref title='Uninstall-ChocolateyEnvironmentVariable' value='uninstall-chocolateyenvironmentvariable' /> - * <Xref title='Uninstall-ChocolateyPackage' value='uninstall-chocolateypackage' /> - * <Xref title='Uninstall-ChocolateyPath' value='uninstall-chocolateypath' /> - * <Xref title='Uninstall-ChocolateyZipPackage' value='uninstall-chocolateyzippackage' /> - * <Xref title='Write-FunctionCallLogMessage' value='write-functioncalllogmessage' /> - -## Chocolatey for Business Functions - -* <Xref title="Install-ChocolateyWindowsService" value="install-chocolateywindowsservice" /> -* <Xref title="Start-ChocolateyWindowsService" value="start-chocolateywindowsservice" /> -* <Xref title="Stop-ChocolateyWindowsService" value="stop-chocolateywindowsservice" /> -* <Xref title="Uninstall-ChocolateyWindowsService" value="uninstall-chocolateywindowsservice" /> - -## Variables - -There are also a number of environment variables providing access to some values from the nuspec and other information that may be useful. They are accessed via `$env:variableName`. - -### Environment Variables - -Chocolatey makes a number of environment variables available (You can access any of these with $env:TheVariableNameBelow): - -* TEMP/TMP - Overridden to the CacheLocation, but may be the same as the original TEMP folder -* ChocolateyInstall - Top level folder where Chocolatey is installed -* ChocolateyPackageName - The name of the package, equivalent to the `<id />` field in the nuspec -* ChocolateyPackageTitle - The title of the package, equivalent to the `<title />` field in the nuspec -* ChocolateyPackageVersion - The version of the package, equivalent to the `<version />` field in the nuspec - -#### Advanced Environment Variables - -The following are more advanced settings: - -* ChocolateyPackageParameters - Parameters to use with packaging, not the same as install arguments (which are passed directly to the native installer). Based on `--package-parameters`. -* CHOCOLATEY_VERSION - The version of Choco you normally see. Use if you are 'lighting' things up based on choco version, otherwise take a dependency on the specific version you need. -* ChocolateyForceX86 = If available and set to 'true', then user has requested 32bit version. Automatically handled in built in Choco functions. -* OS_PLATFORM - Like Windows, macOS, Linux. -* OS_VERSION - The version of OS, like 6.1 something something for Windows. -* OS_NAME - The reported name of the OS. -* IS_PROCESSELEVATED = Is the process elevated? -* ChocolateyPackageInstallLocation - Install location of the software that the package installs. Displayed at the end of the package install. - -#### Set By Options and Configuration - -Some environment variables are set based on options that are passed, configuration and/or features that are turned on: - - * ChocolateyEnvironmentDebug - Was `--debug` passed? If using the built-in PowerShell host, this is always true (but only logs debug messages to console if `--debug` was passed) - * ChocolateyEnvironmentVerbose - Was `--verbose` passed? If using the built-in PowerShell host, this is always true (but only logs verbose messages to console if `--verbose` was passed). - * ChocolateyForce - Was `--force` passed? - * ChocolateyForceX86 - Was `-x86` passed? - * ChocolateyRequestTimeout - How long before a web request will time out. Set by config `webRequestTimeoutSeconds` - * ChocolateyResponseTimeout - How long to wait for a download to complete? Set by config `commandExecutionTimeoutSeconds` - * ChocolateyPowerShellHost - Are we using the built-in PowerShell host? Set by `--use-system-powershell` or the feature `powershellHost` - -#### Business Edition Variables - - * ChocolateyInstallArgumentsSensitive - Encrypted arguments passed from command line `--install-arguments-sensitive` that are not logged anywhere. - * ChocolateyPackageParametersSensitive - Package parameters passed from command line `--package-parameters-sensitive` that are not logged anywhere. - * ChocolateyLicensedVersion - What version is the licensed edition on? - * ChocolateyLicenseType - What edition / type of the licensed edition is installed? - -#### Experimental Environment Variables - -The following are experimental or use not recommended: - - * OS_IS64BIT = This may not return correctly - it may depend on the process the app is running under - * CHOCOLATEY_VERSION_PRODUCT = the version of Choco that may match CHOCOLATEY_VERSION but may be different - based on git describe - * IS_ADMIN = Is the user an administrator? But doesn't tell you if the process is elevated. - -#### Not Useful Or Anti-Pattern If Used - - * ChocolateyInstallOverride - Not for use in package automation scripts. Based on `--override-arguments` being passed. - * ChocolateyInstallArguments - The installer arguments meant for the native installer. You should use chocolateyPackageParameters instead. Based on `--install-arguments` being passed. - * ChocolateyIgnoreChecksums - Was `--ignore-checksums` passed or the feature `checksumFiles` turned off? - * ChocolateyAllowEmptyChecksums - Was `--allow-empty-checksums` passed or the feature `allowEmptyChecksums` turned on? - * ChocolateyAllowEmptyChecksumsSecure - Was `--allow-empty-checksums-secure` passed or the feature `allowEmptyChecksumsSecure` turned on? - * ChocolateyChecksum32 - Was `--download-checksum` passed? - * ChocolateyChecksumType32 - Was `--download-checksum-type` passed? - * ChocolateyChecksum64 - Was `--download-checksum-x64` passed? - * ChocolateyChecksumType64 - Was `--download-checksum-type-x64` passed? - * ChocolateyPackageExitCode - The exit code of the script that just ran - usually set by `Set-PowerShellExitCode` - * ChocolateyLastPathUpdate - Set by Chocolatey as part of install, but not used for anything in particular in packaging. - * ChocolateyProxyLocation - The explicit proxy location as set in the configuration `proxy` - * ChocolateyDownloadCache - Use available download cache? Set by `--skip-download-cache`, `--use-download-cache`, or feature `downloadCache` - * ChocolateyProxyBypassList - Explicitly set locations to ignore in configuration `proxyBypassList` - * ChocolateyProxyBypassOnLocal - Should the proxy bypass on local connections? Set based on configuration `proxyBypassOnLocal` - * http_proxy - Set by original `http_proxy` passthrough, or same as `ChocolateyProxyLocation` if explicitly set. - * https_proxy - Set by original `https_proxy` passthrough, or same as `ChocolateyProxyLocation` if explicitly set. - * no_proxy- Set by original `no_proxy` passthrough, or same as `ChocolateyProxyBypassList` if explicitly set. - * ChocolateyPackageFolder - Not for use in package automation scripts. Recommend using `$toolsDir = "$(Split-Path -parent $MyInvocation.MyCommand.Definition)"` as per template generated by `choco new` - * ChocolateyToolsLocation - Not for use in package automation scripts. Recommend using Get-ToolsLocation instead +--- +order: 40 +xref: powershell-reference +title: Chocolatey PowerShell Reference +description: Chocolatey PowerShell Reference +--- +import Xref from '@components/Xref.astro'; + +{/* This documentation file is automatically generated from the files at $sourceFunctions using $($sourceLocation)GenerateDocs.ps1. Contributions are welcome at the original location(s). */} + +> :choco-info: **NOTE** +> +> As we migrate our PowerShell functions to cmdlets, we will add them to our <Xref title="PowerShell cmdlets reference" value="powershell-cmdlet-reference" />. + +In your Chocolatey packaging, you have the ability to use these functions (and others with Chocolatey's <Xref title="PowerShell Extensions" value="extensions" />) to work with all aspects of software management. Keep in mind Chocolatey's automation scripts are just PowerShell, so you can do manage anything you want. + +> :choco-info: **NOTE** +> +> These scripts are for package scripts, not for use directly in PowerShell. This is in the create packages section, not the using Chocolatey section. + +## Main Functions + +These functions call other functions and many times may be the only thing you need in your <Xref title="chocolateyInstall.ps1 file" value="package-scripts" />. + +* <Xref title="Install-ChocolateyPackage" value="install-chocolateypackage" /> +* <Xref title="Install-ChocolateyZipPackage" value="install-chocolateyzippackage" /> +* <Xref title="Install-ChocolateyPowershellCommand" value="install-chocolateypowershellcommand" /> +* <Xref title="Install-ChocolateyVsixPackage" value="install-chocolateyvsixpackage" /> + +## More Functions + +### Administrative Access Functions + +When creating packages that need to run one of the following commands below, one should add the tag `admin` to the nuspec. + +* <Xref title="Install-ChocolateyPackage" value="install-chocolateypackage" /> +* <Xref title="Start-ChocolateyProcessAsAdmin" value="start-chocolateyprocessasadmin" /> +* <Xref title="Install-ChocolateyInstallPackage" value="install-chocolateyinstallpackage" /> +* <Xref title="Install-ChocolateyPath" value="install-chocolateypath" /> - when specifying machine path +* <Xref title="Install-ChocolateyEnvironmentVariable" value="install-chocolateyenvironmentvariable" /> - when specifying machine path +* <Xref title="Install-ChocolateyExplorerMenuItem" value="install-chocolateyexplorermenuitem" /> +* <Xref title="Install-ChocolateyFileAssociation" value="install-chocolateyfileassociation" /> +* <Xref title="Uninstall-ChocolateyPath" value="uninstall-chocolateypath" /> - when specifying machine path + +### Non-Administrator Safe Functions + +When you have a need to run Chocolatey without Administrative access required (non-default install location), you can run the following functions without administrative access. + +These are the functions from above as one list. + +* <Xref title="Install-ChocolateyZipPackage" value="install-chocolateyzippackage" /> +* <Xref title="Install-ChocolateyPowershellCommand" value="install-chocolateypowershellcommand" /> +* <Xref title="Get-ChocolateyPath" value="get-chocolateypath" /> +* <Xref title="Get-ChocolateyWebFile" value="get-chocolateywebfile" /> +* <Xref title="Get-ChocolateyUnzip" value="get-chocolateyunzip" /> +* <Xref title="Install-ChocolateyPath" value="install-chocolateypath" /> - when specifying user path +* <Xref title="Install-ChocolateyEnvironmentVariable" value="install-chocolateyenvironmentvariable" /> - when specifying user path +* <Xref title="Install-ChocolateyPinnedTaskBarItem" value="install-chocolateypinnedtaskbaritem" /> +* <Xref title="Install-ChocolateyShortcut" value="install-chocolateyshortcut" /> +* <Xref title="Uninstall-ChocolateyPath" value="uninstall-chocolateypath" /> - when specifying user path +* <Xref title="Update-SessionEnvironment" value="update-sessionenvironment" /> +* <Xref title="Get-PackageParameters" value="get-packageparameters" /> + +## Complete List (alphabetical order) + + * <Xref title='Format-FileSize' value='format-filesize' /> + * <Xref title='Get-ChecksumValid' value='get-checksumvalid' /> + * <Xref title='Get-ChocolateyConfigValue' value='get-chocolateyconfigvalue' /> + * <Xref title='Get-ChocolateyPath' value='get-chocolateypath' /> + * <Xref title='Get-ChocolateyUnzip' value='get-chocolateyunzip' /> + * <Xref title='Get-ChocolateyWebFile' value='get-chocolateywebfile' /> + * <Xref title='Get-FtpFile' value='get-ftpfile' /> + * <Xref title='Get-OSArchitectureWidth' value='get-osarchitecturewidth' /> + * <Xref title='Get-PackageParameters' value='get-packageparameters' /> + * <Xref title='Get-ToolsLocation' value='get-toolslocation' /> + * <Xref title='Get-UACEnabled' value='get-uacenabled' /> + * <Xref title='Get-UninstallRegistryKey' value='get-uninstallregistrykey' /> + * <Xref title='Get-VirusCheckValid' value='get-viruscheckvalid' /> + * <Xref title='Get-WebFile' value='get-webfile' /> + * <Xref title='Get-WebFileName' value='get-webfilename' /> + * <Xref title='Get-WebHeaders' value='get-webheaders' /> + * <Xref title='Install-BinFile' value='install-binfile' /> + * <Xref title='Install-ChocolateyEnvironmentVariable' value='install-chocolateyenvironmentvariable' /> + * <Xref title='Install-ChocolateyExplorerMenuItem' value='install-chocolateyexplorermenuitem' /> + * <Xref title='Install-ChocolateyFileAssociation' value='install-chocolateyfileassociation' /> + * <Xref title='Install-ChocolateyInstallPackage' value='install-chocolateyinstallpackage' /> + * <Xref title='Install-ChocolateyPackage' value='install-chocolateypackage' /> + * <Xref title='Install-ChocolateyPinnedTaskBarItem' value='install-chocolateypinnedtaskbaritem' /> + * <Xref title='Install-ChocolateyPowershellCommand' value='install-chocolateypowershellcommand' /> + * <Xref title='Install-ChocolateyShortcut' value='install-chocolateyshortcut' /> + * <Xref title='Install-ChocolateyVsixPackage' value='install-chocolateyvsixpackage' /> + * <Xref title='Install-ChocolateyZipPackage' value='install-chocolateyzippackage' /> + * <Xref title='Install-Vsix' value='install-vsix' /> + * <Xref title='Set-PowerShellExitCode' value='set-powershellexitcode' /> + * <Xref title='Start-ChocolateyProcessAsAdmin' value='start-chocolateyprocessasadmin' /> + * <Xref title='Uninstall-BinFile' value='uninstall-binfile' /> + * <Xref title='Uninstall-ChocolateyEnvironmentVariable' value='uninstall-chocolateyenvironmentvariable' /> + * <Xref title='Uninstall-ChocolateyPackage' value='uninstall-chocolateypackage' /> + * <Xref title='Uninstall-ChocolateyPath' value='uninstall-chocolateypath' /> + * <Xref title='Uninstall-ChocolateyZipPackage' value='uninstall-chocolateyzippackage' /> + * <Xref title='Write-FunctionCallLogMessage' value='write-functioncalllogmessage' /> + +## Chocolatey for Business Functions + +* <Xref title="Install-ChocolateyWindowsService" value="install-chocolateywindowsservice" /> +* <Xref title="Start-ChocolateyWindowsService" value="start-chocolateywindowsservice" /> +* <Xref title="Stop-ChocolateyWindowsService" value="stop-chocolateywindowsservice" /> +* <Xref title="Uninstall-ChocolateyWindowsService" value="uninstall-chocolateywindowsservice" /> + +## Variables + +There are also a number of environment variables providing access to some values from the nuspec and other information that may be useful. They are accessed via `$env:variableName`. + +### Environment Variables + +Chocolatey makes a number of environment variables available (You can access any of these with $env:TheVariableNameBelow): + +* TEMP/TMP - Overridden to the CacheLocation, but may be the same as the original TEMP folder +* ChocolateyInstall - Top level folder where Chocolatey is installed +* ChocolateyPackageName - The name of the package, equivalent to the `<id />` field in the nuspec +* ChocolateyPackageTitle - The title of the package, equivalent to the `<title />` field in the nuspec +* ChocolateyPackageVersion - The version of the package, equivalent to the `<version />` field in the nuspec + +#### Advanced Environment Variables + +The following are more advanced settings: + +* ChocolateyPackageParameters - Parameters to use with packaging, not the same as install arguments (which are passed directly to the native installer). Based on `--package-parameters`. +* CHOCOLATEY_VERSION - The version of Choco you normally see. Use if you are 'lighting' things up based on choco version, otherwise take a dependency on the specific version you need. +* ChocolateyForceX86 = If available and set to 'true', then user has requested 32bit version. Automatically handled in built in Choco functions. +* OS_PLATFORM - Like Windows, macOS, Linux. +* OS_VERSION - The version of OS, like 6.1 something something for Windows. +* OS_NAME - The reported name of the OS. +* IS_PROCESSELEVATED = Is the process elevated? +* ChocolateyPackageInstallLocation - Install location of the software that the package installs. Displayed at the end of the package install. + +#### Set By Options and Configuration + +Some environment variables are set based on options that are passed, configuration and/or features that are turned on: + + * ChocolateyEnvironmentDebug - Was `--debug` passed? If using the built-in PowerShell host, this is always true (but only logs debug messages to console if `--debug` was passed) + * ChocolateyEnvironmentVerbose - Was `--verbose` passed? If using the built-in PowerShell host, this is always true (but only logs verbose messages to console if `--verbose` was passed). + * ChocolateyForce - Was `--force` passed? + * ChocolateyForceX86 - Was `-x86` passed? + * ChocolateyRequestTimeout - How long before a web request will time out. Set by config `webRequestTimeoutSeconds` + * ChocolateyResponseTimeout - How long to wait for a download to complete? Set by config `commandExecutionTimeoutSeconds` + * ChocolateyPowerShellHost - Are we using the built-in PowerShell host? Set by `--use-system-powershell` or the feature `powershellHost` + +#### Business Edition Variables + + * ChocolateyInstallArgumentsSensitive - Encrypted arguments passed from command line `--install-arguments-sensitive` that are not logged anywhere. + * ChocolateyPackageParametersSensitive - Package parameters passed from command line `--package-parameters-sensitive` that are not logged anywhere. + * ChocolateyLicensedVersion - What version is the licensed edition on? + * ChocolateyLicenseType - What edition / type of the licensed edition is installed? + +#### Experimental Environment Variables + +The following are experimental or use not recommended: + + * OS_IS64BIT = This may not return correctly - it may depend on the process the app is running under + * CHOCOLATEY_VERSION_PRODUCT = the version of Choco that may match CHOCOLATEY_VERSION but may be different - based on git describe + * IS_ADMIN = Is the user an administrator? But doesn't tell you if the process is elevated. + +#### Not Useful Or Anti-Pattern If Used + + * ChocolateyInstallOverride - Not for use in package automation scripts. Based on `--override-arguments` being passed. + * ChocolateyInstallArguments - The installer arguments meant for the native installer. You should use chocolateyPackageParameters instead. Based on `--install-arguments` being passed. + * ChocolateyIgnoreChecksums - Was `--ignore-checksums` passed or the feature `checksumFiles` turned off? + * ChocolateyAllowEmptyChecksums - Was `--allow-empty-checksums` passed or the feature `allowEmptyChecksums` turned on? + * ChocolateyAllowEmptyChecksumsSecure - Was `--allow-empty-checksums-secure` passed or the feature `allowEmptyChecksumsSecure` turned on? + * ChocolateyChecksum32 - Was `--download-checksum` passed? + * ChocolateyChecksumType32 - Was `--download-checksum-type` passed? + * ChocolateyChecksum64 - Was `--download-checksum-x64` passed? + * ChocolateyChecksumType64 - Was `--download-checksum-type-x64` passed? + * ChocolateyPackageExitCode - The exit code of the script that just ran - usually set by `Set-PowerShellExitCode` + * ChocolateyLastPathUpdate - Set by Chocolatey as part of install, but not used for anything in particular in packaging. + * ChocolateyProxyLocation - The explicit proxy location as set in the configuration `proxy` + * ChocolateyDownloadCache - Use available download cache? Set by `--skip-download-cache`, `--use-download-cache`, or feature `downloadCache` + * ChocolateyProxyBypassList - Explicitly set locations to ignore in configuration `proxyBypassList` + * ChocolateyProxyBypassOnLocal - Should the proxy bypass on local connections? Set based on configuration `proxyBypassOnLocal` + * http_proxy - Set by original `http_proxy` passthrough, or same as `ChocolateyProxyLocation` if explicitly set. + * https_proxy - Set by original `https_proxy` passthrough, or same as `ChocolateyProxyLocation` if explicitly set. + * no_proxy- Set by original `no_proxy` passthrough, or same as `ChocolateyProxyBypassList` if explicitly set. + * ChocolateyPackageFolder - Not for use in package automation scripts. Recommend using `$toolsDir = "$(Split-Path -parent $MyInvocation.MyCommand.Definition)"` as per template generated by `choco new` + * ChocolateyToolsLocation - Not for use in package automation scripts. Recommend using Get-ToolsLocation instead diff --git a/src/content/docs/en-us/create/package-dependencies.mdx b/src/content/docs/en-us/create/package-dependencies.mdx index afcdfc359f5..0476c0a716c 100644 --- a/src/content/docs/en-us/create/package-dependencies.mdx +++ b/src/content/docs/en-us/create/package-dependencies.mdx @@ -55,8 +55,10 @@ Now that you see how dependencies are defined, their syntax, and how they work, It is also helpful for very complex packages where a package may take a dependency, which in turn has another dependency. Chocolatey will walk this dependency chain all the way to the beginning, and work backwards until all dependencies are met, and then proceed to install your requested package. +See [`ferventcoder.chocolatey.utilities nuspec`](https://github.com/ferventcoder/chocolatey-packages/blob/master/manual/ferventcoder.chocolatey.utilities/ferventcoder.chocolatey.utilities.nuspec) as an example of what you can do. + ## Wrapping up As you can see dependencies in Chocolatey packages are relatively easy to understand, define, and utilize in your Chocolatey packaging! We encourage you to take advantage of this enhanced functionality in your environments. -Still have questions? Join our [Discord](Community Chat)! If you're a Chocolatey For Business customer, run `choco support` to see how to get in touch with our support team, who are at the ready to assist you with Package Dependencies! \ No newline at end of file +Still have questions? Join our [Discord](Community Chat)! If you're a Chocolatey For Business customer, run `choco support` to see how to get in touch with our support team, who are at the ready to assist you with Package Dependencies! diff --git a/src/content/docs/en-us/create/package-faq.mdx b/src/content/docs/en-us/create/package-faq.mdx new file mode 100644 index 00000000000..54885efa81f --- /dev/null +++ b/src/content/docs/en-us/create/package-faq.mdx @@ -0,0 +1,26 @@ +--- +order: 35 +xref: package-faq +title: Chocolatey Package FAQ +description: Frequently Asked Questions about Chocolatey packages and packaging. +--- +import Callout from '@choco/components/Callout.astro'; +import Iframe from '@choco/components/Iframe.astro'; +import Xref from '@components/Xref.astro'; + +## Where is the Chocolatey Package Path? + +The Chocolatey package path is located at `$env:ChocolateyInstall\lib\<PACKAGENAME>` where: + +- `$env:ChocolateyInstall` is the value of the `ChocolateyInstall` PowerShell environment variable (by default this is `C:\ProgramData\chocolatey`). +- `<PACKAGENAME>` is the ID of the package you are installing. + +## How Do I Restrict What Versions of Windows a Package Will Install On + +If the package is installing software that is only supported on a specific version of Windows, you need to **throw a terminating error** which Chocolatey CLI will detect and indicate a package installation failure. In PowerShell, you can create throw an exception using [`throw`](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_throw?view=powershell-5.1). + +There are a very small number of packages where this rule will not apply: packages, such as Windows KB's, that are used as dependencies and need to be installed even if they do not install anything. If the package failed, and it was a dependency of another package, it may cause issues for the parent package. + +## How Do I Stop Packages From Being Installed on Some Versions of Windows + +See [How Do I Restrict What Versions of Windows a Package Will Install On](#how-do-i-restrict-what-versions-of-windows-a-package-will-install-on). diff --git a/src/content/docs/en-us/create/package-metadata-nuspec.mdx b/src/content/docs/en-us/create/package-metadata-nuspec.mdx new file mode 100644 index 00000000000..6b157cf003f --- /dev/null +++ b/src/content/docs/en-us/create/package-metadata-nuspec.mdx @@ -0,0 +1,200 @@ +--- +order: 25 +xref: package-metadata +title: Chocolatey Package Metadata File (.nuspec) +description: Information about the Chocolatey package `.nuspec` Metadata File +--- +import Callout from '@choco/components/Callout.astro'; +import Iframe from '@choco/components/Iframe.astro'; +import Xref from '@components/Xref.astro'; +import CollapseButton from '@choco/components/CollapseButton.astro'; + +<Callout type="warning"> + When creating package metadata `.nuspec` files: + - Use the UTF-8 character encoding for the package metadata `.nuspec` file. If you don't respect this rule, some characters may not displayed correctly. + - Avoid using Windows Notepad as it is still behind in capabilities as compared to other editors. Alternatives: + - [Visual Studio Code](https://community.chocolatey.org/packages/vscode) + - [Notepad++](http://community.chocolatey.org/packages/notepadplusplus) + - [Geany](http://community.chocolatey.org/packages/geany) +- Use this **XML declaration**: `<?xml version="1.0" encoding="utf-8"?>`. +</Callout> + +Chocolatey packages are based on the [NuGet package format](https://learn.microsoft.com/en-us/nuget/reference/nuspec) and have taken the basic information (called metadata) about the package such as the version, the license, maintainers, and package dependencies and extended it. + +<Callout type="warning"> + <Xref title="Additional rules apply" value="create-packages-for-ccr" /> if you are creating packages for the [Chocolatey Community Repository](https://community.chocolatey.org). +</Callout> + +<Callout type="warning"> + If your package uses functionality introduced in specific versions of Chocolatey CLI, you should include `chocolatey` as a dependency, including the version number where the functionality was introduced. Otherwise, the installation could fail for users with an older version of Chocolatey CLI installed. + + You can include the dependency using: + +```xml + <dependencies> + <dependency id="chocolatey" version="2.0.0" /> + </dependencies> +``` + +See <Xref title="package dependencies" value="package-dependencies" /> for more information +</Callout> + +Unless stated, all metadata fields are optional. + +### Naming Your Package: `<id>` Metadata Field (**Required**) + +```xml +<id>adobereader</id> +``` + +There are some guidelines in terms of the package **ID** (`<id>` tag in the package metadata `.nuspec` file): + +* Use only lowercase letters, even if you used uppercase letters in the package title. This keeps the package names consistent in the destination repository. +* If the original application name consists of compound words without spaces, for example _MKVToolNix_, _TightVNC_ and _VirtualBox_, the package `<id>` is simply the same: `mkvtoolnix`, `tightvnc`, and `virtualbox`. +* If the name of the application contains multiple words separated by spaces, such as _MusicBrainz Picard_ or _Adobe Reader_, replace the spaces with the hyphen-minus character “-” (U+002D), or just omit them. +* **Don't use dots**. + We recommended you use the hyphen method when there are long package names to ensure they remain readable. +* For sub-packages, use the hyphen-minus character “-” (U+002D) as the separator, not a dot. Sub-packages are intended for separate packages that include extensions, modules or additional features/files for other applications. + Therefore `keepass-langfiles` is a proper package `<id>`, because it adds the language files for the main application which in this case is _KeePass_. + Another example is `libreoffice-help` for the help pack for _LibreOffice_, the open source office suite. + +These guidelines are already commonly applied on packages for all major Linux distributions, because they lead to a more consistent user experience for software repositories, result in easier to remember package IDs, and reduce unnecessary considerations on naming packages for package creators. + +export const collapse1 = { + id: 'namingPackagesSXSInstallation', + title: 'Naming Packages to Allow for Side-by-Side Installation', +}; + +<CollapseButton content={collapse1}> +#### Naming Packages to Allow for Side-by-Side Installation + +<Callout type="info"> + The ability to use side-by-side packages was <Xref title="removed in version 2.0.0 of Chocolatey CLI" value="upgrading-to-chocolatey-v2-v6" anchor="side-by-side-installs-have-been-removed-1" />. +</Callout> + +For some software, it is expected that users may want multiple different versions installed simultaneously. +This has commonly been seen with software like Python which offer some kind of runtime dependency that other scripts or applications depend on. + +In the past, Chocolatey CLI supported a "side-by-side" installation method which could be used for this purpose to install multiple distinct versions side-by-side, on the same machine. +This has been deprecated and is no longer supported in version 2.0.0 due to many issues with the use and implementation of the feature. + +#### If the Software You're Creating a Package for Expects **Side-by-Side Installations of Different Versions** + +<Callout type="info"> + The ability to use side-by-side packages was <Xref title="removed in version 2.0.0 of Chocolatey CLI" value="upgrading-to-chocolatey-v2-v6" anchor="side-by-side-installs-have-been-removed-1" />. +</Callout> + +1. Create _separate package IDs_ for each major version (or major + minor version, depending on the expectations of users) which include the version number in the ID. + For example, if the package ID would be `python`, the package for major version 2 would be `python2`, or a package for specifically the 2.7 branch might be `python27` or `python2-7`. + These individual versioned packages can be updated as normal, as long as that major and/or minor version is still receiving further updates. +1. Create a <Xref title="**metapackage**" value="getting-started" anchor="terminology" /> for the overall product with a package version for each of the versioned packages. + In other words, create another package (this time without a version number in the ID), which contains only a `nuspec` file and add a dependency on the versioned package. + Following the above example for Python, we'd create a package with the ID `python` at version `2.0.0` that takes a dependency on the `python2` package. +1. New versions of the metapackage should be published for "sub-versions" of the dependency package as well. + For example, if Python version `3` is released, we'd create a new version of the `python` package with its version set to `3.0.0`, which depends on a new `python3` package. + +#### If the Software You're Creating a Package for Expects **Side-by-Side Installations of the Same Version** + +<Callout type="info"> + The ability to use side-by-side packages was <Xref title="removed in version 2.0.0 of Chocolatey CLI" value="upgrading-to-chocolatey-v2-v6" anchor="side-by-side-installs-have-been-removed-1" />. +</Callout> + +A possible example might be where multiple different instances of the software are being installed into different install directories. + +Chocolatey does not currently support this functionality. +This functionality can be mimicked by making use of `--force` to forcibly overwrite an already-installed package and providing an argument or package parameter that the package can use to direct the installation to install into a different directory. +However, Chocolatey will only be aware of the most-recently installed copy of the software, and will only be able to provide updates to that single installation of the software in most cases. +As a result, this particular configuration is not supported. + +A potential workaround for users maintaining their own package repositories is to maintain separate instances of the same package under different package IDs, where each package ships the same software, but is scripted to install to a different directory. +For example, you can create a `python3-localtoolsfolder` and a `python3-programfilesfolder` package which have the same contents, with only slight differences in the parameters passed to the install functions to ensure they install in the desired locations. +The recommended naming conventions here are similar to sub-packages, where the package is named after the primary package ID followed by a dash and a discriminator, likely named after the install location or referencing the purpose of the additional package(s). +</CollapseButton> + +### Package Version: `<version>` Metadata Field + +```xml +<version>2023.003.20215</version> +``` + +Versioning can be both simple and complicated. The best recommendation is to use the same versioning that the software uses. With Chocolatey CLI you get four version segments. If the software only uses 1, 2 or 3 version segments, follow suit. + +export const collapse2 = { + id: 'packageFixVersionNotation', + title: 'Package Fix Version Notation', +}; + +<CollapseButton content={collapse2}> +### Package Fix Version Notation + +Package fix version notation is used when the package needs to be updated, but the software stays at the same version. + +If the software is `1.1.0`, in a normal scenario the package version would be `1.1.0`. If you find that the `1.1.0` _package_ has an issue, that is where package fix version notation comes into play. You would end up with both a `1.1.0` package and a `1.1.0.YYYYMMDD` version of the package. + +If you need to fix an approved package for some reason, you can use the fourth version segment for a package fix notation. There are two recommended methods of package fix version notation: + +- **Date Package fix Version (`yyyyMMdd`)**. Use this notation, as in `20120627` seen as `1.2.0.20120627`. +- **Sequential Package Fix Version Notation**. Sequential numbering uses `0` for no fix, `1` for first fix and so on, seen as `1.2.0.0` and `1.2.0.1`. + +It is recommended: + +- Date Package Fix Version Notation is recommended because one can ascertain what it is immediately upon seeing it, where sequential is not obvious on sight whether it is part of the software versioning or something special with the package. +- Package fix version notation should only be used in the fourth segment. Do not use any of the other segments for package fix notation. If an application only uses 1 or 2 version segments, add zeros into the other segments until you get to the 4th segment (i.e. `1.0.0.20120627`). When the fourth segment is already used, it is recommended to add two zeroes (`00`) to the end of the version. Then, when you need to fix, you just increment that number. So if the package was `ruby` and the version was `2.0.0-p353`, the package is `2.0.0.35300` (adding the two zeroes at the end). Then a fix would be `2.0.0.35301` and so on. + +<Callout type="warning"> + If you decide to add a secondary set of numbers to the fourth segment, you MUST ALWAYS include that secondary set of numbers while the other three version segments are the same. If you fix `.1` to `.100`, then release `.2`, `.100` is greater than `.2` because versioning doesn't look at the `.`, only the number in the element. So `100` is greater than `2`. +</Callout> +</CollapseButton> + +### Package Title: `<title>` Metadata field (**Required**) + +```xml +<title>Adobe Acrobat Reader DC +``` + +The **title** of your package should be the same as the name of the application. +Follow the official spelling, use upper and lower case and don't forget the spaces. +Examples of correct package titles are: _Google Chrome_, _CCleaner_, _PuTTY_ and _FileZilla_. +The title will appear on the left side in the package list of the Chocolatey Community Repository, followed by the version. + +### Package Icon: `` Metadata Field + +```xml +https://cdn.jsdelivr.net/gh/pauby/ChocoPackages@fb3fc3a/icons/adobereader.png +``` + +If there is an icon which is suitable for your package, you can specify it in the `` field. But there are a few things you should consider: + +* **Avoid hotlinking icons from sites where you don't have control over the file**. If you use your own packages repository (), use your own copy of the icon and put it there. +* **Use a static CDN for icon URLs that permits you to serve files hosted in a repository on GitHub.** Some CDN services cache files permanently, and it's therefore best to use a specific tag or commit URL, not a branch URL. While we don't make any recommendations about specific services, the more popular ones used by maintainers are [jsDelivr](https://www.jsdelivr.com/), [Statically](https://statically.io/) and [Githack](https://raw.githack.com/). +* **Avoid using GitHub raw links** (`https://raw.githubusercontent.com/...`). They are not intended to be used as CDN. +* **Use the software's icon if one is available, not the logo.** This [blog post](https://blog.designcrowd.com/article/353/differences-between-logos-and-icons) explains the difference between logos and icons. If the software of your package doesn't have an icon, but a logo with text and an image, you can extract the image with your favorite image editor and use that as package icon. An example is [MySQL's dolphin](https://community.chocolatey.org/packages/mysql). +* Good sources for package icons are the official desktop icons of the corresponding application you want to make a package of. The icons can be extracted from the app executables using tools like [BeCyIconGrabber](https://community.chocolatey.org/packages/becyicongrabber). Remember to take the icon with 128px or more and save it as PNG file. + +### Package Description: ` Metadata Field + +```xml + +This package installs/upgrades the Multi-lingual ("MUI") release. In some cases, this package will by default be able to install over the top of a language-specific installation. Otherwise, this package will exit and require either a manual uninstall of the language specific installation or having the parameter '/OverwriteInstallation' set to do this automatically. + +## Note + +If the package fails on Windows 8.1 or earlier, this might be due to the installation of kb2919355 (which is a dependency of this package) if your system is not up-to-date. This KB requires a reboot of the system before the adobereader package installs successfully. + +``` + +The `` of the package should contain a short text or at least a few words about the software for which the package is made. Here are a few things that should be respected: + +- It should not just contain a repetition of the package name. +- It should not just consist of a link where more information can be found. For that purpose there's already ``. +- The contents of `` are parsed as Markdown, so don't insert line breaks in the middle of sentences. Remember to add empty lines to separate paragraphs and add an empty line before a list. + +### Package Release Notes: `` Metadata Field + +```xml +https://helpx.adobe.com/acrobat/release-note/release-notes-acrobat-reader.html +``` + +The `` of the package should contain the release notes or a URL to them. Here are a few things that should be respected: + +- The contents of `` are parsed as Markdown, so don't insert line breaks in the middle of sentences. Remember to add empty lines to separate paragraphs and add an empty line before a list. diff --git a/src/content/docs/en-us/create/package-scripts.mdx b/src/content/docs/en-us/create/package-scripts.mdx new file mode 100644 index 00000000000..b55d9e753f6 --- /dev/null +++ b/src/content/docs/en-us/create/package-scripts.mdx @@ -0,0 +1,117 @@ +--- +order: 35 +xref: package-scripts +title: Chocolatey Package PowerShell Scripts +description: Information about the Chocolatey package scripts. +--- +import Callout from '@choco/components/Callout.astro'; +import Iframe from '@choco/components/Iframe.astro'; +import Xref from '@components/Xref.astro'; + + + if you are creating packages for the [Chocolatey Community Repository](https://community.chocolatey.org). + + +## When Will Package Scripts Be Run? + +The table below shows which scripts are available, and which commands will cause them to be run. + + + For an upgrade, the `chocolateyInstall.ps1` script will be the one included in the _new package_. The `chocolateyBeforeModify.ps1` script will be the one _from the previously installed package_. + + +Script Name | Install | Upgrade | Uninstall +-------------------------------------------------|---------|---------|---------- +`chocolateyBeforeModify.ps1` | | | +`chocolateyInstall.ps1` | | | +`chocolateyUninstall.ps1` | | | + +## Chocolatey Install Script: `chocolateyInstall.ps1` + + + The `chocolateyInstall.ps1` script is not required. If a package does not contain the script then the contents of the package will be extracted to the . Any executable files will be . + + +Chocolatey CLI will look for this script and if found, execute it during package installation or upgrade. See the for more information on the Chocolatey provided PowerShell that you can use. + +It really is just PowerShell, so you can use regular PowerShell here and it should run fine. + +### When is the Script Run? + +If present in a package, the `chocolateyInstall.ps1` script will be run at the following points: + +- When a package is for the first time, after the package contents have been extracted. +- When , the `chocolateyInstall.ps1` script for the new package will be executed after any `chocolateyBeforeModify.ps1` script associated with the previous version of the package. + +### Example + +This is what it takes to install [StExBar](https://community.chocolatey.org/packages/stexbar): + +```powershell +$name = 'StExBar' +$url = 'http://stexbar.googlecode.com/files/StExBar-1.8.3.msi' +$url64 = 'http://stexbar.googlecode.com/files/StExBar64-1.8.3.msi' +$silent = '/quiet' + +Install-ChocolateyPackage -PackageName $name -FileType 'MSI' -Url $url -Url64Bit $url64 -SilentArgs $silent +``` + +`Install-ChocolateyPackage` uses the passed parameters to download and silently install, or upgrade, StExBar. See the for more information. + +## Chocolatey Before Modification Script: `chocolateyBeforeModify.ps1` + + + The `chocolateyBeforeModify.ps1` script is not required. + + +Chocolatey CLI will look for this script and if found, execute it during package upgrade or uninstall. See the for more information on the Chocolatey provided PowerShell that you can use. + +It really is just PowerShell, so you can use regular PowerShell here and it should run fine. + +This script is used to stop processes, stop services or otherwise put the system into a state where the package can be upgraded or uninstalled safely. + +### When is the Script Run? + +If present in a package, the `chocolateyBeforeModify.ps1` script will be run at the following points: + +- When a package is , before the package contents have been extracted, the `chocolateyBeforeModidy.ps1` _from the currently installed package_ is run. +- When , the `chocolateyBeforeModify.ps1` script for the new package will be executed after any `chocolateyUninstall.ps1` script, _from the currently installed package_ is run. + +### Example + +```powershell +Get-Process -Name 'Example' -ErrorAction SilentlyContinue | Stop-Process +``` + +This will look for the process 'Example' and stop it if it exists. If it does not exist, it does nothing. + +## Chocolatey Uninstall Script: `chocolateyUninstall.ps1` + + + The `chocolateyUninstall.ps1` script is not required. If a package does not contain the script then the Chocolatey Automatic Uninstaller will uninstall the package as best it can, if enabled, and the will be removed. + + + +Chocolatey CLI will look for this script and if found, execute it during package uninstall. See the for more information on the Chocolatey provided PowerShell that you can use. + +It really is just PowerShell, so you can use regular PowerShell here and it should run fine. + +This script is used to uninstall any software and remove any changes that were made as part of the package installation. For example, if you manually added the software to the Start menu, added registry keys and added anything to the `PATH`, you would remove it again in this script. If a package does not uninstall cleanly then end-user will have to manually clean up after it. Be a good maintainer and write an uninstaller that cleans everything up. + +### When is the Script Run? + +If present in a package, the `chocolateyUninstall.ps1` script will be run at the following points: + +- When , the `chocolateyUninstall.ps1` script will be run before the . + +### Example + +```powershell +$name = 'Example' +$silent = '/quiet' + +Uninstall-ChocolateyPackage -PackageName $name -FileType 'EXE' -SilentArgs $silent -ValidExitCodes @(0, 1603) +``` + +`Uninstall-ChocolateyPackage` uses the passed parameters to uninstall the software silently. See the for more information. + diff --git a/src/content/docs/en-us/faqs.mdx b/src/content/docs/en-us/faqs.mdx index 5ef140e1b85..70d660d0ec5 100644 --- a/src/content/docs/en-us/faqs.mdx +++ b/src/content/docs/en-us/faqs.mdx @@ -8,6 +8,54 @@ import Callout from '@choco/components/Callout.astro'; import Iframe from '@choco/components/Iframe.astro'; import Xref from '@components/Xref.astro'; +### Windows Environment Variables + +Chocolatey installations are advised to be performed while running "as administrator". Because of this it is important that you understand that some windows environment variables will be pinned to the administrator user and not the installation user at least +one circumstance. + +On many systems there are multiple accounts. The issue can occur on a system where there is an admin user with an account type of "Administrator", let's call this user **admin**. There is another user with an account type of "Standard User" lets call this second user **user**. + + + "Administrator" and "Standard User" are the 2 account types that Windows 10 supports. + + +When **admin** chooses to run a `cmd` shell with elevated privileges by right clicking and selecting "Run as administrator". **admin** will be warned by "User Access Control" that they are elevating privileges via a dialog that **admin** can dismiss. The command shell will run the shell with administrator rights from the **admin** account. All good! + +When **user** chooses to run a `cmd` shell by right clicking and selecting "Run as administrator", **user** will be asked to enter the credentials for **admin** account to gain administrator rights. **user** will need to enter **admin**'s credentials and then the command shell will run the shell with administrator rights from the **admin** account. Wait... what? + +Yes, really. An elevated command shell for **user** will run as if it is the **admin** user! + +That means that when your installer depends on any environment variables to find install locations there is a scenario where the environment variables are from a different user (e.g. **admin**) than the user installing the package. + +The known affected environment variables are: `APPDATA`, `LOCALAPPDATA`, `TEMP`, `TMP`, `USERNAME`, `USERPROFILE` + +Example Settings for a user named "administrator": + +``` +APPDATA=C:\Users\administrator\AppData\Roaming +LOCALAPPDATA=C:\Users\administrator\AppData\Local +TEMP=C:\Users\administrator\AppData\Local\Temp +TMP=C:\Users\administrator\AppData\Local\Temp +USERNAME=administrator +USERPROFILE=C:\Users\administrator +``` + +A simple way around this is to ask the user to set environment variables that can override environment variables. Or alternatively, instruct your users to set the necessary environment variables in the elevated privileges command shell. + +Example instructions: + +> Within the administrator command shell you will need to set 2 environment variables: +> +> ``` +> set LOCALAPPDATA=C:\Users\\AppData\Local +> set USERPROFILE=C:\Users\ +> ``` + + + + + + ## General ### Can't find your answer here? @@ -492,4 +540,4 @@ A typical way of stating the difference is "Developers use NuGet to get 3rd part ### How is/will Chocolatey be different than apt? * Chocolatey does not support the idea of source packages, which are packages that must be built to be used. For someone interested in that, check out https://github.com/Microsoft/vcpkg. - * Library packages are not completely off the plate, but mostly. How would you link the library up to the application/tool? \ No newline at end of file + * Library packages are not completely off the plate, but mostly. How would you link the library up to the application/tool? diff --git a/src/content/docs/en-us/features/package-anything.mdx b/src/content/docs/en-us/features/package-anything.mdx index 0d222ce03f5..d60128afb9f 100644 --- a/src/content/docs/en-us/features/package-anything.mdx +++ b/src/content/docs/en-us/features/package-anything.mdx @@ -1,30 +1,48 @@ ---- -order: 30 -xref: package-anything -title: Package anything -description: With Chocolatey you can package up anything, whether it is installers, application, zip, scripts, etc ---- -import Callout from '@choco/components/Callout.astro'; -import Iframe from '@choco/components/Iframe.astro'; -import Xref from '@components/Xref.astro'; - -Chocolatey brings with it the concept of a Universal Packaging format for Windows. At the heart of this is , the automation language for Windows. - -Since on a Windows machine you can pretty much do "anything" with PowerShell, you can pretty much do "anything" within a Chocolatey package. If you need to - -- install an msi or an exe -- deploy a standalone binary -- unzip an archive file -- place some scripts into a particular folder - -Then you can do all of these with Chocolatey. The benefit comes that you will then know exactly what version of these artifacts are deployed onto any machine, and as a result, you will know when some of these artifacts need to be updated. Gone are the days of guessing at what version of a binary is deployed onto any given machine. - -When you couple this with the knowledge that a single Chocolatey package can take a dependency on another Chocolatey package, then you can quite quickly see how simple it can be to chain together a complex installation scenario. For example, let's imagine that you want to install the [`vscode` package](https://community.chocolatey.org/packages/vscode), but you also wanted to perform some custom configuration after the installation was performed. You could create a separate package called `vscode-config`, which takes a dependency on `vscode`, and in that package, you could perform all the necessary configuration that you wanted to achieve. Then, when you run: - -```powershell -choco install vscode-config -``` - -Chocolatey will first ensure that all dependencies for this package are met, and will install the `vscode` package. Once complete, the installation of the `vscode-config` package will happen, and your custom configuration will be applied. The beauty of this approach is separation of concerns that can be achieved. Here the installation of `vscode` is completed as a single unit of work, and then the custom configuration is applied afterward. - -On top of this, Chocolatey has the concept of , which means that you can encapsulate common operations into a single Chocolatey package, which can then be used as a dependency on any other package that needs that functionality. This makes it incredibly simple to consolidate re-usable scripts into a versioned package, that can be used across multiple computers, and packages. A prime example of this is the [`chocolatey-core.extension`](https://community.chocolatey.org/packages/chocolatey-core.extension) package which was created by the Chocolatey Community to provide additional functionality on top of the core functions of Chocolatey itself. \ No newline at end of file +--- +order: 30 +xref: package-anything +title: Package Anything +description: With Chocolatey CLI you can package anything, whether it is installers, application, zip, scripts, etc. +--- +import Callout from '@choco/components/Callout.astro'; +import Iframe from '@choco/components/Iframe.astro'; +import Xref from '@components/Xref.astro'; + +Chocolatey CLI brings with it the concept of a **Universal Packaging format for Windows**. At the heart of this is , the automation language for Windows. + +With a Windows computer, you can do pretty much _anything_ with PowerShell, and you can pretty much do _anything_ within a Chocolatey package. + +Packages have many different uses cases: + +- **Install, upgrade and remove software using the distributed installer**. That installer could be an MSI, an EXE, AppX, MSIX or other type of installer. +- **Add or remove a standalone executable binary file**. The binary file will be on the PATH automatically so the end-user just needs to run it anywhere from the command line. You could add a link on the desktop or Start menu for the desktop experience. +- **Unzip an archive file**. The contents of the archive file can then be used in the way intended: running software, importing into other software or saved for later processing. +- **Adding, updating or removing Windows components and libraries**. Add DLL's, code libraries and other types of Windows components and register them if necessary. +- **Adding, updating or removing scripts**. The scripts can then be available for the end-user to run as normal. +- **Adding, updating or removing registry keys**. Once the registry key files are on the computer, you can import these with standard PowerShell. +- **Importing, or removing, a license. Deploy a license to your computer**. . +- Many more use cases. See [packages types](#package-types) below. + +The benefit comes in knowing what version of these artifacts are deployed onto the computer and, as a result, you will know when some of these artifacts need to be updated. Gone are the days of guessing what version of software, or what license, is deployed onto any given computer. + +When you couple this with the knowledge that a single Chocolatey package can take a dependency on another Chocolatey package, then you can quite quickly see how simple it can be to chain together a complex installation scenario. For example, let's imagine that you want to install the [`vscode` package](https://community.chocolatey.org/packages/vscode), but you also wanted to perform some custom configuration after the installation was performed. You could create a separate package called `vscode-config`, which takes a dependency on `vscode`, and in that package, you could perform all the necessary configuration that you wanted to achieve. Then, when you run: + +```powershell +choco install vscode-config +``` + +Chocolatey CLI will first ensure that all dependencies for this package are met, and will install the `vscode` package. Once complete, the `vscode-config` package will be installed, and your custom configuration will be applied. The beauty of this approach is separation of concerns that can be achieved. Here the installation of `vscode` is completed as a single unit of work, and then the custom configuration is applied afterward. + +## Package Types + +While there is one **Universal Packaging format for Windows**, there are a few different package types: + +- **Package managing software and Windows components**. This package can be used to install, upgrade or uninstall software using the , an or . +- **Package managing scripts**. This package can be used to for use by the end-user, other scripts, modules or applications. +- **Chocolatey extension package**. This package type is used to install, upgrade or uninstall . The Community maintained [`chocolatey-core.extension`](https://community.chocolatey.org/packages/chocolatey-core.extension) package is a good example of this. +- **Chocolatey template package**. Chocolatey CLI comes with a default template type that is used when you run `choco new`. You can create to make repeated packaging, easier. +- **Chocolatey hook package**. A hook package allows . + +With a Windows computer, you can do pretty much _anything_ with PowerShell, and you can pretty much do _anything_ within a Chocolatey package. + +Find out how to diff --git a/src/content/docs/en-us/features/shim.mdx b/src/content/docs/en-us/features/shim.mdx index ae2cce07056..2818d47d7a2 100644 --- a/src/content/docs/en-us/features/shim.mdx +++ b/src/content/docs/en-us/features/shim.mdx @@ -100,13 +100,26 @@ Yes, but we have not decided whether shimming Program Files is a good idea yet o If you are creating a package and you need to shim a file that doesn't end in .exe (like a .bat file), you should look at . -### I need to exclude a file from shimming. +### I Need to Exclude a File From Shimming. -If you are creating a package and you want to skip creation of a shim for a particular file, you can create a "*.ignore" file. +If you are creating a package, and you want to skip creation of a shim for a particular file, create an empty file next to the executable (or where it will be downloaded/unpacked to), sharing the same name with the executable and appending `.ignore`. For example, if your file is named `bob.exe`, you need a file named `bob.exe.ignore` (pay attention to case - "`BOB.exe.ignore`" may not work with all versions of Chocolatey CLI). -Set an empty file next to the executable (or where it will be downloaded/unpacked to), sharing the same name with the executable and appending ".ignore". For example, if your file is named "`bob.exe`", you need a file named "`bob.exe.ignore`" (pay attention to case - "`BOB.exe.ignore`" may not work with all versions of Chocolatey). +Here's a great [programmatic example](https://github.com/ferventcoder/chocolatey-packages/blob/6ea7c087bd999d428a564b5d7e236ae998ef72e9/automatic/git.commandline/tools/chocolateyInstall.ps1#L13-L20): - +```powershell +$files = Get-ChildItem -Path $installDir -Include *.exe -Recurse + +ForEach ($file in $files) { + # generate an ignore file + New-Item -Path "$file.ignore" -type file -force | Out-Null +} +``` + +## How Do I Set Up Shims for Applications That Have a GUI? + +If you don't want to see a hanging window when you open an application from the command line that was installed with Chocolatey CLI, you want to create a file next to the executable that is named exactly the same (**case sensitive**) with `.gui` suffixed on the end. + +Example: In the case of `bob.exe` you would create a file named `bob.exe.gui` and that file would be set up as a GUI application, so the window will call it and then move on without waiting for it to finish. ### I have architecture specific binaries to shim diff --git a/src/content/docs/en-us/guides/usage/development-environment-setup.mdx b/src/content/docs/en-us/guides/usage/development-environment-setup.mdx index 02f5fc78658..1f3f1151bf7 100644 --- a/src/content/docs/en-us/guides/usage/development-environment-setup.mdx +++ b/src/content/docs/en-us/guides/usage/development-environment-setup.mdx @@ -105,7 +105,7 @@ The original is [on github](https://gist.github.com/1107920). ## Getting the Source Create a package for your project and call it projectname*.dev*. It should take a nuspec dependency on whatever source control you use. So in the case of git, a dependency on msysgit. -Now, in , you just need something like the following: +Now, in , you just need something like the following: ```powershell try {