Using MUIRCT to Build Resources

  • Article

MUIRCT (Muirct.exe) is a command-line utility for splitting a standard Win32 portable executable file into a language-neutral (LN) file and a .mui file containing language-specific Win32 resources. Each of the resulting files contains resource configuration data that associates the files. MUIRCT is included in the Microsoft Windows SDK for Windows Vista.

Note: Starting with Windows Vista, the Win32 resource loader is updated to load resources from .mui files as well as from LN files.

Windows Vista supports two ways to build an LN file-.mui file pair: one method, described here, is to use MUIRCT; the other method uses the RC Compiler.

About MUIRCT

MUIRCT can take direction from command-line switches and/or from the resource configuration file, specified using the -q switch. If a resource configuration file is specified, it takes precedence over the -i switch.

By convention, the checksum used in an LN file and all of its associated .mui files normally comes from the English (United States) .mui file.

Syntax
muirct [-h|-?] [ -c checksum_file [-b langid] ] [-i resource_types]
     [-g langid] [-q rc_config_file] [-v level] [-x langid]
     [-z | -e output_file] [-d] [-f] source_filename [language_neutral_filename] 
     [mui_filename]
Switches and Arguments

  • -h|-?
    Shows help screen.

  • -c
    Calculates the resource checksum based on the content of checksum_file, a Win32 binary file containing localizable resources. MUIRCT inserts calculated checksum data into the LN file and .mui file. If the checksum file contains resources for more than one language, you must also use the -b switch, referring to a language having resources that are in the checksum file. If the -b switch is not used in this case, MUIRCT fails.

    The -q switch takes precedence over the -c switch. If you use the -q switch and the supplied resource configuration file contains a checksum value, MUIRCT uses the checksum value in the resource configuration file and ignores the -c switch.

    If you use both -c and –q switches and the supplied resource configuration file does not contain a checksum, MUIRCT calculates a checksum based on the language of the resources in the supplied checksum file. In this case, the checksum file must contain only resources in a single language, unless the -b switch is also used. Otherwise, the utility fails.

    If you do not use the -c switch, MUIRCT calculates a checksum based on the language of the resources in the source file.

  • -b
    Uses the specified language identifier for checksum calculation if the checksum file is a binary file containing resources in multiple languages. You can only use this switch in conjunction with the -c switch.

    If you do not specify the -b switch and the checksum input file contains resources in multiple languages, MUIRCT fails. The utility also fails if it cannot find the language specified by the -b switch in the checksum input file.

  • -i
    Puts the specified resource types in the .mui file. You can specify multiple resource types after this switch. If you do not use this switch, MUIRCT splits all resource types and places them in the .mui file.

    You must use standard resource type identifiers or names with this switch. MUIRCT always includes resource types 1 and 12 together, even if you only specify one of them with this switch. Types 3 and 14 are also always included together.

    MUIRCT performs strict resource type checks when this switch is used. In other words, if the source file does not contain type 2, but you specify type 2 when using this switch, the utility fails.

  • -g
    Uses the specified language as the ultimate fallback language to include in the resource configuration data of the LN file.

  • -q
    Uses a resource configuration file in XML format that specifies the resource types to extract to the .mui file and place in the LN file. For more information, see Preparing a Resource Configuration File. If you specify the -q switch and the -i switch in the same command line entry, MUIRCT ignores the -i switch.

    If you use the resource configuration file with this switch, MUIRCT can split the resource based on the individual items as well as types.

    Example:

    • 



muirct -x 0x409 -q myprog.rcconfig myprog.dll



    

  • -v
    
Uses the specified verbose level for logging. Specify 1 to print all basic error messages and operation results. Specify 2 to print everything specified for verbose level 1 and also print resource information (type, name, language identifier) that is included in the .mui file and LN file. The default is -v 1.
    

    • 

  • -x
    
Marks all added resource types with the specified language identifier in the resource section of the .mui file. The operation can use either decimal or hexadecimal format.
    

    Examples, both for English (United States):
    

    • 



muirct -x 0x409
muirct -x 1033



    

  • -z
    
Calculates and inserts resource checksum data in the specified output file. MUIRCT bases checksum calculation on the input provided with the -c switch, and the optional -b switch. If you specify an output file for the -z switch that does not exist, MUIRCT exits with a failure.
    

    Example: Calculates the checksum based on localizable resources in Notepad.exe and inserts the checksum into the output file Notepad2.exe.
    

    • 



muirct -c notepad.exe -q myprog.rcconfig -z notepad2.exe



    

  • -e
    
