// 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.
        //
        // Currently Supported dependency formats (--format) are `make`
        // (default) and `lines`.
        //
        // The `make` format is the make dependency declaration in the
        // `<target>...: [<prerequisite>...]` form. In the non-byproduct mode
        // a relative prerequisite path is considered non-existent.
        //
        // The `lines` format lists targets and/or prerequisites one per line.
        // If the --dyn-target option is specified then the target list is
        // expected to come first separated from the prerequisites list with a
        // blank line. If there are no prerequisites, then the blank line can
        // be omitted. If the --dyn-target option is not specified, then all
        // lines are treated as prerequisites and there should be no blank
        // lines. In the non-byproduct mode a prerequisite line that starts
        // with a leading space is considered a non-existent prerequisite.
        // Currently only relative non-existent prerequisites are supported.
        // Finally, in this mode, if the prerequisite is syntactically a
        // directory (that is, it ends with a trailing directory separator),
        // then it is added as fsdir{}. This can be used to handle situations
        // where the dynamic targets are placed into subdirectories.
        //
        // 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),
                                      // or `lines`.

        // 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 extension.

        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, lines format for existing
                                      // paths).

        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` and `lines` formats are supported (see above), 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.
        //
        string --target-what;         // Target kind, e.g., "source".

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

        map<string, string>           // Extension to target type mapping in
          --target-extension-type;    // the <ext>=<type> form, for example,
                                      // h=hxx. This mapping is considered
                                      // before attempting to automatically
                                      // map the extension and so can be used
                                      // to resolve ambiguities.

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

      };
    }
  }
}