1 // Copyright 2017 The Bazel Authors. All rights reserved. 2 // 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 package com.google.devtools.common.options; 15 16 /** 17 * These categories are used to logically group options in generated documentation, both the command 18 * line output for the standard HelpCommand and the html output used for command-line-reference on 19 * the website. 20 * 21 * <p>Constraints for adding new categories: 22 * 23 * <ul> 24 * <li>Since these are for grouping, we want useful sizes of groups. Somewhere between 5 and 200 25 * (ok, maybe less than that) options, probably. A category for 2 options is pretty useless, 26 * and a category for all options equally so. 27 * <li>Each option needs to belong to exactly one of these groups, so the categories should be 28 * clearly distinct. 29 * <li>These are easy to change, and not brittle, so feel free to add new ones. However, if you 30 * add a new category, other flags that used to be categorized in some related way but belong 31 * in the new category should be updated to keep our docs fresh. Either do it yourself or file 32 * a bug against the owners of these flags. 33 * </ul> 34 */ 35 public enum OptionDocumentationCategory { 36 /** 37 * A category to aid transition, to make it obvious that an option needs to be categorized. Note: 38 * Do NOT add this to new flags! 39 */ 40 UNCATEGORIZED, 41 42 /** 43 * A category for flags that are intended to not be listed, and for whom a documentation category 44 * does not make sense. 45 */ 46 UNDOCUMENTED, 47 48 /** 49 * Startup options appear before the command and are parsed by the client. Changing them may cause 50 * a server restart, see OptionEffectTag.LOSES_INCREMENTAL_STATE. 51 */ 52 BAZEL_CLIENT_OPTIONS, 53 54 /** This option's primary purpose is to affect the verbosity, format or location of logging. */ 55 LOGGING, 56 57 /** 58 * This option affects how strictly Bazel enforces valid build inputs (rule definitions, 59 * flag combinations, etc). 60 */ 61 INPUT_STRICTNESS, 62 63 /** This option deals with how to go about executing the build. */ 64 EXECUTION_STRATEGY, 65 66 /** This option deals with build time optimizations. */ 67 BUILD_TIME_OPTIMIZATION, 68 69 /** 70 * This option lets a user specify WHICH output they wish the command to have. It might be a 71 * selective filter on the outputs, or a blanket on/off switch. 72 */ 73 OUTPUT_SELECTION, 74 75 /** 76 * This option lets a user configure the outputs. Unlike OUTPUT_SELECTION, which specifies whether 77 * or not an output is built, this specifies qualities of the output. 78 */ 79 OUTPUT_PARAMETERS, 80 81 /** 82 * This option provides information about signing outputs of the build. (For example, signing 83 * an iOS application with a certificate.) 84 */ 85 SIGNING, 86 87 /** 88 * This option dictates information about the test environment or test runner. 89 */ 90 TESTING, 91 92 /** 93 * This option lets a user configure the toolchain used to execute actions in the build. This is 94 * not to be used for parameters to a toolchain, which are more likely to fall into another 95 * category; options in this category are for selecting between available toolchains, for example 96 * based on execution-environment requirements. 97 */ 98 TOOLCHAIN, 99 100 /** This option relates to query output and semantics. */ 101 QUERY, 102 103 /** 104 * This option specifies or alters a generic input to a Bazel command. This category should only 105 * be used if the input is generic and does not fall into other categories, such as toolchain- 106 * specific inputs. 107 */ 108 GENERIC_INPUTS, 109 } 110