mirror of
https://github.com/fleschutz/PowerShell.git
synced 2024-12-12 01:31:00 +01:00
132 lines
6.5 KiB
Plaintext
132 lines
6.5 KiB
Plaintext
|
TODO
|
||
|
|
||
|
1. Determine Package Use:
|
||
|
|
||
|
Organization? Internal Use? - You are not subject to distribution
|
||
|
rights when you keep everything internal. Put the binaries directly
|
||
|
into the tools directory (as long as total nupkg size is under 1GB).
|
||
|
When bigger, look to use from a share or download binaries from an
|
||
|
internal location. Embedded binaries makes for the most reliable use
|
||
|
of Chocolatey. Use `$fileLocation` (`$file`/`$file64`) and
|
||
|
`Install-ChocolateyInstallPackage`/`Get-ChocolateyUnzip` in
|
||
|
tools\chocolateyInstall.ps1.
|
||
|
|
||
|
You can also choose to download from internal urls, see the next
|
||
|
section, but ignore whether you have distribution rights or not, it
|
||
|
doesn't apply. Under no circumstances should download from the
|
||
|
internet, it is completely unreliable. See
|
||
|
https://docs.chocolatey.org/en-us/community-repository/community-packages-disclaimer
|
||
|
to understand the limitations of a publicly available repository.
|
||
|
|
||
|
Community Repository?
|
||
|
Have Distribution Rights?
|
||
|
If you are the software vendor OR the software EXPLICITLY allows
|
||
|
redistribution and the total nupkg size will be under 200MB, you
|
||
|
have the option to embed the binaries directly into the package to
|
||
|
provide the most reliable install experience. Put the binaries
|
||
|
directly into the tools folder, use `$fileLocation` (`$file`/
|
||
|
`$file64`) and `Install-ChocolateyInstallPackage`/
|
||
|
`Get-ChocolateyUnzip` in tools\chocolateyInstall.ps1. Additionally,
|
||
|
fill out the LICENSE and VERIFICATION file (see 3 below and those
|
||
|
files for specifics).
|
||
|
|
||
|
NOTE: You can choose to download binaries at runtime, but be sure
|
||
|
the download location will remain stable. See the next section.
|
||
|
|
||
|
Do Not Have Distribution Rights?
|
||
|
- Note: Packages built this way cannot be 100% reliable, but it's a
|
||
|
constraint of publicly available packages and there is little
|
||
|
that can be done to change that. See
|
||
|
https://docs.chocolatey.org/en-us/community-repository/community-packages-disclaimer
|
||
|
to better understand the limitations of a publicly available
|
||
|
repository.
|
||
|
Download Location is Publicly Available?
|
||
|
You will need to download the runtime files from their official
|
||
|
location at runtime. Use `$url`/`$url64` and
|
||
|
`Install-ChocolateyPackage`/`Install-ChocolateyZipPackage` in
|
||
|
tools\chocolateyInstall.ps1.
|
||
|
Download Location is Not Publicly Available?
|
||
|
Stop here, you can't push this to the community repository. You
|
||
|
can ask the vendor for permission to embed, then include a PDF of
|
||
|
that signed permission directly in the package. Otherwise you
|
||
|
will need to seek alternate locations to non-publicly host the
|
||
|
package.
|
||
|
Download Location Is Same For All Versions?
|
||
|
You still need to point to those urls, but you may wish to set up
|
||
|
something like Automatic Updater (AU) so that when a new version
|
||
|
of the software becomes available, the new package version
|
||
|
automatically gets pushed up to the community repository. See
|
||
|
https://docs.chocolatey.org/en-us/create/automatic-packages#automatic-updater-au
|
||
|
|
||
|
2. Determine Package Type:
|
||
|
|
||
|
- Installer Package - contains an installer (everything in template is
|
||
|
geared towards this type of package)
|
||
|
- Zip Package - downloads or embeds and unpacks archives, may unpack
|
||
|
and run an installer using `Install-ChocolateyInstallPackage` as a
|
||
|
secondary step.
|
||
|
- Portable Package - Contains runtime binaries (or unpacks them as a
|
||
|
zip package) - cannot require administrative permissions to install
|
||
|
or use
|
||
|
- Config Package - sets config like files, registry keys, etc
|
||
|
- Extension Package - Packages that add PowerShell functions to
|
||
|
Chocolatey - https://docs.chocolatey.org/en-us/features/extensions
|
||
|
- Template Package - Packages that add templates like this for `choco
|
||
|
new -t=name` - https://docs.chocolatey.org/en-us/guides/create/create-custom-package-templates
|
||
|
- Other - there are other types of packages as well, these are the main
|
||
|
package types seen in the wild
|
||
|
|
||
|
3. Fill out the package contents:
|
||
|
|
||
|
- tools\chocolateyBeforeModify.ps1 - remove if you have no processes
|
||
|
or services to shut down before upgrade/uninstall
|
||
|
- tools\LICENSE.txt / tools\VERIFICATION.txt - Remove if you are not
|
||
|
embedding binaries. Keep and fill out if you are embedding binaries
|
||
|
in the package AND pushing to the community repository, even if you
|
||
|
are the author of software. The file becomes easier to fill out
|
||
|
(does not require changes each version) if you are the software
|
||
|
vendor. If you are building packages for internal use (organization,
|
||
|
etc), you don't need these files as you are not subject to
|
||
|
distribution rights internally.
|
||
|
- tools\chocolateyUninstall.ps1 - remove if autouninstaller can
|
||
|
automatically uninstall and you have nothing additional to do during
|
||
|
uninstall
|
||
|
- Readme.txt - delete this file once you have read over and used
|
||
|
anything you've needed from here
|
||
|
- nuspec - fill this out, then clean out all the comments (you may wish
|
||
|
to leave the headers for the package vs software metadata)
|
||
|
- tools\chocolateyInstall.ps1 - instructions in next section.
|
||
|
|
||
|
4. ChocolateyInstall.ps1:
|
||
|
|
||
|
- For embedded binaries - use `$fileLocation` (`$file`/`$file64`) and
|
||
|
`Install-ChocolateyInstallPackage`/ `Get-ChocolateyUnzip`.
|
||
|
- Downloading binaries at runtime - use `$url`/`$url64` and
|
||
|
`Install-ChocolateyPackage` / `Install-ChocolateyZipPackage`.
|
||
|
- Other needs (creating files, setting registry keys), use regular
|
||
|
PowerShell to do so or see if there is a function already defined:
|
||
|
https://docs.chocolatey.org/en-us/create/functions
|
||
|
- There may also be functions available in extension packages, see
|
||
|
https://community.chocolatey.org/packages?q=id%3A.extension for examples and
|
||
|
availability.
|
||
|
- Clean out the comments and sections you are not using.
|
||
|
|
||
|
5. Test the package to ensure install/uninstall work appropriately.
|
||
|
There is a test environment you can use for this -
|
||
|
https://github.com/chocolatey/chocolatey-test-environment
|
||
|
|
||
|
6. Learn more about Chocolatey packaging - go through the workshop at
|
||
|
https://github.com/chocolatey/chocolatey-workshop
|
||
|
You will learn about
|
||
|
- General packaging
|
||
|
- Customizing package behavior at runtime (package parameters)
|
||
|
- Extension packages
|
||
|
- Custom packaging templates
|
||
|
- Setting up an internal Chocolatey.Server repository
|
||
|
- Adding and using internal repositories
|
||
|
- Reporting
|
||
|
- Advanced packaging techniques when installers are not friendly to
|
||
|
automation
|
||
|
|
||
|
7. Delete this file.
|