Home | History | Annotate | Download | only in options 
      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