diff --git a/src/content/docs/en-us/features/package-internalizer.mdx b/src/content/docs/en-us/features/package-internalizer.mdx index 2ee8022549..16de28b403 100644 --- a/src/content/docs/en-us/features/package-internalizer.mdx +++ b/src/content/docs/en-us/features/package-internalizer.mdx @@ -8,106 +8,37 @@ import Callout from '@choco-astro/components/Callout.astro'; import Iframe from '@choco-astro/components/Iframe.astro'; import Xref from '@components/Xref.astro'; -Automatically Internalize/Recompile Existing Packages (Business and MSP Editions Only) +
+
+

Available In:

+

+ Chocolatey for Business +

+
+
-There are thousands of existing packages on the [Chocolatey Community Repository](https://community.chocolatey.org/packages) that are a tremendous resource when it comes to creating packages that have software that can sometimes be tricky! Unfortunately you may be wary of using those packages without changes because many of those packages are subject to distribution rights and thus have an internet dependency (which creates both ). There is a process for downloading and internalizing packages to use internal or embedded locations for that software that is called **internalizing** (also known as recompiling). +## Summary +Chocolatey has over 10,000 packages already built and available on the [Chocolatey Community Repository](https://community.chocolatey.org/packages). If you want to put those packages to use in your organization, look no further than **Package Internalizer**! -Chocolatey for Business is able to automatically download packages and resources, edit the scripts, and recompile packages to internalize and remove internet dependencies from those packages, saving you hours of time in ! +Many of those packages are subject to distribution rights and thus have an internet dependency (which creates both ). **Internalizing** is the process for downloading those packages for use with internal or embedded locations for the software (this may also be referred to as 'recompiling'). -## Usage +Package Internalizer can: -Call `choco download` with options including the name of an existing package for Chocolatey for Business to download and download all existing remote resources. +* Be fully scripted and used directly in the command line. +* Control dependency resolution for packages needing additional software to function. +* Internalize specific versions of packages. +* Integrate with automation engines such as Jenkins, GitHub Actions, GitLab CI, Azure DevOps, and more. -![Internalize Existing Packages, Recompiling Resources - if you are on https://docs.chocolatey.org/en-us/guides/create/recompile-packages, see commented html below for detailed description of image](https://img.chocolatey.org/docs/features/features_recompile_packages.png) - -{/* -Text in the image above: - -Reuse Existing Packages - Automatic Download and Internalize Support - -- Chocolatey for Business allows you to take advantage of thousands of existing packages without a dependency on the internet! -- Downloads an existing package and all remote resources. -- Recompiles the package to use those internal resources. -- Optionally can download and point to another location. -- Host recompiled packages on your private internal repositories! - -This image shows running `choco download --recompile git.install`. - -*/} +Package Internalizer is able to automatically download packages and resources, edit the scripts, remove internet dependencies, and then recompile the packages, saving you hours of time in ! ## See It In Action - -![automatic recompile](https://img.chocolatey.org/docs/gifs/choco_business_features_recompile.gif) - - - See all the [feature videos for Chocolatey for Business](https://chocolatey.org/resources/features#c4b). - - -## Options and Switches - -When running `choco download` in the Business editions, pass the following: - -```powershell - --outputdirectory=VALUE - OutputDirectory - Specifies the directory for the downloaded Chocolatey - package file. If not specified, uses the current directory. - - -i, --ignoredependencies, --ignore-dependencies - IgnoreDependencies - Ignore dependencies when installing package(s). - Licensed editions v1.9.0+ Defaults to false. - - --recompile, --internalize - Recompile / Internalize - Download all external resources and recompile - the package to use the local resources instead. Business editions only - (licensed version 1.5.0+). - - --resources-location=VALUE - Resources Location - When internalizing, use this location for resources - instead of embedding the downloaded resources into the package. Can be a - file share or an internal url location. When it is a file share, it will - attempt to download to that location. When it is an internal url, it - will download locally and give further instructions on where it should - be uploaded to match package edits. Business editions only (licensed - version 1.5.1+). - - --download-location=VALUE - Download Location - OPTIONAL - when internalizing, download the - resources to this location. Used with Resources Location (and defaults - to Resources Location when not set). Business editions only (licensed - version 1.8.3+). - - --append-useoriginallocation, --append-use-original-location - Append -UseOriginalLocation - When `Install-ChocolateyPackage` is - internalized, append the `-UseOriginalLocation` parameter to the - function. Business editions only (licensed version 1.7.0+). Requires at - least Chocolatey v0.10.1 for `Install-ChocolateyPackage` to recognize - the switch appropriately. Overrides the feature - 'internalizeAppendUseOriginalLocation' set to by default to 'False'. -``` - -See for more information. - -## Resources - -Community posts that include Package Internalizer: - -* [Getting Started With Chocolatey 4 Business & Jenkins CI](https://blog.pauby.com/post/getting-started-with-chocolatey-and-jenkins/) -* [Automating Chocolatey package internalizing with PowerShell](https://winsysblog.com/2017/10/automating-chocolatey-package-internalizing-with-powershell.html) ([archive.org](https://web.archive.org/web/20201025112142/https://winsysblog.com/2017/10/automating-chocolatey-package-internalizing-with-powershell.html)) -* [Recompiling Chocolatey packages](https://winsysblog.com/2017/08/recompiling-chocolatey-packages.html) ([archive.org](https://web.archive.org/web/20210815015512/https://winsysblog.com/2017/08/recompiling-chocolatey-packages.html)) +Package Internalizer is a powerful asset for any organization. The short video below shows how to put it to work for you! ## FAQ -### How do I take advantage of this feature? - -You must have a [Business edition of Chocolatey](https://chocolatey.org/compare) or Chocolatey for MSP. Business editions are great for organizations that need to manage the total software management lifecycle. - -### I'm a licensed customer, now what? - -You can run `choco download` and point it to an existing package name on any remote resource, typically folks point to `https://community.chocolatey.org/api/v2/` and let Chocolatey do all of the work of getting the package and remote resources to recompile the package. - ### How does it work? -It downloads a package locally. Then it looks at the install script to determine if there are remote resources, which are downloaded to a directory in the package (or with another switch will be placed on a file share or setup for an http location). Then it edits the install script to use the local resources instead and recompiles the package. The process takes about as long as it takes to download the remote resources. +It downloads a package locally, then it looks at the install script to determine if there are remote resources which are downloaded to a directory in the package (or placed on a file share or setup for an HTTP location; this can be changed with a switch). It then edits the install script to use the local resources and recompiles the package. The process takes about as long as it takes to download the remote resources. ### Does it work with all types of packages? @@ -115,10 +46,10 @@ Some packages are already internalized or don't have remote resources. In those ### It was not able to download a resource. Why not? -This feature is able to download/recompile quite a few packages. There are a few that it may have issues with, especially if variables with methods are used (e.g. `$(somevar).Replace(".","")`). In those cases it attempts to warn you ahead of time that it cannot handle those yet. - -Future versions of the licensed edition will support advanced scenarios such as these. +There are a few resources that it may have issues with, especially if variables with methods are used (e.g. `$(somevar).Replace(".","")`). In those cases it attempts to warn you ahead of time that it cannot handle those yet. Future versions of the licensed edition will support advanced scenarios such as these. ### Are all packages guaranteed to be compatible? -Unfortunately not all packages on the Chocolatey Community Repository are created equal, even with the rigorous moderation process. A few packages do not use the built-in functions for acquiring files from the internet, so they don't lend well to automatic recompiling. Typically Chocolatey will let you know when this is the case and allow you to inspect the package to allow you to finish up the next steps of recompiling. As a future enhancement, it's possible this scenario would also be supported, although it is a very small subset of packages that are created in this way. +Unfortunately, not all packages on the Chocolatey Community Repository are created equal, even with the rigorous . + +Typically, Chocolatey will let you know when a package does not use built-in functions for acquiring files from the internet, and will allow you to inspect the package to finish up the next steps of internalization. Although a small subset of packages are created in this way, this scenario may be supported in a future enhancement.