manifest.md (12908B)
1 --- 2 title: Create your package manifest 3 description: If you want to submit a software package to the Windows Package Manager repository, start by creating a package manifest. 4 ms.date: 04/29/2020 5 ms.topic: article 6 ms.localizationpriority: medium 7 --- 8 9 # Create your package manifest 10 11 If you want to submit a software package to the [Windows Package Manager Community Repository](repository.md), start by creating a package manifest. The manifest is a YAML file that describes the application to be installed. 12 13 You may either use the [Windows Package Manager Manifest Creator](https://github.com/microsoft/winget-create), the [YAMLCreate](#using-the-yamlcreateps1) PowerShell script, or you can craft a manifest manually following the instructions below. 14 15 ### Using WinGetCreate Utility 16 17 You can install `wingetcreate` utility using the command below. 18 19 ```powershell 20 winget install wingetcreate 21 ``` 22 23 After installation, you can run `wingetcreate new` to create a new package and fill in the prompts. The last option **WinGetCreate** will offer is for you to submit the manifest to the packages repository. If you choose yes, you will automatically submit your Pull Request (PR) to the [Windows Package Manager Community Repository](https://github.com/microsoft/winget-pkgs). 24 25 ### Using the YAMLCreate.ps1 26 To help author manifest files, we have provided a YAMLCreate.ps1 powershell script located in the Tools folder on the [Windows Package Manager Community Repository](https://github.com/microsoft/winget-pkgs). You can use the script by cloning the [Windows Package Manager Community Repository](https://github.com/microsoft/winget-pkgs) on your PC and run the script directly from the **Tools** folder. The script will prompt you for the URL to the installer, then will prompt you to fill in metadata. Like **WinGetCreate**, this script will also offer you to submit your manifest automatically. 27 28 ## YAML basics 29 30 The YAML format was chosen for package manifests because of its relative ease of human readability and consistency with other Microsoft development tools. If you are not familiar with YAML syntax, you can learn the basics at [Learn YAML in Y Minutes](https://learnxinyminutes.com/docs/yaml/). 31 32 > Manifests for Windows Package Manager currently do not support all YAML features. Unsupported YAML features include anchors, complex keys, and sets. 33 34 ## Conventions 35 36 These conventions are used in this article: 37 38 * To the left of `:` is a literal keyword used in manifest definitions. 39 * To the right of `:` is a data type. The data type can be a primitive type like **string** or a reference to a rich structure defined elsewhere in this article. 40 * The notation `[` *datatype* `]` indicates an array of the mentioned data type. For example, `[ string ]` is an array of strings. 41 * The notation `{` *datatype* `:` *datatype* `}` indicates a mapping of one data type to another. For example, `{ string: string }` is a mapping of strings to strings. 42 43 ## Manifest contents 44 45 A package manifest must include a set of required items, and can also include further optional items that can help improve the customer experience of installing your software. This section provides brief summaries of the required manifest schema and complete manifest schemas, and examples of each. 46 47 Each field in the manifest file must be Pascal-cased and cannot be duplicated. 48 49 For a complete list and descriptions of items in a manifest, see the [manifest specification](https://github.com/microsoft/winget-pkgs/tree/master/doc/manifest/schema) in the [https://github.com/microsoft/winget-pkgs](https://github.com/microsoft/winget-pkgs) repository. 50 51 ### Minimal required schema 52 53 #### [Minimal required schema](#tab/minschema/) 54 55 As specified in the [singleton JSON schema](https://github.com/microsoft/winget-cli/blob/master/schemas/JSON/manifests/v1.4.0/manifest.singleton.1.4.0.json), 56 only a number of fields are required. The minimal supported YAML file would look like the example below. The singleton format is only valid for packages containing 57 a single installer and a single locale. If more than one installer or locale is provided, the multiple YAML file format and schema must be used. 58 59 The partitioning scheme was added to help with GitHub's UX. Folders with thousands of children do not render well in the browser. 60 61 62 ```YAML 63 PackageIdentifier: # Publisher.package format. 64 PackageVersion: # Version numbering format. 65 PackageLocale: # BCP 47 format (e.g. en-US) 66 Publisher: # The name of the publisher. 67 PackageName: # The name of the application. 68 License: # The license of the application. 69 ShortDescription: # The description of the application. 70 Installers: 71 - Architecture: # Enumeration of supported architectures. 72 InstallerType: # Enumeration of supported installer types (exe, msi, msix, inno, wix, nullsoft, appx). 73 InstallerUrl: # Path to download installation file. 74 InstallerSha256: # SHA256 calculated from installer. 75 ManifestType: # The manifest file type 76 ManifestVersion: 1.4.0 77 ``` 78 79 #### [Example](#tab/minexample/) 80 81 Path: manifests / m / Microsoft / WindowsTerminal / 1.6.10571.0 / Microsoft.WindowsTerminal.yaml 82 83 ```YAML 84 PackageIdentifier: Microsoft.WindowsTerminal 85 PackageVersion: 1.6.10571.0 86 PackageLocale: en-US 87 Publisher: Microsoft 88 PackageName: Windows Terminal 89 License: MIT 90 ShortDescription: The new Windows Terminal, a tabbed command line experience for Windows. 91 Installers: 92 - Architecture: x64 93 InstallerType: msix 94 InstallerUrl: https://github.com/microsoft/terminal/releases/download/v1.6.10571.0/Microsoft.WindowsTerminal_1.6.10571.0_8wekyb3d8bbwe.msixbundle 95 InstallerSha256: 092aa89b1881e058d31b1a8d88f31bb298b5810afbba25c5cb341cfa4904d843 96 SignatureSha256: e53f48473621390c8243ada6345826af7c713cf1f4bbbf0d030599d1e4c175ee 97 ManifestType: singleton 98 ManifestVersion: 1.4.0 99 ``` 100 101 #### Multiple File Example 102 In order to provide the best user experience, manifests should contain as much meta-data as possible. In order to separate concerns for validating installers 103 and providing localized meta-data manifests will be split into multiple files. The minimum number of YAML files for this kind of manifest is three. Additional 104 locales should also be provided. 105 * A [version](https://github.com/microsoft/winget-cli/blob/master/schemas/JSON/manifests/v1.4.0/manifest.version.1.4.0.json) file 106 * The [default locale](https://github.com/microsoft/winget-cli/blob/master/schemas/JSON/manifests/v1.4.0/manifest.defaultLocale.1.4.0.json) file 107 * An [installer](https://github.com/microsoft/winget-cli/blob/master/schemas/JSON/manifests/v1.4.0/manifest.installer.1.4.0.json) file 108 * Additional [locale](https://github.com/microsoft/winget-cli/blob/master/schemas/JSON/manifests/v1.4.0/manifest.locale.1.4.0.json) files 109 110 The example below shows many optional meta-data fields and multiple locales. Note the default locale has more requirements than additional locales. In the show 111 command, any required fields that aren't provided for additional locales will display fields from the default locale. 112 113 Path: manifests / m / Microsoft / WindowsTerminal / 1.6.10571.0 / Microsoft.WindowsTerminal.yaml 114 115 ```YAML 116 PackageIdentifier: Microsoft.WindowsTerminal 117 PackageVersion: 1.6.10571.0 118 DefaultLocale: en-US 119 ManifestType: version 120 ManifestVersion: 1.4.0 121 ``` 122 123 Path: manifests / m / Microsoft / WindowsTerminal / 1.6.10571.0 / Microsoft.WindowsTerminal.locale.en-US.yaml 124 125 ```YAML 126 PackageIdentifier: Microsoft.WindowsTerminal 127 PackageVersion: 1.6.10571.0 128 PackageLocale: en-US 129 Publisher: Microsoft 130 PublisherURL: https://www.microsoft.com/ 131 PrivacyURL: https://privacy.microsoft.com/ 132 PackageName: Windows Terminal 133 PackageURL: https://docs.microsoft.com/windows/terminal/ 134 License: MIT 135 LicenseURL: https://github.com/microsoft/terminal/blob/master/LICENSE 136 ShortDescription: The new Windows Terminal, a tabbed command line experience for Windows. 137 Tags: 138 - console 139 - command-line 140 - shell 141 - command-prompt 142 - powershell 143 - wsl 144 - developer-tools 145 - utilities 146 - cli 147 - cmd 148 - ps 149 - terminal 150 ManifestType: defaultLocale 151 ManifestVersion: 1.4.0 152 ``` 153 154 Path: manifests / m / Microsoft / WindowsTerminal / 1.6.10571.0 / Microsoft.WindowsTerminal.locale.fr-FR.yaml 155 156 ```YAML 157 PackageIdentifier: Microsoft.WindowsTerminal 158 PackageVersion: 1.6.10571.0 159 PackageLocale: fr-FR 160 Publisher: Microsoft 161 ShortDescription: Le nouveau terminal Windows, une expérience de ligne de commande à onglets pour Windows. 162 ManifestType: locale 163 ManifestVersion: 1.4.0 164 ``` 165 166 Path: manifests / m / Microsoft / WindowsTerminal / 1.6.10571.0 / Microsoft.WindowsTerminal.installer.yaml 167 168 ```YAML 169 PackageIdentifier: Microsoft.WindowsTerminal 170 PackageVersion: 1.6.10571.0 171 Platform: 172 - Windows.Desktop 173 MinimumOSVersion: 10.0.18362.0 174 InstallerType: msix 175 InstallModes: 176 - silent 177 PackageFamilyName: Microsoft.WindowsTerminal_8wekyb3d8bbwe 178 Installers: 179 - Architecture: x64 180 InstallerUrl: https://github.com/microsoft/terminal/releases/download/v1.6.10571.0/Microsoft.WindowsTerminal_1.6.10571.0_8wekyb3d8bbwe.msixbundle 181 InstallerSha256: 092aa89b1881e058d31b1a8d88f31bb298b5810afbba25c5cb341cfa4904d843 182 SignatureSha256: e53f48473621390c8243ada6345826af7c713cf1f4bbbf0d030599d1e4c175ee 183 - Architecture: arm64 184 InstallerUrl: https://github.com/microsoft/terminal/releases/download/v1.6.10571.0/Microsoft.WindowsTerminal_1.6.10571.0_8wekyb3d8bbwe.msixbundle 185 InstallerSha256: 092aa89b1881e058d31b1a8d88f31bb298b5810afbba25c5cb341cfa4904d843 186 SignatureSha256: e53f48473621390c8243ada6345826af7c713cf1f4bbbf0d030599d1e4c175ee 187 - Architecture: x86 188 InstallerUrl: https://github.com/microsoft/terminal/releases/download/v1.6.10571.0/Microsoft.WindowsTerminal_1.6.10571.0_8wekyb3d8bbwe.msixbundle 189 InstallerSha256: 092aa89b1881e058d31b1a8d88f31bb298b5810afbba25c5cb341cfa4904d843 190 SignatureSha256: e53f48473621390c8243ada6345826af7c713cf1f4bbbf0d030599d1e4c175ee 191 ManifestType: installer 192 ManifestVersion: 1.4.0 193 ``` 194 195 * * * 196 197 > If your installer is an .exe and it was built using Nullsoft or Inno, you may specify those values instead. When Nullsoft or Inno are specified, the client will automatically set the silent and silent with progress install behaviors for the installer. 198 199 ## Installer switches 200 201 You can often figure out what silent `Switches` are available for an installer by passing in a `-?` to the installer from the command line. Here are some common silent `Switches` that can be used for different installer types. 202 203 | Installer | Command | Documentation | 204 | :--- | :-- | :--- | 205 | MSI | `/q` | [MSI Command-Line Options](https://docs.microsoft.com/windows/win32/msi/command-line-options) | 206 | InstallShield | `/s` | [InstallShield Command-Line Parameters](https://docs.flexera.com/installshield19helplib/helplibrary/IHelpSetup_EXECmdLine.htm) | 207 | Inno Setup | `/SILENT or /VERYSILENT` | [Inno Setup documentation](https://jrsoftware.org/ishelp/) | 208 | Nullsoft | `/S` | [Nullsoft Silent Installers/Uninstallers](https://nsis.sourceforge.io/Docs/Chapter4.html#silent) | 209 210 ## Tips and best practices 211 212 * The package identifier must be unique. You cannot have multiple submissions with the same package identifier. Only one pull request per package version is allowed. 213 214 * Avoid creating multiple publisher folders. For example, do not create "Contoso Ltd." if there is already a "Contoso" folder. 215 216 * All tools must support a silent install. If you have an executable that does not support a silent install, then we cannot provide that tool at this time. 217 218 * Provide as many fields as possible. The more meta-data you provide the better the user experience will be. In some cases, the fields may not yet be supported 219 by the Windows Package Manager client (winget.exe). For example, the `Moniker` field is optional. However, if you include this field, customers will see results associated with the `Moniker` value when performing the [search](../winget/search.md) command (for example, **vscode** for **Visual Studio Code**). If there is only one app with the specified `Moniker` value, customers can install your application by specifying the moniker rather than the fully qualified package identifier. 220 221 * The length of strings in this specification should be limited to 100 characters before a line break. 222 223 * The "PackageName" and "Publisher" should match the entry made in Add / Remove Programs to help the correlation with manifests to support **export**, and **upgrade**. 224 225 * Package installers in MSI format use [Product Codes](https://docs.microsoft.com/windows/win32/msi/product-codes) to uniquely identify applications. The product code for a given version of a package should be included in the manifest to help ensure the best **upgrade** experience. 226 227 * Limit the length of strings in your manifest to 100 characters before a line break. 228 * When more than one installer type exists for the specified version of the package, an instance of `InstallerType` can be placed under each of the `Installers`.