Home · Overviews · Reference · Classes codeless banner

Rule Javascript Class Reference

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 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 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 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.
  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.

Applies toModifierEffect
Input Files (recursive)fEvaluate string. The returned list<string> is treated as additional input files.
nIf freshening of this file fails, the rule doesn't necessarily fail.
vDo not evaluate string (default).
oOptional. If the input file does not exist and a rule cannot be found to freshen it, the rule will run. However, if a rule can be found and freshening fails the rule will still value (assuming n isn't on).
sCombime with o to trigger the rule if the file does not exist. Useful for rules that change their input files after they run (eg. .d files).
CommandsfEvaluate string. The returned list<string> is joined with " "'s and treated as a single command (default).
eDo not echo the command before running it.
EOnly echo the command if there is output from it.
hRun the command, but this command is not counted towards the rules ran commands count.
nIf this command fails, the rule doesn't necessarily fail.
vDo not evaluate the string.
tRun the command in a virtual TTy. This allows programs to output in color (isatty() returns true instead of false).
sCancel the rest of the commands if this command fails.
TestsfEvaluate string (default). The test fails if the returned string is empty or is equal to false. The test passes in all other cases. Note that shell commands cannot be run.
Prerequisite actions (recursive)fEvaluate string. The returned list<string> is treated as additional prerequisites.
hRun the prerequisite, but don't use the prerequisite running as reason to run this rule.
nIf the prerequisite fails, the rule doesn't necessarily fail.
vDo not evaluate the string (default).
oOptional. If the rule cannot be found, the rule will continue processing. However, if a rule can be found, and running the rule fails, the rule will still fail (assuming n isn't on).
cCall the function, passing the rule name as an argument. The returned list<string> is treated as additional prerequisite actions.

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.


Copyright © 2009 Nokia
Qt Extended - QBuild Maintainer Guide