def register_action (self, action_name, command, bound_list = [], flags = [],
                         function = None):
        """Creates a new build engine action.

        Creates on bjam side an action named 'action_name', with
        'command' as the command to be executed, 'bound_variables'
        naming the list of variables bound when the command is executed
        and specified flag.
        If 'function' is not None, it should be a callable taking three
        parameters:
            - targets
            - sources
            - instance of the property_set class
        This function will be called by set_update_action, and can
        set additional target variables.
        """
        assert isinstance(action_name, basestring)
        assert isinstance(command, basestring)
        assert is_iterable(bound_list)
        assert is_iterable(flags)
        assert function is None or callable(function)

        bjam_flags = reduce(operator.or_,
                            (action_modifiers[flag] for flag in flags), 0)

        # We allow command to be empty so that we can define 'action' as pure
        # python function that would do some conditional logic and then relay
        # to other actions.
        assert command or function
        if command:
            bjam_interface.define_action(action_name, command, bound_list, bjam_flags)

        self.actions[action_name] = BjamAction(action_name, function)

def equal (a, b):
    """ Returns True iff 'a' contains the same elements as 'b', irrespective of their order.
        # TODO: Python 2.4 has a proper set class.
    """
    assert is_iterable(a)
    assert is_iterable(b)
    return contains (a, b) and contains (b, a)

    def option(self, name, value):
        assert is_iterable(name) and isinstance(name[0], basestring)
        assert is_iterable(value) and isinstance(value[0], basestring)
        name = name[0]
        if not name in ["site-config", "user-config", "project-config"]:
            get_manager().errors()("The 'option' rule may be used only in site-config or user-config")

        option.set(name, value[0])

 def do_set_update_action (self, action_name, targets, sources, property_set_):
     assert isinstance(action_name, basestring)
     assert is_iterable(targets)
     assert is_iterable(sources)
     assert isinstance(property_set_, property_set.PropertySet)
     action = self.actions.get(action_name)
     if not action:
         raise Exception("No action %s was registered" % action_name)
     action(targets, sources, property_set_)

def intersection (set1, set2):
    """ Removes from set1 any items which don't appear in set2 and returns the result.
    """
    assert is_iterable(set1)
    assert is_iterable(set2)
    result = []
    for v in set1:
        if v in set2:
            result.append (v)
    return result

