Merging packages using FeatureMerger

  • 项目

The package feature merger tool (FeatureMerger.exe) combines packages into a small, well-defined set of merged packages that adhere to a predictable and consistent naming system. For retail images, OEMs must use FeatureMerger.exe to merge their packages into a specific set of packages that conform to the Windows Standard Package Configuration (WSPC).

For an overview of package merging, see Merging packages before imaging. For more information about the WSPC requirements for retail images, see Windows Standard Packaging Configuration (WSPC) requirements for retail images.

FeatureMerger.exe overview

FeatureMerger.exe can be used in two ways: by passing a single feature manifest XML file, or by passing an FMFileList XML file that describes multiple feature manifests. The tool generates a set of merged packages and a new feature manifest file that references the merged packages. The new feature manifest file can be referenced in an OEMInput file that is passed to ImgGen.cmd to build an image from the new merged packages.

To generate merged packages that comply with the (WSPC) for retail images, you must organize all your packages into a single feature manifest as described in Windows Standard Packaging Configuration (WSPC) requirements for retail images and pass this feature manifest to FeatureMerger.exe. If you are starting with packages that are described in multiple feature manifest files, you can generate merged packages that comply with WSPC in a multi-step process:

  1. Generate an initial set of merged packages and feature manifests by running FeatureMerger.exe with an FMFileList XML file that references the feature manifest files.

  2. Manually create a new feature manifest file that references all of the merged packages generated in the first step. Make sure that the merged packages are referenced in the WSPC-compliant sections of the feature manifest file, as described in Windows Standard Packaging Configuration (WSPC) requirements for retail images.

  3. Generate merged packages by running FeatureMerger.exe with the consolidated feature manifest file.

Using FeatureMerger.exe with a single feature manifest XML file

FeatureMerger.exe has the following syntax when used with a single feature manifest XML file.

