From 79b60fbc4a06bdbfa2ccd0abd9039f7d63ae2a49 Mon Sep 17 00:00:00 2001 From: Rob Reynolds Date: Fri, 5 Jun 2015 17:44:40 -0500 Subject: [PATCH] (GH-296) Add readme template --- src/chocolatey/chocolatey.csproj | 1 + .../services/TemplateService.cs | 1 + .../templates/ChocolateyReadMeTemplate.cs | 114 ++++++++++++++++++ 3 files changed, 116 insertions(+) create mode 100644 src/chocolatey/infrastructure.app/templates/ChocolateyReadMeTemplate.cs diff --git a/src/chocolatey/chocolatey.csproj b/src/chocolatey/chocolatey.csproj index d820e9b50b..21367d6050 100644 --- a/src/chocolatey/chocolatey.csproj +++ b/src/chocolatey/chocolatey.csproj @@ -108,6 +108,7 @@ + diff --git a/src/chocolatey/infrastructure.app/services/TemplateService.cs b/src/chocolatey/infrastructure.app/services/TemplateService.cs index 172fe3c038..7ebb2ebf9b 100644 --- a/src/chocolatey/infrastructure.app/services/TemplateService.cs +++ b/src/chocolatey/infrastructure.app/services/TemplateService.cs @@ -89,6 +89,7 @@ public void generate(ChocolateyConfiguration configuration) generate_file_from_template(configuration, tokens, NuspecTemplate.Template, _fileSystem.combine_paths(packageLocation, "{0}.nuspec".format_with(tokens.PackageNameLower)), Encoding.UTF8); generate_file_from_template(configuration, tokens, ChocolateyInstallTemplate.Template, _fileSystem.combine_paths(packageToolsLocation, "chocolateyinstall.ps1"), Encoding.UTF8); generate_file_from_template(configuration, tokens, ChocolateyUninstallTemplate.Template, _fileSystem.combine_paths(packageToolsLocation, "chocolateyuninstall.ps1"), Encoding.UTF8); + generate_file_from_template(configuration, tokens, ChocolateyReadMeTemplate.Template, _fileSystem.combine_paths(packageToolsLocation, "ReadMe.md"), Encoding.UTF8); this.Log().Info(ChocolateyLoggers.Important, "Successfully generated {0}{1} package specification files{2} at '{3}'".format_with(configuration.NewCommand.Name, configuration.NewCommand.AutomaticPackage ? " (automatic)" : string.Empty, Environment.NewLine, packageLocation)); } diff --git a/src/chocolatey/infrastructure.app/templates/ChocolateyReadMeTemplate.cs b/src/chocolatey/infrastructure.app/templates/ChocolateyReadMeTemplate.cs new file mode 100644 index 0000000000..a7944e9fbe --- /dev/null +++ b/src/chocolatey/infrastructure.app/templates/ChocolateyReadMeTemplate.cs @@ -0,0 +1,114 @@ +// Copyright © 2011 - Present RealDimensions Software, LLC +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +namespace chocolatey.infrastructure.app.templates +{ + public class ChocolateyReadMeTemplate + { + public static string Template = + @"## Summary +How do I create packages? See https://github.com/chocolatey/choco/wiki/CreatePackages + +If you are submitting packages to the community feed (https://chocolatey.org) +always try to ensure you have read, understood and adhere to the create +packages wiki link above. + +## Automatic Packages? +Consider making this package an automatic package, for the best +maintainability over time. Read up at https://github.com/chocolatey/choco/wiki/AutomaticPackages + +## Shim Generation +Any executables you include in the package or download (but don't call +install against using the built-in functions) will be automatically shimmed. + +This means those executables will automatically be included on the path. +Shim generation runs whether the package is self-contained or uses automation +scripts. + +By default, these are considered console applications. + +If the application is a GUI, you should create an empty file next to the exe +named 'name.exe.gui' e.g. 'bob.exe' would need a file named 'bob.exe.gui'. +See https://github.com/chocolatey/choco/wiki/CreatePackages#how-do-i-set-up-batch-redirects-for-applications-that-have-a-gui + +If you want to ignore the executable, create an empty file next to the exe +named 'name.exe.ignore' e.g. 'bob.exe' would need a file named +'bob.exe.ignore'. +See https://github.com/chocolatey/choco/wiki/CreatePackages#how-do-i-exclude-executables-from-getting-batch-redirects + +## Self-Contained? +If you have a self-contained package, you can remove the automation scripts +entirely and just include the executables, they will automatically get shimmed, +which puts them on the path. Ensure you have the legal right to distribute +the application though. See https://github.com/chocolatey/choco/wiki/Legal. + +You should read up on the Shim Generation section to familiarize yourself +on what to do with GUI applications and/or ignoring shims. + +## 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 built-in +functions that you can use, these are sometimes called the helpers. + +### Built-In Functions +https://github.com/chocolatey/choco/wiki/HelpersReference + +A note about a couple: +* Get-BinRoot - this is a horribly named function that doesn't do what new folks think it does. It gets you the 'tools' root, which by default is set to 'c:\tools', not the chocolateyInstall bin folder. +* Install-BinFile - used for non-exe files - executables are automatically shimmed... +* Uninstall-BinFile - used for non-exe files - executables are automatically shimmed + +### Getting package specific information +Use the package parameters pattern - see https://github.com/chocolatey/choco/wiki/How-To-Parse-PackageParameters-Argument + +### Need to mount an ISO? +https://github.com/chocolatey/choco/wiki/How-To-Mount-An-Iso-In-Chocolatey-Package + + +### Environment Variables +Chocolatey makes a number of environment variables available (You can access any of these with $env:TheVariableNameBelow): + + * TEMP = 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 in the nuspec (0.9.9+) + * chocolateyPackageVersion = The version of the package, equivalent to the version in the nuspec (0.9.9+) + * chocolateyPackageFolder = The top level location of the package folder + +#### Advanced Environment Variables +The following are more advanced settings: + + * chocolateyPackageParameters = (0.9.8.22+) + * CHOCOLATEY_VERSION = The version of Choco you normally see. Use if you are 'lighting' things up based on choco version. (0.9.9+) + - Otherwise take a dependency on the specific version you need. + * chocolateyForceX86 = If available and set to 'true', then user has requested 32bit version. (0.9.9+) + - Automatically handled in built in Choco functions. + * OS_PLATFORM = Like Windows, OSX, Linux. (0.9.9+) + * OS_VERSION = The version of OS, like 6.1 something something for Windows. (0.9.9+) + * OS_NAME = The reported name of the OS. (0.9.9+) + * IS_PROCESSELEVATED = Is the process elevated? (0.9.9+) + +#### 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 (0.9.9+) + * CHOCOLATEY_VERSION_PRODUCT = the version of Choco that may match CHOCOLATEY_VERSION but may be different (0.9.9+) + - it's based on git describe + * IS_ADMIN = Is the user an administrator? But doesn't tell you if the process is elevated. (0.9.9+) + * chocolateyInstallOverride = Not for use in package automation scripts. (0.9.9+) + * chocolateyInstallArguments = the installer arguments meant for the native installer. You should use chocolateyPackageParameters intead. (0.9.9+) + +"; + } +} \ No newline at end of file