aboutsummaryrefslogtreecommitdiff
path: root/libbuild2/build/script/builtin.cli
diff options
context:
space:
mode:
Diffstat (limited to 'libbuild2/build/script/builtin.cli')
-rw-r--r--libbuild2/build/script/builtin.cli128
1 files changed, 128 insertions, 0 deletions
diff --git a/libbuild2/build/script/builtin.cli b/libbuild2/build/script/builtin.cli
new file mode 100644
index 0000000..5aea034
--- /dev/null
+++ b/libbuild2/build/script/builtin.cli
@@ -0,0 +1,128 @@
+// 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 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.
+ //
+ 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.
+
+ };
+ }
+ }
+}