aboutsummaryrefslogtreecommitdiff
path: root/libbuild2/build/script/builtin.cli
blob: cf1540d56976bdc447cc016477a4d573012167e1 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
// 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.
        //
        // 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 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, 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.
        //
        // @@ 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.

      };
    }
  }
}