def difference (b, a):
    """ Returns the elements of B that are not in A.
    """
    assert is_iterable(b)
    assert is_iterable(a)
    result = []
    for element in b:
        if not element in a:
            result.append (element)

    return result

 def __call__(self, targets, sources, property_set_):
     assert is_iterable(targets)
     assert is_iterable(sources)
     assert isinstance(property_set_, property_set.PropertySet)
     # Bjam actions defined from Python have only the command
     # to execute, and no associated jam procedural code. So
     # passing 'property_set' to it is not necessary.
     bjam_interface.call("set-update-action", self.action_name,
                         targets, sources, [])
     if self.function:
         self.function(targets, sources, property_set_)

    def project(self, *args):
        assert is_iterable(args) and all(is_iterable(arg) for arg in args)
        jamfile_module = self.registry.current().project_module()
        attributes = self.registry.attributes(jamfile_module)

        id = None
        if args and args[0]:
            id = args[0][0]
            args = args[1:]

        if id:
            attributes.set('id', [id])

        explicit_build_dir = None
        for a in args:
            if a:
                attributes.set(a[0], a[1:], exact=0)
                if a[0] == "build-dir":
                    explicit_build_dir = a[1]

        # If '--build-dir' is specified, change the build dir for the project.
        if self.registry.global_build_dir:

            location = attributes.get("location")
            # Project with empty location is 'standalone' project, like
            # user-config, or qt.  It has no build dir.
            # If we try to set build dir for user-config, we'll then
            # try to inherit it, with either weird, or wrong consequences.
            if location and location == attributes.get("project-root"):
                # Re-read the project id, since it might have been changed in
                # the project's attributes.
                id = attributes.get('id')

                # This is Jamroot.
                if id:
                    if explicit_build_dir and os.path.isabs(explicit_build_dir):
                        self.registry.manager.errors()(
"""Absolute directory specified via 'build-dir' project attribute
Don't know how to combine that with the --build-dir option.""")

                    rid = id
                    if rid[0] == '/':
                        rid = rid[1:]

                    p = os.path.join(self.registry.global_build_dir, rid)
                    if explicit_build_dir:
                        p = os.path.join(p, explicit_build_dir)
                    attributes.set("build-dir", p, exact=1)
            elif explicit_build_dir:
                self.registry.manager.errors()(
"""When --build-dir is specified, the 'build-dir'
attribute is allowed only for top-level 'project' invocations""")

    def get_target_variable(self, targets, variable):
        """Gets the value of `variable` on set on the first target in `targets`.

        Args:
            targets (str or list): one or more targets to get the variable from.
            variable (str): the name of the variable

        Returns:
             the value of `variable` set on `targets` (list)

        Example:

            >>> ENGINE = get_manager().engine()
            >>> ENGINE.set_target_variable(targets, 'MY-VAR', 'Hello World')
            >>> ENGINE.get_target_variable(targets, 'MY-VAR')
            ['Hello World']

        Equivalent Jam code:

            MY-VAR on $(targets) = "Hello World" ;
            echo [ on $(targets) return $(MY-VAR) ] ;
            "Hello World"
        """
        if isinstance(targets, str):
            targets = [targets]
        assert is_iterable(targets)
        assert isinstance(variable, basestring)

        return bjam_interface.call('get-target-variable', targets, variable)

    def add_dependency (self, targets, sources):
        """Adds a dependency from 'targets' to 'sources'

        Both 'targets' and 'sources' can be either list
        of target names, or a single target name.
        """
        if isinstance (targets, str):
            targets = [targets]
        if isinstance (sources, str):
            sources = [sources]
        assert is_iterable(targets)
        assert is_iterable(sources)

        for target in targets:
            for source in sources:
                self.do_add_dependency (target, source)

 def do_set_target_variable (self, target, variable, value, append):
     assert isinstance(target, basestring)
     assert isinstance(variable, basestring)
     assert is_iterable(value)
     assert isinstance(append, int)  # matches bools
     if append:
         bjam_interface.call("set-target-variable", target, variable, value, "true")
     else:
         bjam_interface.call("set-target-variable", target, variable, value)

    def set_target_variable (self, targets, variable, value, append=0):
        """ Sets a target variable.

        The 'variable' will be available to bjam when it decides
        where to generate targets, and will also be available to
        updating rule for that 'taret'.
        """
        if isinstance (targets, str):
            targets = [targets]
        if isinstance(value, str):
            value = [value]

        assert is_iterable(targets)
        assert isinstance(variable, basestring)
        assert is_iterable(value)

        for target in targets:
            self.do_set_target_variable (target, variable, value, append)

 def __init__(self, variable_name, values, condition, rule = None):
     assert isinstance(variable_name, basestring)
     assert is_iterable(values) and all(
         isinstance(v, (basestring, type(None))) for v in values)
     assert is_iterable_typed(condition, property_set.PropertySet)
     assert isinstance(rule, (basestring, type(None)))
     self.variable_name = variable_name
     self.values = values
     self.condition = condition
     self.rule = rule

    def set_update_action (self, action_name, targets, sources, properties=None):
        """ Binds a target to the corresponding update action.
            If target needs to be updated, the action registered
            with action_name will be used.
            The 'action_name' must be previously registered by
            either 'register_action' or 'register_bjam_action'
            method.
        """
        if isinstance(targets, str):
            targets = [targets]
        if isinstance(sources, str):
            sources = [sources]
        if properties is None:
            properties = property_set.empty()
        assert isinstance(action_name, basestring)
        assert is_iterable(targets)
        assert is_iterable(sources)
        assert(isinstance(properties, property_set.PropertySet))

        self.do_set_update_action (action_name, targets, sources, properties)

def select_highest_ranked(elements, ranks):
    """ Returns all of 'elements' for which corresponding element in parallel
        list 'rank' is equal to the maximum value in 'rank'.
    """
    assert is_iterable(elements)
    assert is_iterable(ranks)
    if not elements:
        return []

    max_rank = max_element(ranks)

    result = []
    while elements:
        if ranks[0] == max_rank:
            result.append(elements[0])

        elements = elements[1:]
        ranks = ranks[1:]

    return result

