Custom Rules

Xmake not only natively supports multi-language file building, but also allows users to implement complex unknown file building through custom build rules. Custom rules let you define specialized build logic for specific file types.

Basic Concepts

Custom build rules are defined using the rule() function and associate a set of file extensions to rules through set_extensions(). Once these extensions are associated with rules, calls to add_files() will automatically use this custom rule.

Creating Simple Rules

Basic Syntax

rule("rulename")
    set_extensions(".ext1", ".ext2")
    on_build_file(function (target, sourcefile, opt)
        -- build logic
    end)

Example: Markdown to HTML

-- Define a build rule for markdown files
rule("markdown")
    set_extensions(".md", ".markdown")
    on_build_file(function (target, sourcefile, opt)
        import("core.project.depend")
        
        -- make sure build directory exists
        os.mkdir(target:targetdir())
        
        -- replace .md with .html
        local targetfile = path.join(target:targetdir(), path.basename(sourcefile) .. ".html")
        
        -- only rebuild if file has changed
        depend.on_changed(function ()
            -- call pandoc to convert markdown to html
            os.vrunv('pandoc', {"-s", "-f", "markdown", "-t", "html", "-o", targetfile, sourcefile})
        end, {files = sourcefile})
    end)

target("test")
    set_kind("object")
    add_rules("markdown")
    add_files("src/*.md")

Applying Rules to Targets

Method 1: Using add_rules()

target("test")
    set_kind("binary")
    add_rules("markdown")  -- apply markdown rule
    add_files("src/*.md")  -- automatically use markdown rule

Method 2: Specifying in add_files

target("test")
    set_kind("binary")
    add_files("src/*.md", {rules = "markdown"})  -- specify rule for specific files

Note

Rules specified via add_files("*.md", {rules = "markdown"}) have higher priority than rules set via add_rules("markdown").

Rule Lifecycle

Custom rules support the complete build lifecycle and can execute custom logic at different stages:

Main Stages

• on_load: Executed when rule is loaded
• on_config: Executed after configuration is complete
• before_build: Executed before building
• on_build: Executed during building (overrides default build behavior)
• after_build: Executed after building
• on_clean: Executed during cleaning
• on_package: Executed during packaging
• on_install: Executed during installation

Example: Complete Lifecycle

rule("custom")
    set_extensions(".custom")
    
    on_load(function (target)
        -- configuration when rule is loaded
        target:add("defines", "CUSTOM_RULE")
    end)
    
    before_build(function (target)
        -- preparation work before building
        print("Preparing to build custom files...")
    end)
    
    on_build_file(function (target, sourcefile, opt)
        -- process individual source files
        print("Building file:", sourcefile)
    end)
    
    after_build(function (target)
        -- cleanup work after building
        print("Custom build completed")
    end)

File Processing Methods

Single File Processing (on_build_file)

rule("single")
    set_extensions(".single")
    on_build_file(function (target, sourcefile, opt)
        -- process single file
        local targetfile = path.join(target:targetdir(), path.basename(sourcefile) .. ".out")
        os.cp(sourcefile, targetfile)
    end)

Batch File Processing (on_build_files)

rule("batch")
    set_extensions(".batch")
    on_build_files(function (target, sourcebatch, opt)
        -- batch process multiple files
        for _, sourcefile in ipairs(sourcebatch.sourcefiles) do
            print("Processing file:", sourcefile)
        end
    end)

Batch Command Mode

Using on_buildcmd_file and on_buildcmd_files can generate batch commands instead of directly executing builds:

rule("markdown")
    set_extensions(".md", ".markdown")
    on_buildcmd_file(function (target, batchcmds, sourcefile, opt)
        -- ensure build directory exists
        batchcmds:mkdir(target:targetdir())
        
        -- generate target file path
        local targetfile = path.join(target:targetdir(), path.basename(sourcefile) .. ".html")
        
        -- add pandoc command
        batchcmds:vrunv('pandoc', {"-s", "-f", "markdown", "-t", "html", "-o", targetfile, sourcefile})
        
        -- add dependency files
        batchcmds:add_depfiles(sourcefile)
    end)

Rule Dependencies

Adding Rule Dependencies

rule("foo")
    add_deps("bar")  -- foo depends on bar rule

rule("bar")
    set_extensions(".bar")
    on_build_file(function (target, sourcefile, opt)
        -- bar rule build logic
    end)

Controlling Execution Order

rule("foo")
    add_deps("bar", {order = true})  -- ensure bar executes before foo
    on_build_file(function (target, sourcefile, opt)
        -- foo rule build logic
    end)

Common Interfaces

Setting File Extensions

rule("myrule")
    set_extensions(".ext1", ".ext2", ".ext3")

Adding Import Modules

rule("myrule")
    add_imports("core.project.depend", "utils.progress")
    on_build_file(function (target, sourcefile, opt)
        -- can directly use depend and progress modules
    end)

Getting Build Information

rule("myrule")
    on_build_file(function (target, sourcefile, opt)
        print("Target name:", target:name())
        print("Source file:", sourcefile)
        print("Build progress:", opt.progress)
        print("Target directory:", target:targetdir())
    end)

Practical Examples

Example 1: Resource File Processing

rule("resource")
    set_extensions(".rc", ".res")
    on_build_file(function (target, sourcefile, opt)
        import("core.project.depend")
        
        local targetfile = target:objectfile(sourcefile)
        depend.on_changed(function ()
            os.vrunv("windres", {sourcefile, "-o", targetfile})
        end, {files = sourcefile})
    end)

Example 2: Protocol Buffer Compilation

rule("protobuf")
    set_extensions(".proto")
    on_build_file(function (target, sourcefile, opt)
        import("core.project.depend")
        
        local targetfile = path.join(target:autogendir(), path.basename(sourcefile) .. ".pb.cc")
        depend.on_changed(function ()
            os.vrunv("protoc", {"--cpp_out=" .. target:autogendir(), sourcefile})
        end, {files = sourcefile})
        
        -- add generated file to target
        target:add("files", targetfile)
    end)

Best Practices

1. Use Dependency Checking: Avoid unnecessary rebuilds through depend.on_changed()
2. Error Handling: Add appropriate error handling logic in rules
3. Progress Display: Use opt.progress to display build progress
4. Modularization: Break complex rules into multiple simple rules
5. Documentation: Add clear comments and documentation for custom rules

More Information

• Complete API documentation: Custom Rule API
• Built-in rules reference: Built-in Rules
• Rule examples: Rule Examples