tools/gn/docs/reference.md - Issue 1301423006: Escape "--" in markdown rendering for GN reference docs.

Side by Side Diff: tools/gn/docs/reference.md

Issue 1301423006: Escape "--" in markdown rendering for GN reference docs. (Closed) Base URL: https://chromium.googlesource.com/chromium/src.git@gn_reference

Patch Set: fix second dec== Created 5 years, 3 months ago

Use n/p to move between diff chunks; N/P to move between comments. Draft comments are only viewable by you.

Jump to:

View unified diff | Download patch

OLD	NEW
1 # GN Reference	1 # GN Reference

2	2

3 This page is automatically generated from `gn help --markdown all`.	3 This page is automatically generated from `gn help --markdown all`.

4	4

5 ## --args: Specifies build arguments overrides.	5 ## \--args: Specifies build arguments overrides.

6	6

7 ```	7 ```

8 See "gn help buildargs" for an overview of how build arguments work.	8 See "gn help buildargs" for an overview of how build arguments work.

9	9

10 Most operations take a build directory. The build arguments are taken	10 Most operations take a build directory. The build arguments are taken

11 from the previous build done in that directory. If a command specifies	11 from the previous build done in that directory. If a command specifies

12 --args, it will override the previous arguments stored in the build	12 --args, it will override the previous arguments stored in the build

13 directory, and use the specified ones.	13 directory, and use the specified ones.

14	14

15 The args specified will be saved to the build directory for subsequent	15 The args specified will be saved to the build directory for subsequent

(...skipping 17 matching lines...) Expand all Loading...
33	33

34 gn gen out/Default --args='foo="bar" enable=true blah=7'	34 gn gen out/Default --args='foo="bar" enable=true blah=7'

35	35

36 gn check out/Default --args=""	36 gn check out/Default --args=""

37 Clears existing build args from the directory.	37 Clears existing build args from the directory.

38	38

39 gn desc out/Default --args="some_list=[1, false, \"foo\"]"	39 gn desc out/Default --args="some_list=[1, false, \"foo\"]"

40	40

41	41

42 ```	42 ```

43 ## --[no]color: Forces colored output on or off.	43 ## \--[no]color: Forces colored output on or off.

44	44

45 ```	45 ```

46 Normally GN will try to detect whether it is outputting to a terminal	46 Normally GN will try to detect whether it is outputting to a terminal

47 and will enable or disable color accordingly. Use of these switches	47 and will enable or disable color accordingly. Use of these switches

48 will override the default.	48 will override the default.

49	49

50 ```	50 ```

51	51

52 ### Examples	52 ### Examples

53	53

54 ```	54 ```

55 gn gen out/Default --color	55 gn gen out/Default --color

56	56

57 gn gen out/Default --nocolor	57 gn gen out/Default --nocolor

58	58

59	59

60 ```	60 ```

61 ## --dotfile: Override the name of the ".gn" file.	61 ## \--dotfile: Override the name of the ".gn" file.

62	62

63 ```	63 ```

64 Normally GN loads the ".gn"file from the source root for some basic	64 Normally GN loads the ".gn"file from the source root for some basic

65 configuration (see "gn help dotfile"). This flag allows you to	65 configuration (see "gn help dotfile"). This flag allows you to

66 use a different file.	66 use a different file.

67	67

68 Note that this interacts with "--root" in a possibly incorrect way.	68 Note that this interacts with "--root" in a possibly incorrect way.

69 It would be nice to test the edge cases and document or fix.	69 It would be nice to test the edge cases and document or fix.

70	70

71	71

72 ```	72 ```

73 ## --markdown: write the output in the Markdown format.	73 ## \--markdown: write the output in the Markdown format.

74	74

75 ## --[no]color: Forces colored output on or off.	75 ## \--[no]color: Forces colored output on or off.

76	76

77 ```	77 ```

78 Normally GN will try to detect whether it is outputting to a terminal	78 Normally GN will try to detect whether it is outputting to a terminal

79 and will enable or disable color accordingly. Use of these switches	79 and will enable or disable color accordingly. Use of these switches

80 will override the default.	80 will override the default.

81	81

82 ```	82 ```

83	83

84 ### Examples	84 ### Examples

85	85

86 ```	86 ```

87 gn gen out/Default --color	87 gn gen out/Default --color

88	88

89 gn gen out/Default --nocolor	89 gn gen out/Default --nocolor

90	90

91	91

92 ```	92 ```

93 ## -q: Quiet mode. Don't print output on success.	93 ## -q: Quiet mode. Don't print output on success.