FeatureMerger InputFile OutputPackageDir OutputPackageVersion OutputFMDir /FMID:<feature manifest id> /Languages:<language identifier list>
/Resolutions:<resolution identifier list> /OwnerName:<owner name> /Variables:<variables> [/OwnerType:<owner type>] [/MergePackageRootReplacement:<replacement directory> 
[{+|-}Incremental] [{+|-}Compress]

Required arguments and switches

The following table lists the required arguments and switches when using FeatureMerger.exe with a single feature manifest XML file.

Argument/switch Description Value

InputFile

The path to the feature manifest XML file.

Text string

OutputPackageDir

The path to the directory where the merged packages will be placed.

Text string

OutputPackageVersion

The version of the merged package that is created using the format "<major>.<minor>.<hotfix>.<build>".

Note  

The package version must be incremented whenever a package is changed. For more info about package versioning and updates, see Update requirements.

Text string

OutputFMDir

The path to the directory where the generated feature manifests will be placed. Feature manifests are generated with the same file name as the original feature manifest file name. The updated version of the feature manifest file contains the names of the merged packages and the provided version number.

Text string

/FMID:Feature manifest ID

A required short FM ID that describes the feature manifest file that is used in the merged package name to ensure that features from different FM files don't collide. The ID should be eight characters or less and be different from all other FM IDs. When generating merged packages for retail images, this ID must have the value of either Phone or Variant. For more info, see Windows Standard Packaging Configuration (WSPC) requirements for retail images.

Text string

/Languages:Language identifier list

A semicolon “;” separated list of supported UI language identifiers. The following is an example of a language identifier list.

en-us;de-de

Text string

/Resolutions:Resolution identifier list

A semicolon “;” separated list of supported resolution identifiers. The following is an example of a resolutions identifier list.

480x800;720x1280;768x1280;1080x1920

Text string

/OwnerName:Owner name

The name of the package owner, for example “Contoso”.

Text string

/Variables:variables

Additional variables that are used in the project file using the following syntax:<name>=<value>;<name>=<value>;

The following variables are pre-defined:

  • _cputype: Required. Specifies the CPU architecture. For Windows 10 Mobile, this variable must be set to "arm".

  • buildtype: Required. Specifies the build type. This variable must be set to either "fre" or "chk".

  • releasetype: Optional. Specifies the image release type. This variable can be set to either "test" or "production". If this variable is not specified, the default value is "test".

For example, to set the CPU, build type, and release type, specify the variables like this:

/Variables:_cputype=arm;buildtype=fre;releasetype:production

Text string

 

Optional and reserved switches

The following table lists the optional switches when using FeatureMerger.exe with a single feature manifest XML file.

Switch Description Value

/OwnerType:Owner type

Specifies the resulting package owner type.

Text string – For OEM packages, this value must be set to "OEM".

/MergePackageRootReplacement:Replacement directory

Specifies a string to be used in the generated FM file for packages. Replaces the OutputPackageDir in the package paths.

Text string

{+|-}Incremental

Specifies to only re-merge existing merged packages when one of the sources packages has changed. If this value is not set, the default is False. This means that all packages will be rebuilt each time FeatureMerger is called.

Boolean value: Precede this switch with either [+] to set to true or [-] to set to false

{+|-}Compress

This value allows for the compression of merged packages. When compress is true, the merge tool run time increases, but the package is optimized for storage size. This setting has no impact on imaging.

Boolean value: Precede this switch with either [+] to set to true or [-] to set to false

 

The following table lists the switches that are reserved for use by Microsoft when using FeatureMerger.exe with a single feature manifest XML file.

Switch Description Value

/Critical

Reserved for use by Microsoft.

Text string

 

Examples

The following examples demonstrate FeatureMerger.exe syntax when specifying a feature manifest file.

FeatureMerger C:\FM\OEMSampleFM.xml D:\FM\MergedPackages 8.0.0.1 D:\FM\MergedFMs /FMID:Phone /Languages:en-us 
/Resolutions:480x800;720x1280;768x1280;1080x1920 /OwnerName:Contoso /variables:_cputype=arm;buildtype=fre

Using FeatureMerger.exe with an FMFileList XML file

FeatureMerger.exe has the following syntax when used with a single feature manifest XML file.

FeatureMerger InputFile OutputPackageDir OutputPackageVersion OutputFMDir /InputFMDirPath:<path> /Variables:<variables> [/MergePackageRootReplacement:<replacement directory> 
[{+|-}Incremental] [{+|-}Compress]

Required arguments and switches

The following table lists the required arguments and switches when using FeatureMerger.exe with an FMFileList XML file.

Argument/switch Description Value

InputFile

The path to the FMFileList XML file. For more info about the contents of the FMFileList XML file, see Contents of the FMFileList XML file in this topic.

Text string

OutputPackageDir

The path to the directory where the merged packages will be placed.

Text string

OutputPackageVersion

The version of the merged package that is created using the format "<major>.<minor>.<hotfix>.<build>".

Note  

The package version must be incremented whenever a package is changed. For more info about package versioning and updates, see Update requirements.

Text string

OutputFMDir

The path to the directory where the generated feature manifests will be placed. Feature manifests are generated with the same file name as the original feature manifest file name. The updated version of the feature manifest file contains the names of the merged packages and the provided version number.

Text string

/InputFMDirpath:path

The directory where the source feature manifest files are located.

Text string

/Variables:variables

Additional variables used in the project file using the following syntax:<name>=<value>;<name>=<value>;

The following variables are pre-defined:

  • _cputype: Required. Specifies the CPU architecture. For Windows 10 Mobile, this variable must be set to "arm".

  • buildtype: Required. Specifies the build type. This variable must be set to either "fre" or "chk".

  • releasetype: Optional. Specifies the image release type. This variable can be set to either "test" or "production". If this variable is not specified, the default value is "test".

For example, to set the CPU, build type, and release type, specify the variables like this:

/Variables:_cputype=arm;buildtype=fre;releasetype:production

Text string

 

Optional and reserved switches

The following table lists the optional switches when using FeatureMerger.exe with FMFileList XML file.

Switch Description Value

/MergePackageRootReplacement:Replacement directory

Specifies a string to be used in the generated feature manifest for packages. Replaces the OutputPackageDir in the package paths.

Text string

{+|-}Incremental

Specifies to only remerge existing merged packages when one of the sources packages has changed. If this value is not set, the default is False. This means that all packages will be rebuilt each time FeatureMerger.exe is called.

Boolean value: Precede this switch with either [+] to set to true or [-] to set to false

{+|-}Compress

This value allows for the compression of merged packages. When compress is true, the merge tool run time increases, but the package is optimized for storage size. This setting has no impact on imaging.

Boolean value: Precede this switch with either [+] to set to true or [-] to set to false

 

The following table lists the switches that are reserved for use by Microsoft when using FeatureMerger.exe with an FMFileList XML file.

Switch Description Value

/Critical

Reserved for use by Microsoft.

Text string

 

Examples

The following example demonstrates FeatureMerger.exe syntax when specifying an FMFileList XML file.

FeatureMerger.exe C:\FM\OEMSampleFMFileList.xml C:\FM\MergedPackages 8.0.0.1 C:\FM\MergedFMs  
/variables:_cputype=arm;buildtype=fre

Contents of the FMFileList XML file

An FMFileList XML file contains the following elements.

Element Description

FMs

The FMs element contains one or more FM elements.

FM

The FM element is used to point to feature manifest files.

<FM Path="C:\MyDir\OEMSampleFM.xml" ReleaseType="Test" OwnerType="OEM" ID="Phone" OwnerName="Contoso" />

The FM element has the following attributes.

  • Path: The path to the feature manifest files. The variable $(FMDirectory) can be used to specify the InputFMDir parameter in the path.

  • ReleaseType: The release type must be set to either "Test" or "Production". For FMs used in final retail images, this should be set to "Production". In addition, all packages defined in a Production FM must have the ReleaseType set to "Production". For more info about working with packages, see Primary elements and attributes of a package project file.

  • OwnerType: This value should be set to "OEM".

  • ID: A required short FM ID that describes the feature manifest file that is used in the merged package name to ensure that features from different FM files don't collide. The ID should be eight characters or less and be different from all other FM IDs. When generating merged packages for retail images, this ID must have the value of either Phone or Variant. For more info, see Windows Standard Packaging Configuration (WSPC) requirements for retail images.

  • OwnerName: The owner name should be set to the OEM name, for example "Contoso".

SupportedResolutions

The SupportedResolutions element is used to list the resolutions supported in the packages that will be merged.

<Resolution>480x800</Resolution>

SupportedLanguages

The SupportedLanguages element is used to list the languages supported in the packages that will be merged.

<Language>en-US</Language>

SupportedLocales

The SupportedLocales element is used to list the locales supported in the packages that will be merged.

<Locale>en-US</Locale>

 

For example, the following sample file specifies two feature manifest files, a list of supported resolutions, a supported language, and a supported locale.

<?xml version="1.0" encoding="utf-8"?>
<FMCollectionManifest xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
   xmlns:xsd="https://www.w3.org/2001/XMLSchema"
   xmlns="https://schemas.microsoft.com/embedded/2004/10/ImageUpdate">

  <FMs>
    <FM Path="D:\FeatureMergeTest\OEMSampleFM1.xml" ReleaseType="Test" OwnerType="OEM" ID="FM1" OwnerName="Contoso"/>
    <FM Path="D:\FeatureMergeTest\OEMSampleFM2.xml" ReleaseType="Test" OwnerType="OEM" ID="FM2" OwnerName="Contoso"/>
  </FMs>
  <SupportedResolutions>
    <Resolution>480x800</Resolution>
    <Resolution>720x1280</Resolution>
    <Resolution>768x1280</Resolution>
  </SupportedResolutions>
  <SupportedLanguages>
    <Language>en-US</Language>
  </SupportedLanguages>
  <SupportedLocales>
    <Locale>en-US</Locale>
  </SupportedLocales>
</FMCollectionManifest>

Paths that contain spaces

When you are using FeatureMerger.exe, be sure to use quotation marks around paths that contain spaces. For example, if you define a %WPDKCONTENTROOT% environment variable that is set to C:\Program Files (x86)\Windows Kits\10, the invocation of a package merger should be enclosed in quotation marks:

"%WPDKCONTENTROOT%\tools\bin\i386\FeatureMerger.exe"

This guidance also applies to the parameters that take paths, such as /InputFMDirpath.

Package code signing

Like all package generation, merged package generation uses catalog signing. For catalog signing to work, a certificate must be specified. To specify a signing certificate for package generation, follow the steps in Set up the signing environment and Sign binaries and packages.

Merging packages before imaging

Windows Standard Packaging Configuration (WSPC) requirements for retail images