// Copyright 2014 The Bazel Authors. All rights reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
package com.google.devtools.build.lib.rules.extra;
import static com.google.devtools.build.lib.packages.Attribute.ConfigurationTransition.HOST;
import static com.google.devtools.build.lib.packages.Attribute.attr;
import static com.google.devtools.build.lib.packages.BuildType.LABEL_LIST;
import static com.google.devtools.build.lib.syntax.Type.BOOLEAN;
import static com.google.devtools.build.lib.syntax.Type.STRING;
import static com.google.devtools.build.lib.syntax.Type.STRING_LIST;
import com.google.devtools.build.lib.analysis.BaseRuleClasses;
import com.google.devtools.build.lib.analysis.RuleDefinition;
import com.google.devtools.build.lib.analysis.RuleDefinitionEnvironment;
import com.google.devtools.build.lib.packages.RuleClass;
import com.google.devtools.build.lib.packages.RuleClass.Builder;
/**
* Rule definition for extra_action rule.
*/
public final class ExtraActionRule implements RuleDefinition {
@Override
public RuleClass build(Builder builder, RuleDefinitionEnvironment environment) {
/*
You may refer to this rule by label
in the extra_actions
argument
of action_listener
rules.
*/
return builder
/*
A list of tool
dependencies for this rule.
See the definition of dependencies for more information.
The build system ensures these prerequisites are built before running the
extra_action
command; they are built using the
host
configuration,
since they must run as a tool during the build itself. The path of an individual
tools
target //x:y
can be obtained using
$(location //x:y)
.
All tools and their data dependencies are consolidated into a single tree within which the command can use relative paths. The working directory will be the root of that unified tree.
*/ .add(attr("tools", LABEL_LIST).cfg(HOST).allowedFileTypes().exec()) /* A list of templates for files generated by theextra_action
command.
The template can use the following variables:
extra_action
.
Used to generate a unique output file.
Like genrule cmd attribute with the following differences:
No heuristic label expansion. Only labels using $(location ...) are expanded.
An additional pass is applied to the string to replace all
occurrences of the outputs created from the out_templates
attribute. All occurrences of $(output out_template)
are replaced with the path to the file denoted by label
.
E.g. out_template $(ACTION_ID).analysis
can be matched with $(output $(ACTION_ID).analysis)
.
In effect, this is the same substitution as $(location)
but with a different scope.
extra_action
requires the output of the
original action to be present as input to this extra_action
.
When true (default false), the extra_action can assume that the original action outputs are available as part of its inputs.
*/ .add(attr("requires_action_output", BOOLEAN)) .removeAttribute("deps") .removeAttribute(":action_listener") .build(); } @Override public Metadata getMetadata() { return RuleDefinition.Metadata.builder() .name("extra_action") .ancestors(BaseRuleClasses.RuleBase.class, BaseRuleClasses.MakeVariableExpandingRule.class) .factoryClass(ExtraActionFactory.class) .build(); } } /*
An extra_action
rule doesn't produce any meaningful output
when specified as a regular build target. Instead, it allows tool developers
to insert additional actions into the build graph that shadow existing actions.
See action_listener
for details
on how to enable extra_action
s.
The extra_action
s run as a command-line. The command-line tool gets
access to a file containing a protocol buffer as $(EXTRA_ACTION_FILE)
with detailed information on the original action it is shadowing.
It also has access to all the input files the original action has access to.
See extra_actions.proto
for details on the data stored inside the protocol buffer. Each proto file
contains an ExtraActionInfo message.
Just like all other actions, extra actions are sandboxed, and should be designed to handle that.
*/