94	94

95 ```	95 ```

96 This is useful when running as a part of another script.	96 This is useful when running as a part of another script.

97	97

98	98

99 ```	99 ```

100 ## --root: Explicitly specify source root.	100 ## \--root: Explicitly specify source root.

101	101

102 ```	102 ```

103 Normally GN will look up in the directory tree from the current	103 Normally GN will look up in the directory tree from the current

104 directory to find a ".gn" file. The source root directory specifies	104 directory to find a ".gn" file. The source root directory specifies

105 the meaning of "//" beginning with paths, and the BUILD.gn file	105 the meaning of "//" beginning with paths, and the BUILD.gn file

106 in that directory will be the first thing loaded.	106 in that directory will be the first thing loaded.

107	107

108 Specifying --root allows GN to do builds in a specific directory	108 Specifying --root allows GN to do builds in a specific directory

109 regardless of the current directory.	109 regardless of the current directory.

110	110

111 ```	111 ```

112	112

113 ### Examples	113 ### Examples

114	114

115 ```	115 ```

116 gn gen //out/Default --root=/home/baracko/src	116 gn gen //out/Default --root=/home/baracko/src

117	117

118 gn desc //out/Default --root="C:\Users\BObama\My Documents\foo"	118 gn desc //out/Default --root="C:\Users\BObama\My Documents\foo"

119	119

120	120

121 ```	121 ```

122 ## --runtime-deps-list-file: Save runtime dependencies for targets in file.	122 ## \--runtime-deps-list-file: Save runtime dependencies for targets in file.

123	123

124 ```	124 ```

125 --runtime-deps-list-file=<filename>	125 --runtime-deps-list-file=<filename>

126	126

127 Where <filename> is a text file consisting of the labels, one per	127 Where <filename> is a text file consisting of the labels, one per

128 line, of the targets for which runtime dependencies are desired.	128 line, of the targets for which runtime dependencies are desired.

129	129

130 See "gn help runtime_deps" for a description of how runtime	130 See "gn help runtime_deps" for a description of how runtime

131 dependencies are computed.	131 dependencies are computed.

132	132

(...skipping 14 matching lines...) Expand all Loading...
147 This is probably not useful; the use-case for this feature is	147 This is probably not useful; the use-case for this feature is

148 generally executable targets.	148 generally executable targets.

149	149

150 The runtime dependency file will list one file per line, with no	150 The runtime dependency file will list one file per line, with no

151 escaping. The files will be relative to the root_build_dir. The first	151 escaping. The files will be relative to the root_build_dir. The first

152 line of the file will be the main output file of the target itself	152 line of the file will be the main output file of the target itself

153 (in the above example, "bar.so").	153 (in the above example, "bar.so").

154	154

155	155

156 ```	156 ```

157 ## --time: Outputs a summary of how long everything took.	157 ## \--time: Outputs a summary of how long everything took.

158	158

159 ```	159 ```

160 Hopefully self-explanatory.	160 Hopefully self-explanatory.

161	161

162 ```	162 ```

163	163

164 ### Examples	164 ### Examples

165	165

166 ```	166 ```

167 gn gen out/Default --time	167 gn gen out/Default --time

168	168

169	169

170 ```	170 ```

171 ## --tracelog: Writes a Chrome-compatible trace log to the given file.	171 ## \--tracelog: Writes a Chrome-compatible trace log to the given file.

172	172

173 ```	173 ```

174 The trace log will show file loads, executions, scripts, and writes.	174 The trace log will show file loads, executions, scripts, and writes.

175 This allows performance analysis of the generation step.	175 This allows performance analysis of the generation step.

176	176

177 To view the trace, open Chrome and navigate to "chrome://tracing/",	177 To view the trace, open Chrome and navigate to "chrome://tracing/",

178 then press "Load" and specify the file you passed to this parameter.	178 then press "Load" and specify the file you passed to this parameter.

179	179

180 ```	180 ```

181	181

182 ### Examples	182 ### Examples

183	183

184 ```	184 ```

185 gn gen out/Default --tracelog=mytrace.trace	185 gn gen out/Default --tracelog=mytrace.trace

186	186

187	187

188 ```	188 ```

189 ## -v: Verbose logging.	189 ## -v: Verbose logging.

190	190

191 ```	191 ```

192 This will spew logging events to the console for debugging issues.	192 This will spew logging events to the console for debugging issues.

193 Good luck!	193 Good luck!

194	194

195	195

196 ```	196 ```

