// 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 or --dyn-target, if any, must be the first
        // option and is handled ad hoc.
        //
        // 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          --target-what
        // --default-type  --target-default-type
        //
        path --file;                  // Read from file rather than stdin.

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

        // Dynamic dependency extraction options.
        //
        string --what;                // Prerequisite kind, e.g., "header".

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

        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 of
                                      // prerequisites (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.

        // Dynamic target extraction options.
        //
        // This functionality is enabled with the --dyn-target option. Only
        // the make format is supported, where the listed targets are added as
        // ad hoc group members (unless already specified as static members).
        // This functionality is not available in the byproduct mode.
        //
        // @@ BTW, here what would likely be more useful than default target
        //    is the ability to specify custom extension-to-type mapping in
        //    order to resolve ambiguities. See also the issue with getting
        //    these options during clean.
        //
        string --target-what;         // Target kind, e.g., "source".

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

        dir_path --target-cwd;        // Builtin's working directory used to
                                      // complete relative paths of targets.

      };
    }
  }
}