Home · Overviews · Reference · Classes

Rule Javascript Class Reference

• Running a rule
• Modifiers
• Properties
• name: string
• help: string
• inputFiles: list<string>
• outputFiles: list<string>
• prerequisiteActions: list<string>
• commands: list<string>
• tests: list<string>
• other: list<string>
• serial: boolean
• category: list<string>
• set: object

Running a rule

Each rule that is examined, ultimately ends up in one of three states: Succeeded, Failed, or NothingToDo.

Rules are examined in three stages: Priming, Testing and Executing. During priming, the following steps occur:

1. The prerequisite actions are expanded.
   • If a prerequisite is marked as evaluatable it is evaluated and the result is recursively expanded.
   • If a prerequisite is marked as a function it is invoked and the result is recursively expanded.

   If evaluating or invoking fails, the rule fails immediately. If an expanded prerequisite that is not marked as optional cannot be found, the rule fails immediately.

2. The input files are expanded.
   • If an input file is marked as evaluatable it is evaluatated and the result is recursively expanded.
   • If an input file is marked as a function it is invoked and the result is recursively expanded.

   If evaluating or invoking fails, the rule fails immediately.

3. For each input file, its freshen rule is added to the list of prerequisites.

   A freshen rule is one that has the input file as one of its output files. If a freshen rule is found, it is added as a prerequisite of the current rule. If a freshen rule cannot be found and the input file does not already exist, the rule fails immediately. If a freshen rule cannot be found and the input file already exists, the rule processing continues.

Following priming, further processing of the rule is queued until all of the prerequisite rules have completed. Once this has occured, the rule enters the testing stage. The testing stage determines whether this rule has to execute its commands.

1. If any non-optional prerequisite rules have failed, this rule fails immediately.
2. If any test functions exist, they are evaluated.
   • If any test function returns true, the rule will execute its commands.
   • If all test functions return false, the rule will not execute its commands.

   If they exist, test functions always override the rest of the test stage steps.

3. If there are no output files, the rule will execute its commands.
4. If any input file is newer than any output file, the rule will execute its commands.
5. If any output file does not exist, the rule will execute its commands.
6. Otherwise, the rule will not execute its commands.

Once testing is complete, the rule begins executing.

1. If the testing stage determined that the rule will execute its commands, the commands are executed.
   • If a command is marked as evaluatable and evaluation fails, the rule fails immediately.
   • If a command is marked as a function and invoking it fails, the rule fails immediately.
   • If a command not marked as no-fail fails, the rule fails immediately.
2. The rule is set to the Succeeded state if:

   Any prerequisite not marked as hidden is set to Succeeded. Any command non marked as hidden was run.

3. Otherwise, the rule is set to the NothingToDo state.

Modifiers

Rule properties, such as input files, prerequisite actions and the like, are simple string lists. To pass more information about each, such as when a prerequisite is optional, modifiers are used. Modifiers are included at the start of the appropriate string by enclosing them in an "#(...)" identifier. For example, when used as an input file property,

    #(fo)$$MY_FILES

will evaluate $$MY_FILES and set each returned file as an optional input file. The complete list of modifiers and their meaning in each context is outlined below.

Properties

name: string

The rule name. This name will appear in the actions list in the cases where the rule has help, and is the name that other rules use to refer to the rule. The name is set when a rule is requested through the Project::rule() method.

help: string

The help description associated with this rule. Rules with help are displayed to the user when they run "qbuild -actions". Internal rules need not (and should not) have help associated with them.

inputFiles: list<string>

List of files that form the input files for this rule.

outputFiles: list<string>

List of files this rule generates.

prerequisiteActions: list<string>

List of prerequite rules for this rule. This list of rules will complete before this rule executes.

commands: list<string>

List of commands to be executed by this rule.

tests: list<string>

Tests to determine if this rule should be executed.

other: list<string>

List of properties associated with this rule for use in the commands evaluation.

serial: boolean

Set to true if the prerequisite actions of this rule should be executed sequentially. This should generally not be needed, and defaults to false.

category: list<string>

This is used to group rules that use the same utilities. The user can define throttling to ensure that their system does not become bogged down due to excessive processes being run.

For example, with teambuilder, compiling code is relatively cheap but linking remains expensive so while it might be fine to have 50 compile jobs running at the same time it is probably not acceptable to have 40 linker jobs running.

This property is a list. The first value is what the GUI will display. Additional values are used for throttling matching but are not displayed in the GUI.

A basic compiler category might look like this.

            rule.category = "Compiler";

To allow throttling of the host (native) and target (cross) compilers independantly the following might be used instead.

            rule.category = ["Compiler", "Host Compiler"];
            rule.category = ["Compiler", "Target Compiler"];

Note that a rule will be matched on any value. If you have a throttle limit of Compiler:5 and Host Compiler:3 and you have 5 target compiler instances running no new host compiler jobs will be run.

set: object

Used as a quick way to set multiple rule properties. Assigning a property map to the set property causes just the mapped properties to be set in the rule. For example, to set the inputFiles and help properties of a rule "example_rule" one might:

            project.rule("example_rule").set = { inputFiles: ["inputFile1.txt", "inputFile2.txt"],
                                                 help: "This is an example rule" };

If the example_rule already existed, its other properties would be left untouched.

See also Javascript Binding.