1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
|
// 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.runtime;
import com.google.devtools.common.options.Option;
import com.google.devtools.common.options.OptionsBase;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
/**
* An annotation that lets blaze commands specify their options and their help.
* The annotations are processed by {@link BlazeCommand}.
*/
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
public @interface Command {
/**
* The name of the command, as the user would type it.
*/
String name();
/**
* Options processed by the command, indicated by options interfaces.
* These interfaces must contain methods annotated with {@link Option}.
*/
Class<? extends OptionsBase>[] options() default {};
/**
* The set of other Blaze commands that this annotation's command "inherits"
* options from. These classes must be annotated with {@link Command}.
*/
Class<? extends BlazeCommand>[] inherits() default {};
/**
* A short description, which appears in 'blaze help'.
*/
String shortDescription();
/**
* True if the configuration-specific options should be available for this command.
*/
boolean usesConfigurationOptions() default false;
/**
* True if the command runs a build.
*/
boolean builds() default false;
/**
* True if the command should not be shown in the output of 'blaze help'.
*/
boolean hidden() default false;
/**
* Specifies whether this command allows a residue after the parsed options.
* For example, a command might expect a list of targets to build in the
* residue.
*/
boolean allowResidue() default false;
/**
* Specifies whether the command line residue might have sensitive data, or arbitrary command
* line values.
*/
boolean hasSensitiveResidue() default false;
/**
* Returns true if this command wants to write binary data to stdout.
* Enabling this flag will disable ANSI escape stripping for this command.
* This should be used in conjunction with {@code Reporter#switchToAnsiAllowingHandler}.
* See {@link RunCommand} for example usage.
*/
boolean binaryStdOut() default false;
/**
* Returns true if this command wants to write binary data to stderr.
* Enabling this flag will disable ANSI escape stripping for this command.
* This should be used in conjunction with {@code Reporter#switchToAnsiAllowingHandler}.
* See {@link RunCommand} for example usage.
*/
boolean binaryStdErr() default false;
/**
* Returns true if this command may want to write to the command.log.
*
* <p>The clean command would typically set this to false so it can delete the command.log.
*/
boolean writeCommandLog() default true;
/**
* The help message for this command. If the value starts with "resource:",
* the remainder is interpreted as the name of a text file resource (in the
* .jar file that provides the Command implementation class).
*/
String help();
/**
* Returns true iff this command may only be run from within a Blaze workspace. Broadly, this
* should be true for any command that interprets the package-path, since it's potentially
* confusing otherwise.
*/
boolean mustRunInWorkspace() default true;
/**
* Returns true iff this command is allowed to run in the output directory,
* i.e. $OUTPUT_BASE/_blaze_$USER/$MD5/... . No command should be allowed to run here,
* but there are some legacy uses of 'blaze query'.
*/
boolean canRunInOutputDirectory() default false;
/**
* Returns the type completion help for this command, that is the type arguments that this command
* expects. It can be a whitespace separated list if the command take several arguments. The type
* of each arguments can be <code>label</code>, <code>path</code>, <code>string</code>, ...
* It can also be a comma separated list of values, e.g. <code>{value1,value2}<code>. If a command
* accept several argument types, they can be combined with |, e.g <code>label|path</code>.
*/
String completion() default "";
}
|