Extracts the checksum from the input file provided with the -c switch and places this value in the specified output file. When this switch is specified, MUIRCT ignores all switches other than the -c switch. The input file must be an LN file or .mui file that contains an RC Config data section with a checksum value. The output file must also be an existing LN file or .mui file. MUIRCT fails if the input file does not contain a checksum value or if the output file does not exist or is not an LN file or .mui file.
    

    Example: Extracts the checksum value in Notepad.exe and inserts it in the output file Notepad2.exe.
    

    muirct -c notepad.exe -e notepad2.exe.mui
    

    • 

  • -d
    
Locates and displays embedded resource configuration data in the source file. When you specify this switch, MUIRCT ignores all other command-line options.
    

    • 

  • -f
    
Creates an .mui file with the version resource being the only localizable resource. By default, MUIRCT does not create this type of file if the only localizable resource is the version resource.
    

    • 

  • source_filename
    
Name of the localized binary source file; wildcards cannot be used. This file can only contain resources in one language. If there are resources in multiple languages in the file, MUIRCT fails, unless the -b switch is used. If the file contains resources with language identifiers having value 0 only, MUIRCT does not split the file because a language identifier of 0 indicates a neutral language.
    

    For the -d switch, source_filename is either an LN file or an .mui file for which MUIRCT is to display resource configuration data.
    

    • 

  • language_neutral_filename
    
Optional. Name of LN file. If you do not specify the name of this file, MUIRCT appends a second extension ".ln" to the source file name to use as the language-neutral file name. Typically you should remove the ".ln" extension before deploying the file.
    

    • 

  • mui_filename
    
Optional. Name of .mui file. If you do not specify the name of the .mui file, MUIRCT appends a second extension ".mui" to the source file name to use as the .mui file name.
    

    • 



Language Output


MUIRCT chooses the "UltimateFallbackLanguage" attribute value to insert in the LN file resource configuration data based on the following order, from highest priority to lowest:


    

  1. "UltimateFallbackLanguage" attribute in the source resource configuration file, if one is passed in as input.
    2. 

  2. –t switch
    3. 

  3. -x switch
    4. 

  4. English (United States)
    5. 



MUIRCT picks the "language" attribute value to insert in the .mui file resource configuration data based on the following order:


    

  1. "language" attribute in the source resource configuration file if one is passed in as input
    2. 

  2. -x switch (force language)
    3. 

  3. English (United States)
    4. 



How Does MUIRCT Use a Resource Configuration File?


You can specify resource configuration data when using MUIRCT. Whether or not you explicitly supply a resource configuration file, every .mui file has resource configuration data, as does any LN file with an associated .mui file. For example:


    

  • If you use the -i switch to specify that a particular resource type is localizable and that type of resource exists in your input source file, the resulting LN and .mui files have resource configuration data.
    • 

  • If you use the -q switch to specify a resource configuration file, but there are no localizable resources in your input source file, no .mui file is generated and the resulting LN file does not contain resource configuration data.
    • 



Note: Currently the behavior of MUIRCT is inconsistent when the neutralResources element of the resource configuration file contains no resourceType elements and the localizedResources element contains strings and menus, for example. In such a case, MUIRCT splits the resources as follows:


    

  • All resources in the original binary (including strings and menus), plus the MUI resources, are placed in the LN file.
    • 

  • Strings, menus, and MUI resources are placed in the appropriate .mui file.
    • 



The LN file should not contain strings or menus. You should remove them manually.


How Does MUIRCT Handle Checksums?


The checksum, used primarily by the resource loader, is a unique identifier to validate the association of each .mui file with the corresponding LN file. The computer normally calculates the checksum over the language-specific resources in a file unless you specify it through a resource configuration file. As long as the checksum is the same for the LN file and for the LN file and its associated .mui files, the resource loader can successfully load resources from .mui files.


MUIRCT supports several methods for placing appropriate checksums in the resource configuration data:


    

  • Build a portable executable for each language, containing both code and resources. After this, use MUIRCT to split each of these files into an LN file and an .mui file. You can do this in any of the following ways:
    

    • 

  • Build a portable executable file containing both code and resources for a single language. After this, use MUIRCT to split the resources between the LN file and the .mui file. Finally, use a binary localization tool to modify the resulting .mui file for each language.
    

    • 

  • 

      

    1. Use the -q switch to specify a checksum value in the resource configuration file. MUIRCT places this value in all the LN files and .mui files produced. You need to adopt a strategy for choosing this value, as described later in this topic.
      2. 

    2. Use the -c switch (and, optionally, the -b switch) to choose a single language having resources from which MUIRCT extracts the checksum.
      3. 

    3. Use the -z switch to choose a single language having resources from which MUIRCT always extracts the checksum. Apply this checksum after the files have been built using other methods.
      4. 

    

    • 

  • Build a portable executable file containing both code and resources for a single language. After this, use MUIRCT to split the resources between the LN file and the .mui file. Finally, use a binary localization tool to modify the resulting .mui file for each language.
    

    • 



