Merging packages before imaging

  • Article

Before you create an image, we recommend that you first merge your packages by using the FeatureMerger.exe tool. This tool takes a feature manifest file as an input and merges your referenced packages into a small, well-defined set of packages that adhere to a predictable and consistent naming system.

This topic provides general guidance about the package merging process.

Important  

For retail images, you must generate merged packages that conform to the Windows Standard Package Configuration (WSPC). WSPC is a set of rules that define the package naming requirements for retail devices. For more info, see Windows Standard Packaging Configuration (WSPC) requirements for retail images.

Understanding the package merging process

To create merged packages, create a feature manifest file that lists the packages you want to merge and pass this feature manifest file to the FeatureMerger.exe tool. FeatureMerger.exe merges your packages based on the package groups under which the packages are listed in the feature manifest file and additional package metadata. Based on this information, one or more packages that represent the minimal set of packages based on the metadata are generated. The new merged packages are placed in the output directory specified when the tool was invoked. For instructions about using FeatureMerger.exe, see Merging packages using FeatureMerger.

The following table summarizes how packages are merged based on the feature manifest package group they are listed under.

Package group element in the feature manifest Merging behavior

BasePackages

All packages listed under the BasePackages element with the same partition, language, and resolution will be merged together into a package with the following naming convention:

<Owner>.Base.<FeatureManifestID>.<Partition>.spkg

SOCPackages

All packages listed under the SOCPackages element with the same SOC attribute value, partition, language, and resolution will be merged together into a package with the following naming convention.

<Owner>.SOC_<SOC name>.<FeatureManifestID>.<Partition>.spkg

OEMDevicePlatformPackages

DeviceSpecificPackages

All packages listed under the OEMDevicePlatformPackages and DeviceSpecificPackages elements with the same Device attribute value, partition, language, and resolution will be merged together into a package with the following naming convention.

<Owner>.DEVICE_<device name>.<FeatureManifestID>.<Partition>.spkg

Features

All packages listed under the Features element with the same FeatureID, partition, language, and resolution will be merged together into a package with the following naming convention.

<Owner>.OEM_<feature ID>.<FeatureManifestID>.<Partition>.spkg

ReleasePackages

All packages listed under the ReleasePackages element with the same ReleaseType attribute value, partition, language, and resolution will be merged together into a package with the following naming convention.

<Owner>.RELEASE_<TEST | PRODUCTION>.<FeatureManifestID>.<Partition>.spkg

SVPackages

All packages listed under the SVPackages element with the same SV attribute value, partition, language, and resolution will be merged together into a package with the following naming convention.

<Owner>.SV_<SV name>.<FeatureManifestID>.<Partition>.spkg

PrereleasePackages

All packages listed under the PrereleasePackages element with the same Type attribute value, partition, language, and resolution will be merged together into a package with the following naming convention.

<Owner>.PRERELEASE_<REPLACEMENT | PROTECTED>.<FeatureManifestID>.<Partition>.spkg

 

In the preceding table, the partition, language, and resolution metadata used for package merging are derived from the following attributes in the package project XML file used to generate each package:

  • Partition attribute of the Package element.

  • Language attribute of the Files element.

  • Resolution attribute of the Files element.

Note  

Language and resolution-specific merged packages (packages with the language or resolution suffix in the package file name) do not comply with WSPC. For retail images, these packages should be merged into a WSPC-compliant base package by referencing the packages under the BasePackages element in the feature manifest.

For more info about these attributes, see Primary elements and attributes of a package project file and Specifying files and registry entries in a package project file.

Naming convention for merged packages

The merged packages generated by FeatureMerger.exe have the following basic naming convention:

<Owner>.<MergedPackageType>.<FeatureManifestID>.<Partition>.spkg

The <MergedPackageType> substring is derived from the grouping element in the feature manifest, as described in the previous section. The following table describes where the other substrings are derived from.

Substring Origin of the substring

Owner

The Owner substring is derived from one of the following locations:

  • If you pass a single feature manifest XML file to FeatureMerger.exe, this is derived from the /OwnerName command line parameter.

  • If you pass an FMFileList XML file to FeatureMerger.exe, this is derived from the OwnerName attribute of the FM element in the FMFileList XML file.

FeatureManifestID

The FeatureManifestID substring is derived from one of the following locations:

  • If you pass a single feature manifest XML file to FeatureMerger.exe, this is derived from the /FMID command line parameter.

  • If you pass an FMFileList XML file to FeatureMerger.exe, this is derived from the ID attribute of the FM element in the FMFileList XML file.

Important  

When building merged packages for retail images, OEMs must specify either Phone or Variant for the FeatureManifestID substring. For more info, see Windows Standard Packaging Configuration (WSPC) requirements for retail images.

Partition

The Partition substring is derived from the Partition attribute of the Package element in the package project XML files that were used to build the packages that are being merged. For more information, see Primary elements and attributes of a package project file.

 

General guidelines for package merging

You should structure your feature manifest files to control how groups of packages are merged. The following list is a set of general guidelines for package merging:

  • Plan for how you want your packages to be merged. For example, you may only want certain sets of packages to be available on phones that are targeted for specific mobile operators or markets.

  • Either create new feature manifest files, or leverage existing feature manifest files, to control how packages are merged.

  • Use the SOCPackages, OEMDevicePlatformPackages and DeviceSpecificPackages elements to manage hardware-specific packages. For example, all packages associated with a specific SoC element in a feature manifest should have the same SOC attribute. FeatureMerger.exe uses each of these categories as a criteria for merging packages. The packages will be merged with the other packages when any combination of the elements matches. If some packages match on some of the attributes and not others, then only the packages that match on all elements will be contained in a merged package.

  • When generating merged packages for retail images, make sure you generate packages that conform to the WSPC. For more info, see Windows Standard Packaging Configuration (WSPC) requirements for retail images.

  • Use merged packages for all image generation by using the feature manifests that are generated by FeatureMerger.exe. For more info, see Merging packages using FeatureMerger.

  • Verify that all packages have the proper metadata to ensure that merging is performed as expected.

For more info about feature manifests, see Feature manifest file contents. For more info about the OEMInput file elements, see OEMInput file contents.

Merging packages using FeatureMerger

Windows Standard Packaging Configuration (WSPC) requirements for retail images