Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

(#770) Clarify Package Environment variables and their contents #764

Merged
merged 4 commits into from
Jul 25, 2023
Merged

(#770) Clarify Package Environment variables and their contents #764

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
e7bdb2a
(maint) Format list with punctuation
corbob Jun 27, 2023
5384b81
(#770) Add pkg maintainers blurb to upgrade guide
corbob Jun 27, 2023
c820067
(#770) Update Environment Variable information
corbob Jun 27, 2023
0b74de2
(maint) Adjust code spacing
corbob Jul 19, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 24 additions & 21 deletions input/en-us/create/functions/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
---
---
Order: 40
xref: powershell-reference
Title: PowerShell Reference
Expand Down Expand Up @@ -120,11 +120,14 @@ There are also a number of environment variables providing access to some values

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
* 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 lower case `<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.
* Prior to Chocolatey CLI version 2.1.0 this is equivalent to the `<version />` field in the nuspec.
* Starting with Chocolatey CLI version 2.1.0 this is equivalent to the [normalized version](xref:upgrading-to-chocolatey-v2-v6#package-version-normalization) of the `<version />` field in the nuspec.
* If you rely on `ChocolateyPackageVersion` in a URL, ensure that all possible permutations of the package version work (eg: `1.0.0.0`, `1.0.0`, `1.0`, `1.0.00.0`).

#### Advanced Environment Variables

Expand All @@ -143,14 +146,14 @@ The following are more advanced settings:

Some environment variables are set based on options that are passed, configuration and/or features that are turned on:

* ChocolateyExitOnRebootDetected - Are we exiting on a detected reboot? Set by ` --exit-when-reboot-detected` or the feature `exitOnRebootDetected`
* 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)
* ChocolateyExitOnRebootDetected - Are we exiting on a detected reboot? Set by `--exit-when-reboot-detected` or the feature `exitOnRebootDetected`.
* 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`
* 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

Expand All @@ -163,8 +166,8 @@ Some environment variables are set based on options that are passed, configurati

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
* 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
Expand All @@ -178,14 +181,14 @@ The following are experimental or use not recommended:
* 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`
* 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`
* 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
* 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.
4 changes: 4 additions & 0 deletions input/en-us/guides/upgrading-to-chocolatey-v2-v6.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,10 @@ This is [discussed in more depth later](#side-by-side-installs-have-been-removed

### Package Version Normalization

> :choco-note: **NOTE**
>
> **Important information for package maintainers.** The `ChocolateyPackageVersion` [environment variable](xref:powershell-reference#environment-variables) follows the below version normalization. If your package scripts use this variable, and the nuspec specified version falls outside of the normalized format, then they may not behave as expected. We recommend using specific version numbers within your scripts rather depending on these environment variables.

Due to newer semantic version requirements imposed by the NuGet libraries, some version numbers may appear differently than they did in Chocolatey CLI v1.x. Chocolatey CLI 2.0.0 and later will [normalize version numbers](xref:version-normalization) to comply with these new requirements.

### Optimizing Performance
Expand Down
Loading