Make package (makepkg.exe)

Article
04/04/2023

Creates app packages and app package metadata.

makepkg command [/updcompat 3] [/pc] [/gameos <gameos file>] [/priorpackage <prior package file>] [/f <file name>] [/d <content directory>] [/pd <output directory>] [/l | /lk <secret_key.lekb>] [/contentid <ID>] [/productid <ProductIDGUID>] [/nocrashdump] [/resw <resw directory>] [/t <xml output directory>] [/v] [/?]

Commands

genmap

Builds an XML file to be used with the pack command based on contents of a target folder. The generated file will contain a single chunk and can be edited to split into chunks or provide tags as needed.

makepkg genmap /f <targetXmlFile> /d <contentdirectory>

genid

Converts between a Product ID GUID and a Store ID. The generated GUID will match the product ID provided during submission of your product. A product ID GUID can be converted back to a Store ID.

makepkg genid /storeid <storeId> | /productid <productId>

pack

Creates a new app package from files on disk.

makepkg pack /f <mapping file> /d <content directory> /pd <output package directory> /productid <ProductIDGUID> [/l | /lk <secret_key.lekb>]

Creates an app package in the output package directory by adding files specified within the mapping file. For example, to package the contents of a directory with three files-a.txt, b.txt, and game.exe-the following mapping file would be used:

<Package>
    <Chunk Id="1000" Marker="Launch">
        <FileGroup DestinationPath="\" SourcePath=".\" Include="a.txt"/>
        <FileGroup DestinationPath="\" SourcePath=".\" Include="b.txt"/>
        <FileGroup DestinationPath="\" SourcePath=".\" Include="game.exe"/>
    </Chunk>
</Package>

For a description of the mapping file schema, see Deployment Package Schema. The content directory specified (/d) must contain a valid game configuration file with the name MicrosoftGame.config. The MicrosoftGame.config file can be found in the build output directory of your app's Visual Studio project. For a description of the game config schema, see MicrosoftGame.config Schema.

By default, makepkg pack encrypts the package by using a well-known encryption key recognized by all Development Kits for testing purposes (also known as the /lt encryption switch). These packages should not be considered cryptographically protected. To protect the package file for secure upload use the /lk <local EKB file> switch (recommended for development and submission for console) or /l switch, which will override the default behavior.

MakePkg.exe will scan for certain files in your package and will move them to a special registration chunk. Among these files are MicrosoftGame.config, any images referenced within MicrosoftGame.config, and Resources.pri, if present.

NOTE: Use makepkg localize to generate the Resources.pri file. For more advanced scenarios, see the topic for the Make package resource index (makepri.exe) command-line tool.
You can manually lay out these files in the layout.xml file, by specifying "Registration" in the ID attribute for the chunk that contains these files.

NOTE: Makepkg rejects binaries that contain relocations from within executable sections. Such relocations require modifications to the executable section at load time, which could enable code modifications to take place during this time. For this reason, makepkg will fail if it's presented a binary with such traits. One common way to prevent this is to avoid merging read-only data sections into another executable section when compiling your binaries.

validate

Runs the validation steps without building the package. Steps include running Submission Validator, which generates the log file that documents possible issues with package submission. Takes the same parameters as taken by the makepkg pack command, with the exception of the optional mapfile.

makepkg validate [options] [/f <mapfile>] /d <sourcedir> /pd <destinationdir>

localize

Generates a Resources.pri file from PNG and RESW files in a content directory. A MicrosoftGame.config file must be present in the directory in order for localized information to be discovered. This file should specify the language definitions and image files for shell localization. The resulting Resources.pri will be placed at the root of the output directory if supplied and in the content directory if no output directory is supplied. If a temporary directory is supplied, an XML conversion of the Resources.pri file will be generated in that temporary directory for manual validation. For more information about using Resources.pri files, see MicrosoftGame.config localization.

makepkg localize [/d <content directory>] /pd <destinationdir> /resw <resw directory> /t <xml output directory> /gc <game config path>

genkey

Generates a local escrowed key blob (LEKB). A random content key is generated and stored in the LEKB file.

The LEKB generated is for use with the makepkg pack /lk encryption switch. Generally, you will use genkey for every trust boundary you want to have. For example, you could use genkey once and use one key studio-wide, or use one key per product, depending on who should have access to the package.

To generate the LEKB:

makepkg genkey /ekb <The path to save the generated LEKB file.>

To use the LEKB to encrypt your package, using the /lk encryption switch:

makepkg pack /lk <The path to your LEKB file created by the genkey command.>

The LEKB file should be provided as an option to makepkg pack to use a stable encryption key (/lk encryption) during package creation. This has 4 main benefits:

packageutil compare can generate correct update size estimates (unlike /l).
It enables secure delta upload to Partner Center using the same algorithm that consoles and PCs use to download content updates. (unlike /l)
It can be installed onto devkits (unlike /l).
It uses secure encryption key material and can only be decrypted in specific environments (unlike /lt).

The contents of the LEKB file is only lightly obfuscated. It is your responsibility to ensure the security of your content packages by securing access to the LEKB file. Anyone possessing the LEKB file and the content package file output by makepkg pack can decrypt its contents.

NOTE: the extension .lekb for the Local EKB file created by genkey is recommended to distinguish it from the .ekb file generated by makepkg pack, with the "l" standing for "locally created".