197 ## gn args <out_dir> [--list] [--short] [--args]	197 ## gn args <out_dir> [\--list] [\--short] [\--args]

198	198

199 ```	199 ```

200 See also "gn help buildargs" for a more high-level overview of how	200 See also "gn help buildargs" for a more high-level overview of how

201 build arguments work.	201 build arguments work.

202	202

203 ```	203 ```

204	204

205 ### Usage	205 ### Usage

206 ```	206 ```

207 gn args <out_dir>	207 gn args <out_dir>

(...skipping 44 matching lines...) Expand 10 before \| Expand all \| Expand 10 after Loading...
252 Prints information about the "target_cpu" argument for the out/Debug	252 Prints information about the "target_cpu" argument for the out/Debug

253 build.	253 build.

254	254

255 gn args --list --args="os=\"android\" enable_doom_melon=true"	255 gn args --list --args="os=\"android\" enable_doom_melon=true"

256 Prints all arguments with the default values for a build with the	256 Prints all arguments with the default values for a build with the

257 given arguments set (which may affect the values of other	257 given arguments set (which may affect the values of other

258 arguments).	258 arguments).

259	259

260	260

261 ```	261 ```

262 ## gn check <out_dir> [<label_pattern>] [--force]	262 ## gn check <out_dir> [<label_pattern>] [\--force]

263	263

264 ```	264 ```

265 "gn check" is the same thing as "gn gen" with the "--check" flag	265 "gn check" is the same thing as "gn gen" with the "--check" flag

266 except that this command does not write out any build files. It's	266 except that this command does not write out any build files. It's

267 intended to be an easy way to manually trigger include file checking.	267 intended to be an easy way to manually trigger include file checking.

268	268

269 The <label_pattern> can take exact labels or patterns that match more	269 The <label_pattern> can take exact labels or patterns that match more

270 than one (although not general regular expressions). If specified,	270 than one (although not general regular expressions). If specified,

271 only those matching targets will be checked. See	271 only those matching targets will be checked. See

272 "gn help label_pattern" for details.	272 "gn help label_pattern" for details.

(...skipping 29 matching lines...) Expand all Loading...
302	302

303 ```	303 ```

304 ## gn clean <out_dir>	304 ## gn clean <out_dir>

305	305

306 ```	306 ```

307 Deletes the contents of the output directory except for args.gn and	307 Deletes the contents of the output directory except for args.gn and

308 creates a Ninja build environment sufficient to regenerate the build.	308 creates a Ninja build environment sufficient to regenerate the build.

309	309

310	310

311 ```	311 ```

312 ## gn desc <out_dir> <target label> [<what to show>] [--blame]	312 ## gn desc <out_dir> <target label> [<what to show>] [\--blame]

313	313

314 ```	314 ```

315 Displays information about a given labeled target for the given build.	315 Displays information about a given labeled target for the given build.

316 The build parameters will be taken for the build in the given	316 The build parameters will be taken for the build in the given

317 <out_dir>.	317 <out_dir>.

318	318

319 ```	319 ```

320	320

321 ### Possibilities for <what to show>	321 ### Possibilities for <what to show>

322 ```	322 ```

(...skipping 144 matching lines...) Expand 10 before \| Expand all \| Expand 10 after Loading...
467 gn desc out/Foo :base_unittests deps --tree	467 gn desc out/Foo :base_unittests deps --tree

468 Shows a dependency tree of the "base_unittests" project in	468 Shows a dependency tree of the "base_unittests" project in

469 the current directory.	469 the current directory.

470	470

471 gn desc out/Debug //base defines --blame	471 gn desc out/Debug //base defines --blame

472 Shows defines set for the //base:base target, annotated by where	472 Shows defines set for the //base:base target, annotated by where

473 each one was set from.	473 each one was set from.

474	474

475	475

476 ```	476 ```

477 ## gn format [--dump-tree] [--in-place] [--stdin] BUILD.gn	477 ## gn format [\--dump-tree] [\--in-place] [\--stdin] BUILD.gn

478	478

479 ```	479 ```

480 Formats .gn file to a standard format.	480 Formats .gn file to a standard format.

481	481

482 ```	482 ```

483	483

484 ### Arguments	484 ### Arguments

485 ```	485 ```

486 --dry-run	486 --dry-run

487 Does not change or output anything, but sets the process exit code	487 Does not change or output anything, but sets the process exit code

(...skipping 43 matching lines...) Expand 10 before \| Expand all \| Expand 10 after Loading...
531	531

532	532

533 ```	533 ```

534 ## gn help <anything>	534 ## gn help <anything>