def unique(values, stable=False):
    assert is_iterable(values)
    if stable:
        s = set()
        r = []
        for v in values:
            if not v in s:
                r.append(v)
                s.add(v)
        return r
    else:
        return list(set(values))

def max_element (elements, ordered = None):
    """ Returns the maximum number in 'elements'. Uses 'ordered' for comparisons,
        or '<' is none is provided.
    """
    assert is_iterable(elements)
    assert callable(ordered) or ordered is None
    if not ordered: ordered = operator.lt

    max = elements [0]
    for e in elements [1:]:
        if ordered (max, e):
            max = e

    return max

def __add_flag (rule_or_module, variable_name, condition, values):
    """ Adds a new flag setting with the specified values.
        Does no checking.
    """
    assert isinstance(rule_or_module, basestring)
    assert isinstance(variable_name, basestring)
    assert is_iterable_typed(condition, property_set.PropertySet)
    assert is_iterable(values) and all(
        isinstance(v, (basestring, type(None))) for v in values)
    f = Flag(variable_name, values, condition, rule_or_module)

    # Grab the name of the module
    m = __re_first_segment.match (rule_or_module)
    assert m
    module = m.group(1)

    __module_flags.setdefault(module, []).append(f)
    __flags.setdefault(rule_or_module, []).append(f)

def flags(rule_or_module, variable_name, condition, values = []):
    """ Specifies the flags (variables) that must be set on targets under certain
        conditions, described by arguments.
        rule_or_module:   If contains dot, should be a rule name.
                          The flags will be applied when that rule is
                          used to set up build actions.

                          If does not contain dot, should be a module name.
                          The flags will be applied for all rules in that
                          module.
                          If module for rule is different from the calling
                          module, an error is issued.

         variable_name:   Variable that should be set on target

         condition        A condition when this flag should be applied.
                          Should be set of property sets. If one of
                          those property sets is contained in build
                          properties, the flag will be used.
                          Implied values are not allowed:
                          "<toolset>gcc" should be used, not just
                          "gcc". Subfeatures, like in "<toolset>gcc-3.2"
                          are allowed. If left empty, the flag will
                          always used.

                          Property sets may use value-less properties
                          ('<a>'  vs. '<a>value') to match absent
                          properties. This allows to separately match

                             <architecture>/<address-model>64
                             <architecture>ia64/<address-model>

                          Where both features are optional. Without this
                          syntax we'd be forced to define "default" value.

         values:          The value to add to variable. If <feature>
                          is specified, then the value of 'feature'
                          will be added.
    """
    assert isinstance(rule_or_module, basestring)
    assert isinstance(variable_name, basestring)
    assert is_iterable_typed(condition, basestring)
    assert is_iterable(values) and all(isinstance(v, (basestring, type(None))) for v in values)
    caller = bjam.caller()
    if not '.' in rule_or_module and caller and caller[:-1].startswith("Jamfile"):
        # Unqualified rule name, used inside Jamfile. Most likely used with
        # 'make' or 'notfile' rules. This prevents setting flags on the entire
        # Jamfile module (this will be considered as rule), but who cares?
        # Probably, 'flags' rule should be split into 'flags' and
        # 'flags-on-module'.
        rule_or_module = qualify_jam_action(rule_or_module, caller)
    else:
        # FIXME: revive checking that we don't set flags for a different
        # module unintentionally
        pass

    if condition and not replace_grist (condition, ''):
        # We have condition in the form '<feature>', that is, without
        # value. That's a previous syntax:
        #
        #   flags gcc.link RPATH <dll-path> ;
        # for compatibility, convert it to
        #   flags gcc.link RPATH : <dll-path> ;
        values = [ condition ]
        condition = None

    if condition:
        transformed = []
        for c in condition:
            # FIXME: 'split' might be a too raw tool here.
            pl = [property.create_from_string(s,False,True) for s in c.split('/')]
            pl = feature.expand_subfeatures(pl);
            transformed.append(property_set.create(pl))
        condition = transformed

        property.validate_property_sets(condition)

    __add_flag (rule_or_module, variable_name, condition, values)

def register_components(components):
    """Declare that the components specified by the parameter exist."""
    assert is_iterable(components)
    __components.extend(components)