Options

Option	Description
/validationpath	Specifies the path to use for loading SubmissionValidator.dll. If this value is not specified, SubmissionValidator.dll will be loaded from the same directory as MakePkg.exe
/updcompat 3	Used with the pack command. The only supported value is 3 which uses sub-file content update granularity.
/pc	Used with the pack command. Optional parameter that indicates that this is an MSIXVC package specifically targeting PC publishing. Packages produced with this flag can be deployed to, tested, or published for Windows 10 PCs only, not for Xbox consoles.
/priorpackage <prior package file>	Used with the pack command. Optional parameter that specifies the prior package file to be used to optimize sub-file content updates. Implies /updcompat 3.
/gameos <gameos file>	Used with the pack command. Optional parameter that specifies the gameos file to be embedded in the package. If this parameter isn't used, or if no gameos file is specified, the GameOs.xvd file is required to be in the layout directory next to the executable.
/storeid <storeId>	Used with the genid command. Specifies the Store ID to use.
/f <file name>	Specifies an input file. When used with the pack or validate command, it specifies a mapping file. When used with the appdata command, it specifies the Application Manifest file.
/d <content directory>	Specifies the content directory. The specified directory (such as the layout\image\loose directory for your project) must contain a valid MicrosoftGame.config file.
/pd <output directory>	Specifies the output directory.
/lk <lekbfile>	Encrypts the package with a content license using a specified ekb file. See the genkey command for more information. By default, makepkg pack encrypts the package by using a well-known encryption key recognized by all devkits for testing purposes. Both the /lk and /l switch override the default behavior. NOTE: When submitting a package to certification, you must use /l or /lk unless the Certification team has directed you to do otherwise.
/l	Encrypts the package with a unique content license. Used with the pack command. By default, makepkg pack encrypts the package by using a well-known encryption key recognized by all devkits for testing purposes. Both the /lk and /l switch override the default behavior. NOTE: When submitting a package to certification, you must use /l or /lk unless the Certification team has directed you to do otherwise.
/contentid <ID>	Optional parameter that specifies the content ID to which this package belongs. The ID is a GUID. If this parameter isn't present or is specified with a value of 00000000-0000-0000-0000-000000000000, a stable GUID based upon the package family name will be used. This parameter isn't necessary when you prepare builds for submission. It's used with the pack command. It is recommended that you do not specify this option or that you keep this option the same between different invocations of makepkg per game product, to enable calculation of update sizes using the packageutil compare utility.
/productid <ProductIDGUID>	Optional parameter that specifies the product ID to which this package belongs. The ID is a GUID. If this parameter isn't present, the GUID will be 00000000-0000-0000-0000-000000000000. This parameter isn't necessary when you prepare builds for submission. It's used with the pack and genid commands. ProductID is to be included when you want to enumerate the DLC packages installed from burned discs, or when the system is running offline.
/symbolpaths	Allows specifying additional paths for symbol resolution lookup during the symbol bundling. The paths should be specified as a semicolon-delimited list.
/skipsymbolbundling	Specifies that the symbol-bundling step is to be skipped. We don't recommend the use of this flag.
/skipvalidation	Specifies that the validation step is to be skipped. No Submission Validator log file will be generated when this flag is used. We don't recommend the use of this flag for builds that might be submitted to certification, but it can speed up local iteration times.
/validationcritical	Specifies that failures in Submission Validator are to be treated as critical failures for the MakePkg process.
/validationlanguage	Specifies an additional language for building the submission validator log file. This language should be specified in the BCP-47 format and a second log file will be produced in this target language if the string resources are available. The current supported language are Japanese (ja-JP), Korean (ko-KR), and Simplified Chinese (zh-CN).
/t	Used with the localize command. Optional directory for converting the Resources.pri contents to an XML format. Viewing the contents of Resources.pri in an xml format is convenient for ensuring the contents of Resources.pri are what you expect.
/resw	Used with the localize command. Optional directory path relative to the root directory, which contains RESW files if they aren't present in the immediate root directory.
/gc	Used with the localize command. Optional path to the MicrosoftGame.config file if it isn't located at the base of the content directory or has a name other than MicrosoftGame.config.
/v	Enables verbose output to the console.
/loggable	Suppresses output containing control characters which are not suitable for being written to a log file. For example, copy progress uses a rolling percentage in non-verbose mode which can bloat log files.
/?	Displays help.

Remarks

When makepkg pack is run, a binary package file is created, referred to as an Xbox Virtual Container (XVC). XVCs for console have the file name extension of .xvc and for PC have the file name extension of .msixvc. In addition to the extension difference, there is a suffix added to the package name to differentiate between Xbox One Family (_x) and Xbox Series X|S Family (_xs) packages.

When makepkg pack or makepkg validate is run, a set of validation tests is performed. The amount of time taken by these tests depends on the size of the title and the number of files.

The results of the validation test are logged to an XML file that's in the same output directory as the one used for the app package output. The log lists all the errors that must be corrected for the title to pass validation. The validation tests check for common errors that historically have led to titles being delayed or later rejected from the mastering and certification process.

makepkg sets the following exit codes:

Exit code	Description
0	Success
1	Bad environment: kernel driver isn't installed; not running in an elevated command prompt
2	Invalid command line
3	Failed to build the output

More extensive information is also logged to stderr.