blob: 1e27956ed206e806849534a1b009723a3d8e9d65 [file] [log] [blame]
Damien Martin-Guillerezf88f4d82015-09-25 13:56:55 +00001// Copyright 2014 The Bazel Authors. All rights reserved.
Han-Wen Nienhuysd08b27f2015-02-25 16:45:20 +01002//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7// http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15package com.google.devtools.build.lib.analysis;
16
Carmi Grushko97f81482016-04-08 14:14:56 +000017import com.google.auto.value.AutoValue;
Han-Wen Nienhuysd08b27f2015-02-25 16:45:20 +010018import com.google.devtools.build.lib.packages.RuleClass;
Googler58505032015-03-19 16:12:34 +000019import com.google.devtools.build.lib.packages.RuleClass.Builder.RuleClassType;
Googler58505032015-03-19 16:12:34 +000020import java.util.Arrays;
21import java.util.Collections;
22import java.util.List;
Han-Wen Nienhuysd08b27f2015-02-25 16:45:20 +010023
24/**
25 * This class is a common ancestor for every rule object.
26 *
Ulf Adams3ab82f72015-09-04 12:10:53 +000027 * <p>Implementors are also required to have the {@link Metadata} annotation
Han-Wen Nienhuysd08b27f2015-02-25 16:45:20 +010028 * set.
29 */
30public interface RuleDefinition {
31 /**
32 * This method should return a RuleClass object that represents the rule. The usual pattern is
33 * that various setter methods are called on the builder object passed in as the argument, then
34 * the object that is built by the builder is returned.
35 *
36 * @param builder A {@link com.google.devtools.build.lib.packages.RuleClass.Builder} object
37 * already preloaded with the attributes of the ancestors specified in the {@link
Ulf Adams3ab82f72015-09-04 12:10:53 +000038 * Metadata} annotation.
Han-Wen Nienhuysd08b27f2015-02-25 16:45:20 +010039 * @param environment The services Blaze provides to rule definitions.
40 *
41 * @return the {@link RuleClass} representing the rule.
42 */
43 RuleClass build(RuleClass.Builder builder, RuleDefinitionEnvironment environment);
Googler58505032015-03-19 16:12:34 +000044
45 /**
46 * Returns metadata for this rule.
47 */
48 Metadata getMetadata();
49
50 /**
51 * Value class that contains the name, type, ancestors of a rule, as well as a reference to the
52 * configured target factory.
53 */
Carmi Grushko97f81482016-04-08 14:14:56 +000054 @AutoValue
Googler58505032015-03-19 16:12:34 +000055 public abstract static class Metadata {
56 /**
57 * The name of the rule, as it appears in the BUILD file. If it starts with
58 * '$', the rule will be hidden from users and will only be usable from
59 * inside Blaze.
60 */
61 public abstract String name();
62
63 /**
64 * The type of the rule. It can be an abstract rule, a normal rule or a test
65 * rule. If the rule type is abstract, the configured class must not be set.
66 */
67 public abstract RuleClassType type();
68
69 /**
70 * The {@link RuleConfiguredTargetFactory} class that implements this rule. If the rule is
71 * abstract, this must not be set.
72 */
73 public abstract Class<? extends RuleConfiguredTargetFactory> factoryClass();
74
75 /**
76 * The list of other rule classes this rule inherits from.
77 */
78 public abstract List<Class<? extends RuleDefinition>> ancestors();
79
80 public static Builder builder() {
Carmi Grushko97f81482016-04-08 14:14:56 +000081 return new AutoValue_RuleDefinition_Metadata.Builder()
Googler58505032015-03-19 16:12:34 +000082 .type(RuleClassType.NORMAL)
83 .factoryClass(RuleConfiguredTargetFactory.class)
84 .ancestors(Collections.<Class<? extends RuleDefinition>>emptyList());
85 }
86
87 public static Metadata empty() {
88 return builder().build();
89 }
90
91 /**
92 * Builder class for the Metadata class.
93 */
Carmi Grushko97f81482016-04-08 14:14:56 +000094 @AutoValue.Builder
Googler58505032015-03-19 16:12:34 +000095 public abstract static class Builder {
96 public abstract Builder name(String s);
97 public abstract Builder type(RuleClassType type);
98 public abstract Builder factoryClass(Class<? extends RuleConfiguredTargetFactory> factory);
99 public abstract Builder ancestors(List<Class<? extends RuleDefinition>> ancestors);
Ulf Adams08207112015-04-23 15:49:34 +0000100 @SafeVarargs
101 public final Builder ancestors(Class<? extends RuleDefinition>... ancstrs) {
Googler58505032015-03-19 16:12:34 +0000102 return ancestors(Arrays.asList(ancstrs));
103 }
104 public abstract Metadata build();
105 }
106 }
Han-Wen Nienhuysd08b27f2015-02-25 16:45:20 +0100107}