Using the first method, MUIRCT runs multiple times in the course of building a multilingual application, one time to generate an .mui file for each language. For both methods listed above, MUIRCT produces LN files that should be identical, but .mui files that are all different, each containing resources for a single language. The utility associates the .mui files with the LN file by using identical checksums in the resource configuration data.


How Does MUIRCT Determine Whether to Create an .mui File?


Normally, MUIRCT creates an .mui file. However, it does not create an .mui file if any of the following conditions exist:


    

  • No localizable resources are in the original binary file.
    • 

  • The only resource language found in the original binary file is the neutral language.
    • 

  • The original binary file has resources for more than one language, not counting the neutral language. If the binary file contains resources for two languages, and one of them is the neutral language, the utility considers the file to be monolingual and creates an .mui file if there are localizable resources.
    • 



Standard Resource Types


The following are the standard resource types and their numeric identifiers:


    

  • CURSOR(1)
    • 

  • BITMAP(2)
    • 

  • ICON(3)
    • 

  • MENU(4)
    • 

  • DIALOG(5)
    • 

  • STRING(6)
    • 

  • FONTDIR(7)
    • 

  • FONT(8)
    • 

  • ACCELERATORS(9)
    • 

  • RCDATA(10)
    • 

  • MESSAGETABLE(11)
    • 

  • GROUP_CURSOR(12)
    • 

  • GROUP_ICON(14)
    • 

  • VERSION(16)
    • 

  • HTML(23)
    • 



Examples for Using MUIRCT


Examples of Standard Usage


muirct -q mui.MMF -f bar.exe barnew.exe barnew.exe.mui

muirct –d myprog.exe.mui



Example of LN File Output Using -d Switch


Here is an example of the resource configuration data output from an LN file, Shell32.dll, using the -d switch with MUIRCT:


Signature          -    fecdfecd
Length             -    148
RC Config Version  -    10000
FileType           -    11
SystemAttributes   -    100
UltimateFallback location    -  external
Service Checksum   -    14f44a8d86bef14af26d9a885964c935
Checksum           -    f5b3b7ab330439d6fcc07582c3afb613
MainNameTypes      -    AVI FTR ORDERSTREAM TYPELIB UIFILE XML MUI
MainIDTypes        -    1 2 3 12 14 16 24
MuiNameTypes       -    MUI
MuiIDTypes         -    2 3 4 5 6 9 14 16
UltimateFallbackLanguage   -   en-US



Example of .mui File Output Using -d Switch


Here is an example of the resource configuration data output from an .mui file, Shell32.dll.mui, using the -d switch for MUIRCT:


Signature          -    fecdfecd
Length             -     c8
RC Config Version  -    10000
FileType           -    12
SystemAttributes   -    100
Service Checksum   -    14f44a8d86bef14af26d9a885964c935
Checksum           -    f5b3b7ab330439d6fcc07582c3afb613
MainNameTypes      -    MUI
MainIDTypes        -    2 3 4 5 6 9 14 16
Language           -    en-US



Using MUIRCT to Supply a Checksum


The most common convention for checksum handling is to base the checksum on the English (United States) (en-US) resources. You are free to adopt a different convention, as long as the convention is consistent for each individual LN file. For example, it is perfectly acceptable for a software development enterprise to base its checksums in the software it builds on French (France) resources instead of English (United States) resources, as long as all of the applications have French (France) resources on which to base the checksums. It is also acceptable to use the resource configuration file to assign an arbitrary hexadecimal value of up to 16 hexadecimal digits as a checksum. This last strategy precludes the effective use of the -z, -c, and -b switches of MUIRCT. It requires adoption of a method using either GuidGen or some other tool to generate checksum values. This strategy also requires you to set up a policy for determining when to modify the value when adding new localizable resources.


To apply the English (United States) checksum to all files, you can use any of the methods described in the section "How Does MUIRCT Handle Checksums?" above. For example, you can generate the LN file and .mui file for en-US, then use the MUIRCT -d switch to obtain the resulting checksum. You can copy this checksum into your resource configuration file and use the -q switch with MUIRCT to apply the checksum to all other files.



Handling Win32 MUI Resources