Rule Files

A rule file, or RULES file, is an XML file that has a .rules file extension. It allows you to define custom build rules and incorporate them into the build process of a Visual C++ project. Custom build rules are associated with one or more file extensions. A custom build rule enables you pass input files to a tool, which results in one or more output files, as part of the build process.

Use the Visual C++ Custom Build Rule Files Dialog Box to manage the rule files in your projects.

Note

Rule files follow the same property inheritance guidelines as property sheets (VSPROPS files). For more information, see Property Inheritance.

When you incorporate custom build rules into the build process, you can also specify the order in which those build rules are run. For more information, see Tool Build Order Dialog Box.

Example

The following example RULES file defines a custom build rule:

<?xml version="1.0" encoding="utf-8"?>
<VisualStudioToolFile
   Name="Microsoft Macro Assembler"
   >
   <Rules>
      <CustomBuildRule
         Name="MASM"
         DisplayName="Microsoft Macro Assembler"
         CommandLine="ml.exe /nologo /c [AllOptions] [AdditionalOptions] /Fo&quot;$(IntDir)\$(InputName).obj&quot; /Ta [inputs]"
         Outputs="$(IntDir)\$(InputName).obj"
         FileExtensions="*.asm"
         ExecutionDescription="Assembling..."
         ShowOnlyRuleProperties="true"
         >
         <Properties>
            <BooleanProperty
               Name="TinyMemoryModelSupport"
               DisplayName="Tiny Memory Model Support"
               PropertyPageName="Advanced"
               Description="Enables tiny-memory-model support. Note that this is not equivalent to the .MODEL TINY directive.     (/AT)"
               HelpURL="https://msdn.microsoft.com/library/default.asp?url=/library/en-us/vcmasm/html/vclrfml.asp"
               Switch="/AT"
            />
            <BooleanProperty
               Name="UseCommonObjectFileFormat"
               DisplayName="Use Common Object File Format (COFF)"
               PropertyPageName="Object File"
               Description="Generates a common object file format type of object module.     (/coff)"
               HelpURL="https://msdn.microsoft.com/library/default.asp?url=/library/en-us/vcmasm/html/vclrfml.asp"
               Switch="/coff"
            />
            <BooleanProperty
               Name="PreserveIdentifierCase"
               DisplayName="Preserve Identifier Case"
               PropertyPageName="Identifiers"
               Description="Preserves case of all user identifiers.     (/Cp)"
               HelpURL="https://msdn.microsoft.com/library/default.asp?url=/library/en-us/vcmasm/html/vclrfml.asp"
               Switch="/Cp"
            />
            <BooleanProperty
               Name="MapIdentifiersToUpperCase"
               DisplayName="Map Identifiers To Upper Case"
               PropertyPageName="Identifiers"
               Description="Maps all identifiers to upper case.     (/Cu)"
               HelpURL="https://msdn.microsoft.com/library/default.asp?url=/library/en-us/vcmasm/html/vclrfml.asp"
               Switch="/Cu"
               DefaultValue="true"
            />
            <BooleanProperty
               Name="PreservePublicAndExternSymbolCase"
               DisplayName="Preserve Public and Extern Symbol Case"
               PropertyPageName="Identifiers"
               Description="Preserves case in public and extern symbols.     (/Cx)"
               HelpURL="https://msdn.microsoft.com/library/default.asp?url=/library/en-us/vcmasm/html/vclrfml.asp"
               Switch="/Cx"
            />
            <StringProperty
               Name="PreprocessorDefinitions"
               DisplayName="Preprocessor Definitions"
               Description="Defines a text macro with the given name.     (/D[symbol])"
               HelpURL="https://msdn.microsoft.com/library/default.asp?url=/library/en-us/vcmasm/html/vclrfml.asp"
               Switch="/D&quot;[value]&quot;"
               Delimited="true"
               Inheritable="true"
            />
            <BooleanProperty
               Name="GeneratePreprocessedSourceListing"
               DisplayName="Generate Preprocessed Source Listing"
               PropertyPageName="Listing File"
               Description="Generates a preprocessed source listing to the Output Window.     (/EP)"
               HelpURL="https://msdn.microsoft.com/library/default.asp?url=/library/en-us/vcmasm/html/vclrfml.asp"
               Switch="/EP"
            />
            <StringProperty
               Name="AssembledCodeListingFile"
               DisplayName="Assembled Code Listing File"
               PropertyPageName="Listing File"
               Description="Generates an assembled code listing file.     (/Fl[file])"
               HelpURL="https://msdn.microsoft.com/library/default.asp?url=/library/en-us/vcmasm/html/vclrfml.asp"
               Switch="/Fl&quot;[value]&quot;"
               Delimited="true"
            />
            <BooleanProperty
               Name="GenerateEmulatorFixups"
               DisplayName="Generate Emulator Fixups"
               PropertyPageName="Advanced"
               Description="Generates emulator fix-ups for floating-point arithmetic (mixed language only).     (/FPi)"
               HelpURL="https://msdn.microsoft.com/library/default.asp?url=/library/en-us/vcmasm/html/vclrfml.asp"
               Switch="/FPi"
            />
            <StringProperty
               Name="SourceBrowserFile"
               DisplayName="Source Browser File"
               PropertyPageName="Source Browser File"
               Description="Generates a source browser .sbr file.     (/Fr[file])"
               HelpURL="https://msdn.microsoft.com/library/default.asp?url=/library/en-us/vcmasm/html/vclrfml.asp"
               Switch="/Fr&quot;[value]&quot;"
               Delimited="true"
            />
            <StringProperty
               Name="ExtendedSourceBrowserFile"
               DisplayName="Extended Source Browser File"
               PropertyPageName="Source Browser File"
               Description="Generates an extended form of a source browser .sbr file.     (/FR[file])"
               HelpURL="https://msdn.microsoft.com/library/default.asp?url=/library/en-us/vcmasm/html/vclrfml.asp"
               Switch="/FR&quot;[value]&quot;"
               Delimited="true"
            />
            <BooleanProperty
               Name="UsePascalCallingConvention"
               DisplayName="Use Pascal Calling Convention"
               PropertyPageName="Advanced"
               Description="Specifies use of FORTRAN- or Pascal-style function calling and naming conventions. Same as OPTION LANGUAGE:PASCAL.     (/Gc)"
               HelpURL="https://msdn.microsoft.com/library/default.asp?url=/library/en-us/vcmasm/html/vclrfml.asp"
               Switch="/Gc"
            />
            <BooleanProperty
               Name="UseCStyleCallingConvention"
               DisplayName="Use C-Style Calling Convention"
               PropertyPageName="Advanced"
               Description="Specifies use of C-style function calling and naming conventions. Same as OPTION LANGUAGE:C.     (/Gd)"
               HelpURL="https://msdn.microsoft.com/library/default.asp?url=/library/en-us/vcmasm/html/vclrfml.asp"
               Switch="/Gd"
            />
            <IntegerProperty
               Name="ExternalNameCharacterLimit"
               DisplayName="External Name Character Limit"
               PropertyPageName="Identifiers"
               Description="Restricts external names to number significant characters. The default is 31 characters.     (/H [number])"
               HelpURL="https://msdn.microsoft.com/library/default.asp?url=/library/en-us/vcmasm/html/vclrfml.asp"
               Switch="/H [value]"
               DefaultValue="31"
            />
            <StringProperty
               Name="IncludePaths"
               DisplayName="Include Paths"
               Description="Sets path for include file. A maximum of 10 /I options is allowed.     (/I [path])"
               HelpURL="https://msdn.microsoft.com/library/default.asp?url=/library/en-us/vcmasm/html/vclrfml.asp"
               Switch="/I &quot;[value]&quot;"
               Delimited="true"
               Inheritable="true"
            />
            <BooleanProperty
               Name="UseObjectModuleFileFormat"
               DisplayName="Use Object Module File Format"
               PropertyPageName="Object File"
               Description="Generates object module file format (OMF) type of object module.     (/omf)"
               HelpURL="https://msdn.microsoft.com/library/default.asp?url=/library/en-us/vcmasm/html/vclrfml.asp"
               Switch="/omf"
            />
            <BooleanProperty
               Name="ListAllAvailableInformation"
               DisplayName="List All Available Information"
               PropertyPageName="Listing File"
               Description="Turns on listing of all available information.     (/Sa)"
               HelpURL="https://msdn.microsoft.com/library/default.asp?url=/library/en-us/vcmasm/html/vclrfml.asp"
               Switch="/Sa"
            />
            <BooleanProperty
               Name="UseSafeExceptionHandlers"
               DisplayName="Use Safe Exception Handlers"
               PropertyPageName="Advanced"
               Description="Marks the object as either containing no exception handlers or containing exception handlers that are all declared with .SAFESEH.     (/safeseh)"
               HelpURL="https://msdn.microsoft.com/library/default.asp?url=/library/en-us/vcmasm/html/vclrfml.asp"
               Switch="/safeseh"
            />
            <BooleanProperty
               Name="AddInstructionTimings"
               DisplayName="Add Instruction Timings"
               PropertyPageName="Listing File"
               Description="Adds instruction timings to listing file.     (/Sc)"
               HelpURL="https://msdn.microsoft.com/library/default.asp?url=/library/en-us/vcmasm/html/vclrfml.asp"
               Switch="/Sc"
            />
            <BooleanProperty
               Name="AddFirstPassListing"
               DisplayName="Add First Pass Listing"
               PropertyPageName="Listing File"
               Description="Adds first-pass listing to listing file.     (/Sf)"
               HelpURL="https://msdn.microsoft.com/library/default.asp?url=/library/en-us/vcmasm/html/vclrfml.asp"
               Switch="/Sf"
            />
            <BooleanProperty
               Name="EnableAssemblyGeneratedCodeListing"
               DisplayName="Enable Assembly Generated Code Listing"
               PropertyPageName="Listing File"
               Description="Turns on listing of assembly-generated code.     (/Sg)"
               HelpURL="https://msdn.microsoft.com/library/default.asp?url=/library/en-us/vcmasm/html/vclrfml.asp"
               Switch="/Sg"
            />
            <IntegerProperty
               Name="SourceListingLineWidth"
               DisplayName="Source Listing Line Width"
               PropertyPageName="Listing File"
               Description="Sets the line width of source listing in characters per line. Range is 60 to 255 or 0. Default is 0. Same as PAGE width.     (/Sl [width])"
               HelpURL="https://msdn.microsoft.com/library/default.asp?url=/library/en-us/vcmasm/html/vclrfml.asp"
               Switch="/Sl [value]"
            />
            <BooleanProperty
               Name="DisableSymbolTable"
               DisplayName="Disable Symbol Table"
               PropertyPageName="Listing File"
               Description="Turns off symbol table when producing a listing.     (/Sn)"
               HelpURL="https://msdn.microsoft.com/library/default.asp?url=/library/en-us/vcmasm/html/vclrfml.asp"
               Switch="/Sn"
            />
            <IntegerProperty
               Name="SourceListingPageLength"
               DisplayName="Source Listing Page Length"
               PropertyPageName="Listing File"
               Description="Sets the page length of source listing in lines per page. Range is 10 to 255 or 0. Default is 0. Same as PAGE length.     (/Sp [length])"
               HelpURL="https://msdn.microsoft.com/library/default.asp?url=/library/en-us/vcmasm/html/vclrfml.asp"
               Switch="/Sp [value]"
            />
            <StringProperty
               Name="SourceListingSubTitle"
               DisplayName="Source Listing Subtitle"
               PropertyPageName="Listing File"
               Description="Specifies subtitle text for source listing. Same as SUBTITLE text.     (/Ss [subtitle])"
               HelpURL="https://msdn.microsoft.com/library/default.asp?url=/library/en-us/vcmasm/html/vclrfml.asp"
               Switch="/Ss [value]"
               Delimited="true"
            />
            <StringProperty
               Name="SourceListingTitle"
               DisplayName="Source Listing Title"
               PropertyPageName="Listing File"
               Description="Specifies title for source listing. Same as TITLE text.     (/St [title])"
               HelpURL="https://msdn.microsoft.com/library/default.asp?url=/library/en-us/vcmasm/html/vclrfml.asp"
               Switch="/St [value]"
               Delimited="true"
            />
            <BooleanProperty
               Name="EnableFalseConditionalsInListing"
               DisplayName="Enable False Conditionals In Listing"
               PropertyPageName="Listing File"
               Description="Turns on false conditionals in listing.     (/Sx)"
               HelpURL="https://msdn.microsoft.com/library/default.asp?url=/library/en-us/vcmasm/html/vclrfml.asp"
               Switch="/Sx"
            />
            <EnumProperty
               Name="WarningLevel"
               DisplayName="Warning Level"
               Description="Sets the warning level, where level = 0, 1, 2, or 3.    (/W0, /W1, /W2, /W3)"
               HelpURL="https://msdn.microsoft.com/library/default.asp?url=/library/en-us/vcmasm/html/vclrfml.asp"
               >
               <Values>
                  <EnumValue
                     Value="0"
                     Switch="/W0"
                     DisplayName="Warning Level 0 (/W0)"
                  />
                  <EnumValue
                     Value="1"
                     Switch="/W1"
                     DisplayName="Warning Level 1 (/W1)"
                  />
                  <EnumValue
                     Value="2"
                     Switch="/W2"
                     DisplayName="Warning Level 2 (/W2)"
                  />
                  <EnumValue
                     Value="3"
                     Switch="/W3"
                     DisplayName="Warning Level 3 (/W3)"
                  />
               </Values>
            </EnumProperty>
            <BooleanProperty
               Name="TreatWarningsAsErrors"
               DisplayName="Treat Warnings As Errors"
               Description="Returns an error code if warnings are generated.     (/WX)"
               HelpURL="https://msdn.microsoft.com/library/default.asp?url=/library/en-us/vcmasm/html/vclrfml.asp"
               Switch="/WX"
            />
            <BooleanProperty
               Name="GenerateLineInformation"
               DisplayName="Generate Line Information"
               PropertyPageName="Object File"
               Description="Generates line-number information in object file.     (/Zd)"
               HelpURL="https://msdn.microsoft.com/library/default.asp?url=/library/en-us/vcmasm/html/vclrfml.asp"
               Switch="/Zd"
            />
            <BooleanProperty
               Name="MakeAllSymbolsPublic"
               DisplayName="Make All Symbols Public"
               PropertyPageName="Object File"
               Description="Makes all symbols public.     (/Zf)"
               HelpURL="https://msdn.microsoft.com/library/default.asp?url=/library/en-us/vcmasm/html/vclrfml.asp"
               Switch="/Zf"
            />
            <BooleanProperty
               Name="GenerateCodeViewInformation"
               DisplayName="Generate CodeView Information"
               PropertyPageName="Object File"
               Description="Generates CodeView information in object file.     (/Zi)"
               HelpURL="https://msdn.microsoft.com/library/default.asp?url=/library/en-us/vcmasm/html/vclrfml.asp"
               Switch="/Zi"
            />
            <BooleanProperty
               Name="EnableMASM51Compatibility"
               DisplayName="Enable MASM 5.1 Compatibility"
               Description="Enables M510 option for maximum compatibility with MASM 5.1.     (/Zm)"
               HelpURL="https://msdn.microsoft.com/library/default.asp?url=/library/en-us/vcmasm/html/vclrfml.asp"
               Switch="/Zm"
            />
            <EnumProperty
               Name="PackAlignmentBoundary"
               DisplayName="Pack Alignment Boundary"
               PropertyPageName="Advanced"
               Description="Packs structures on the specified byte boundary. The alignment can be 1, 2, or 4.     (/Zp1, /Zp2, /Zp4)"
               HelpURL="https://msdn.microsoft.com/library/default.asp?url=/library/en-us/vcmasm/html/vclrfml.asp"
               >
               <Values>
                  <EnumValue
                     Value="0"
                     Switch="/Zp1"
                     DisplayName="One Byte Boundary (/Zp1)"
                  />
                  <EnumValue
                     Value="1"
                     Switch="/Zp2"
                     DisplayName="Two Byte Boundary (/Zp2)"
                  />
                  <EnumValue
                     Value="2"
                     Switch="/Zp4"
                     DisplayName="Four Byte Boundary (/Zp4)"
                  />
               </Values>
            </EnumProperty>
            <BooleanProperty
               Name="PerformSyntaxCheckOnly"
               DisplayName="Perform Syntax Check Only"
               Description="Performs a syntax check only.     (/Zs)"
               HelpURL="https://msdn.microsoft.com/library/default.asp?url=/library/en-us/vcmasm/html/vclrfml.asp"
               Switch="/Zs"
            />
         </Properties>
      </CustomBuildRule>
   </Rules>
</VisualStudioToolFile>

Use the XML Schema Definition for Rule Files to validate your own RULES files.

See Also

Reference

XML Schema Definition for Property Sheets

Project Files

Understanding Custom Build Steps and Build Events