// file      : libbuild2/build/script/builtin.cli
// license   : MIT; see accompanying LICENSE file

include <libbuild2/common.cli>;

// Note that options in this file are undocumented because we generate neither
// the usage printing code nor man pages. Instead, they are documented in the
// manual.
//
namespace build2
{
  namespace build
  {
    namespace script
    {
      // Pseudo-builtin options.
      //
      class depdb_dyndep_options
      {
        // Note that --byproduct, if any, must be the first option and is
        // handled ad hoc, kind of as a sub-command.
        //
        // Similarly, --update-{include,exclude} are handled ad hoc and must
        // be literals, similar to the -- separator. They specify prerequisite
        // targets/patterns to include/exclude (from the static prerequisite
        // set) for update during match (those excluded will be updated during
        // execute). The order in which these options are specified is
        // significant with the first target/pattern that matches determining
        // the result. If only the --update-include options are specified,
        // then only the explicitly included prerequisites will be updated.
        // Otherwise, all prerequisites that are not explicitly excluded will
        // be updated. If none of these options is specified, then all the
        // static prerequisites are updated during match. Note also that these
        // options do not apply to ad hoc prerequisites which are always
        // updated during match.
        //
        // Note that in the future we may extend --cwd support to the non-
        // byproduct mode where it will also have the `env --cwd` semantics
        // (thus the matching name). Note that it will also be incompatible
        // with support for generated files (and thus -I) at least in the make
        // format where we use relative paths for non-existent files.
        //
        // Note on naming: whenever we (may) have two options, one for target
        // and the other for prerequisite, we omit "prerequisite" as that's
        // what we extract by default and most commonly. For example:
        //
        // --what          --what-target
        // --default-type  --default-target-type
        //
        path --file;                  // Read from file rather than stdin.

        string --format;              // Dependency format: make (default).

        string --what;                // Dependency kind, e.g., "header".

        dir_paths --include-path|-I;  // Search paths for generated files.

        string --default-type;        // Default prerequisite type to use
                                      // if none could be derived from ext.

        bool --adhoc;                 // Treat dynamically discovered
                                      // prerequisites as ad hoc (so they
                                      // don't end up in $<; only in the
                                      // normal mode).

        dir_path --cwd;               // Builtin's working directory used
                                      // to complete relative paths (only
                                      // in --byproduct mode).

        bool --drop-cycles;           // Drop prerequisites that are also
                                      // targets. Only use if you are sure
                                      // such cycles are harmless, that is,
                                      // the output is not affected by such
                                      // prerequisites' content.
      };
    }
  }
}