535 ```	535 ```

536 Yo dawg, I heard you like help on your help so I put help on the help	536 Yo dawg, I heard you like help on your help so I put help on the help

537 in the help.	537 in the help.

538	538

539	539

540 ```	540 ```

541 ## gn ls <out_dir> [<label_pattern>] [--all-toolchains] [--as=...]	541 ## gn ls <out_dir> [<label_pattern>] [\--all-toolchains] [\--as=...]

542 ```	542 ```

543 [--type=...] [--testonly=...]	543 [--type=...] [--testonly=...]

544	544

545 Lists all targets matching the given pattern for the given build	545 Lists all targets matching the given pattern for the given build

546 directory. By default, only targets in the default toolchain will	546 directory. By default, only targets in the default toolchain will

547 be matched unless a toolchain is explicitly supplied.	547 be matched unless a toolchain is explicitly supplied.

548	548

549 If the label pattern is unspecified, list all targets. The label	549 If the label pattern is unspecified, list all targets. The label

550 pattern is not a general regular expression (see	550 pattern is not a general regular expression (see

551 "gn help label_pattern"). If you need more complex expressions,	551 "gn help label_pattern"). If you need more complex expressions,

(...skipping 83 matching lines...) Expand 10 before \| Expand all \| Expand 10 after Loading...
635	635

636 ```	636 ```

637	637

638 ### Example	638 ### Example

639	639

640 ```	640 ```

641 gn path out/Default //base //tools/gn	641 gn path out/Default //base //tools/gn

642	642

643	643

644 ```	644 ```

645 ## *gn refs <out_dir> (<label_pattern>\|<label>\|<file>\|@<response_file>) [--all ]**	645 ## *gn refs <out_dir> (<label_pattern>\|<label>\|<file>\|@<response_file>) [\--al l]**

646 ```	646 ```

647 [--all-toolchains] [--as=...] [--testonly=...] [--type=...]	647 [--all-toolchains] [--as=...] [--testonly=...] [--type=...]

648	648

649 Finds reverse dependencies (which targets reference something). The	649 Finds reverse dependencies (which targets reference something). The

650 input is a list containing:	650 input is a list containing:

651	651

652 - Target label: The result will be which targets depend on it.	652 - Target label: The result will be which targets depend on it.

653	653

654 - Config label: The result will be which targets list the given	654 - Config label: The result will be which targets list the given

655 config in its "configs" or "public_configs" list.	655 config in its "configs" or "public_configs" list.

(...skipping 4154 matching lines...) Expand 10 before \| Expand all \| Expand 10 after Loading...
4810	4810

4811	4811

4812 ```	4812 ```

4813 **Available global switches	4813 **Available global switches

4814 ** Do "gn help --the_switch_you_want_help_on" for more. Individual	4814 ** Do "gn help --the_switch_you_want_help_on" for more. Individual

4815 commands may take command-specific switches not listed here. See the	4815 commands may take command-specific switches not listed here. See the

4816 help on your specific command for more.	4816 help on your specific command for more.

4817	4817

4818 ```	4818 ```

4819	4819

4820 --args: Specifies build arguments overrides.	4820 \--args: Specifies build arguments overrides.

4821 --color: Force colored output.	4821 \--color: Force colored output.

4822 --dotfile: Override the name of the ".gn" file.	4822 \--dotfile: Override the name of the ".gn" file.

4823 --markdown: write the output in the Markdown format.	4823 \--markdown: write the output in the Markdown format.

4824 --nocolor: Force non-colored output.	4824 \--nocolor: Force non-colored output.

4825 -q: Quiet mode. Don't print output on success.	4825 -q: Quiet mode. Don't print output on success.

4826 --root: Explicitly specify source root.	4826 \--root: Explicitly specify source root.

4827 --runtime-deps-list-file: Save runtime dependencies for targets in file.	4827 \--runtime-deps-list-file: Save runtime dependencies for targets in file.

4828 --time: Outputs a summary of how long everything took.	4828 \--time: Outputs a summary of how long everything took.

4829 --tracelog: Writes a Chrome-compatible trace log to the given file.	4829 \--tracelog: Writes a Chrome-compatible trace log to the given file.

4830 -v: Verbose logging.	4830 -v: Verbose logging.

4831 --version: Prints the GN version number and exits.	4831 \--version: Prints the GN version number and exits.

4832	4832

4833 ```	4833 ```

OLD	NEW

« no previous file with comments | « no previous file | tools/gn/standard_out.cc » ('j') | no next file with comments »