Skip to content

Commit 6036024

Browse files
authored
Provide a default --target-variant for clang_tidy. (flutter#45909)
Using `engine_repo_tools`, provide a default `--target-variant` for the `clang_tidy` tool. Mostly test code added below, the major change is that `--target-variant` now has a default other than `host_debug` if we're running inside of an engine root (which we ~always are). I didn't make any other changes (i.e. to the pre-commit hook) to keep this change smallish. Also rewrote the `README.md` to represent the current state as best I could.
1 parent 21372b1 commit 6036024

8 files changed

Lines changed: 356 additions & 123 deletions

File tree

‎tools/clang_tidy/README.md‎

Lines changed: 87 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,94 @@
11
# clang_tidy
22

3-
This is a Dart program/library that runs clang_tidy over modified files in the Flutter engine repo.
3+
A wrapper library and program that runs `clang_tidy` on the Flutter engine repo.
44

5-
By default the linter runs on the repo files changed contained in `src/out/host_debug/compile_commands.json` command.
6-
To check files other than in `host_debug` use `--target-variant android_debug_unopt`,
7-
`--target-variant ios_debug_sim_unopt`, etc.
5+
```shell
6+
# Assuming you are in the `flutter` root of the engine repo.
7+
dart ./tools/clang_tidy/bin/main.dart
8+
```
9+
10+
By default, the linter runs over _modified_[^1] files in the _latest_[^2] build
11+
of the engine.
812

9-
Alternatively, use `--compile-commands` to specify a path to a `compile_commands.json` file.
13+
A subset of checks can also be fixed automatically by passing `--fix`:
1014

15+
```shell
16+
dart ./tools/clang_tidy/bin/main.dart --fix
1117
```
12-
$ bin/main.dart --target-variant <engine-variant>
13-
$ bin/main.dart --compile-commands <compile_commands.json-path>
14-
$ bin/main.dart --help
18+
19+
To configure what lints are enabled, see [`.clang-tidy`](../../.clang-tidy).
20+
21+
> **💡 TIP**: If you're looking for the git pre-commit hook configuration, see
22+
> [`githooks`](../githooks).
23+
24+
## Advanced Usage
25+
26+
Some common use cases are described below, or use `--help` to see all options.
27+
28+
### Run with checks added or removed
29+
30+
To run adding a check _not_ specified in `.clang-tidy`:
31+
32+
```shell
33+
dart ./tools/clang_tidy/bin/main.dart --checks="<check-name-to-run>"
1534
```
35+
36+
It's possible also to use wildcards to add multiple checks:
37+
38+
```shell
39+
dart ./tools/clang_tidy/bin/main.dart --checks="readability-*"
40+
```
41+
42+
To remove a specific check:
43+
44+
```shell
45+
dart ./tools/clang_tidy/bin/main.dart --checks="-<check-name-to-remove>"
46+
```
47+
48+
To remove multiple checks:
49+
50+
```shell
51+
dart ./tools/clang_tidy/bin/main.dart --checks="-readability-*"
52+
```
53+
54+
To remove _all_ checks (usually to add a specific check):
55+
56+
```shell
57+
dart ./tools/clang_tidy/bin/main.dart --checks="-*,<only-check-to-run>"
58+
```
59+
60+
### Specify a specific build
61+
62+
There are some rules that are only applicable to certain builds, or to check
63+
a difference in behavior between two builds.
64+
65+
Use `--target-variant` to specify a build:
66+
67+
```shell
68+
dart ./tools/clang_tidy/bin/main.dart --target-variant <engine-variant>
69+
```
70+
71+
For example, to check the `android_debug_unopt` build:
72+
73+
```shell
74+
dart ./tools/clang_tidy/bin/main.dart --target-variant android_debug_unopt
75+
```
76+
77+
In rarer cases, for example comparing two different checkouts of the engine,
78+
use `--src-dir=<path/to/engine/src>`.
79+
80+
### Lint entire repository
81+
82+
When adding a new lint rule, or when checking lint rules that impact files that
83+
have not changed.
84+
85+
Use `--lint-all` to lint all files in the repo:
86+
87+
```shell
88+
dart ./tools/clang_tidy/bin/main.dart --lint-all
89+
```
90+
91+
> **⚠️ WARNING**: This will take a long time to run.
92+
93+
[^1]: Modified files are determined by a `git diff` command compared to `HEAD`.
94+
[^2]: Latest build is the last updated directory in `src/out/`.

‎tools/clang_tidy/lib/clang_tidy.dart‎

Lines changed: 10 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55
import 'dart:convert' show LineSplitter, jsonDecode;
66
import 'dart:io' as io show File, stderr, stdout;
77

8+
import 'package:engine_repo_tools/engine_repo_tools.dart';
89
import 'package:meta/meta.dart';
910
import 'package:path/path.dart' as path;
1011
import 'package:process/process.dart';
@@ -92,25 +93,29 @@ class ClangTidy {
9293
),
9394
_outSink = outSink ?? io.stdout,
9495
_errSink = errSink ?? io.stderr,
95-
_processManager = processManager;
96+
_processManager = processManager,
97+
_engine = null;
9698

9799
/// Builds an instance of [ClangTidy] from a command line.
98100
ClangTidy.fromCommandLine(
99101
List<String> args, {
102+
Engine? engine,
100103
StringSink? outSink,
101104
StringSink? errSink,
102105
ProcessManager processManager = const LocalProcessManager(),
103106
}) :
104-
options = Options.fromCommandLine(args, errSink: errSink),
107+
options = Options.fromCommandLine(args, errSink: errSink, engine: engine),
105108
_outSink = outSink ?? io.stdout,
106109
_errSink = errSink ?? io.stderr,
107-
_processManager = processManager;
110+
_processManager = processManager,
111+
_engine = engine;
108112

109113
/// The [Options] that specify how this [ClangTidy] operates.
110114
final Options options;
111115
final StringSink _outSink;
112116
final StringSink _errSink;
113117
final ProcessManager _processManager;
118+
final Engine? _engine;
114119

115120
late final DateTime _startTime;
116121

@@ -119,12 +124,12 @@ class ClangTidy {
119124
_startTime = DateTime.now();
120125

121126
if (options.help) {
122-
options.printUsage();
127+
options.printUsage(engine: _engine);
123128
return 0;
124129
}
125130

126131
if (options.errorMessage != null) {
127-
options.printUsage(message: options.errorMessage);
132+
options.printUsage(message: options.errorMessage, engine: _engine);
128133
return 1;
129134
}
130135

‎tools/clang_tidy/lib/src/options.dart‎

Lines changed: 89 additions & 74 deletions
Original file line numberDiff line numberDiff line change
@@ -5,11 +5,10 @@
55
import 'dart:io' as io show Directory, File, Platform, stderr;
66

77
import 'package:args/args.dart';
8+
import 'package:engine_repo_tools/engine_repo_tools.dart';
89
import 'package:path/path.dart' as path;
910

10-
// Path to root of the flutter/engine repository containing this script.
11-
final String _engineRoot = path.dirname(path.dirname(path.dirname(path.dirname(path.fromUri(io.Platform.script)))));
12-
11+
final Engine _engineRoot = Engine.findWithin(path.dirname(path.fromUri(io.Platform.script)));
1312

1413
/// Adds warnings as errors for only specific runs. This is helpful if migrating one platform at a time.
1514
String? _platformSpecificWarningsAsErrors(ArgResults options) {
@@ -91,8 +90,13 @@ class Options {
9190
factory Options.fromCommandLine(
9291
List<String> arguments, {
9392
StringSink? errSink,
93+
Engine? engine,
9494
}) {
95-
final ArgResults argResults = _argParser.parse(arguments);
95+
// TODO(matanlurey): Refactor this further, ideally moving all of the engine
96+
// resolution logic (i.e. --src-dir, --target-variant, --compile-commands)
97+
// into a separate method, and perhaps also adding `engine.output(name)`
98+
// to engine_repo_tools instead of path manipulation inlined below.
99+
final ArgResults argResults = _argParser(defaultEngine: engine).parse(arguments);
96100

97101
String? buildCommandsPath = argResults['compile-commands'] as String?;
98102

@@ -134,74 +138,85 @@ class Options {
134138
);
135139
}
136140

137-
static final ArgParser _argParser = ArgParser()
138-
..addFlag(
139-
'help',
140-
abbr: 'h',
141-
help: 'Print help.',
142-
negatable: false,
143-
)
144-
..addFlag(
145-
'lint-all',
146-
help: 'Lint all of the sources, regardless of FLUTTER_NOLINT.',
147-
)
148-
..addFlag(
149-
'lint-head',
150-
help: 'Lint files changed in the tip-of-tree commit.',
151-
)
152-
..addFlag(
153-
'fix',
154-
help: 'Apply suggested fixes.',
155-
)
156-
..addFlag(
157-
'verbose',
158-
help: 'Print verbose output.',
159-
)
160-
..addOption(
161-
'shard-id',
162-
help: 'When used with the shard-commands option this identifies which shard will execute.',
163-
valueHelp: 'A number less than 1 + the number of shard-commands arguments.',
164-
)
165-
..addOption(
166-
'shard-variants',
167-
help: 'Comma separated list of other targets, this invocation '
168-
'will only execute a subset of the intersection and the difference of the '
169-
'compile commands. Use with `shard-id`.'
170-
)
171-
..addOption(
172-
'compile-commands',
173-
help: 'Use the given path as the source of compile_commands.json. This '
174-
'file is created by running "tools/gn". Cannot be used with --target-variant '
175-
'or --src-dir.',
176-
)
177-
..addOption(
178-
'target-variant',
179-
aliases: <String>['variant'],
180-
help: 'The engine variant directory containing compile_commands.json '
181-
'created by running "tools/gn". Cannot be used with --compile-commands.',
182-
valueHelp: 'host_debug|android_debug_unopt|ios_debug|ios_debug_sim_unopt',
183-
defaultsTo: 'host_debug',
184-
)
185-
..addOption('mac-host-warnings-as-errors',
141+
static ArgParser _argParser({required Engine? defaultEngine}) {
142+
defaultEngine ??= _engineRoot;
143+
final io.Directory? latestBuild = defaultEngine.latestOutput()?.path;
144+
return ArgParser()
145+
..addFlag(
146+
'help',
147+
abbr: 'h',
148+
help: 'Print help.',
149+
negatable: false,
150+
)
151+
..addFlag(
152+
'lint-all',
153+
help: 'Lint all of the sources, regardless of FLUTTER_NOLINT.',
154+
)
155+
..addFlag(
156+
'lint-head',
157+
help: 'Lint files changed in the tip-of-tree commit.',
158+
)
159+
..addFlag(
160+
'fix',
161+
help: 'Apply suggested fixes.',
162+
)
163+
..addFlag(
164+
'verbose',
165+
help: 'Print verbose output.',
166+
)
167+
..addOption(
168+
'shard-id',
169+
help: 'When used with the shard-commands option this identifies which shard will execute.',
170+
valueHelp: 'A number less than 1 + the number of shard-commands arguments.',
171+
)
172+
..addOption(
173+
'shard-variants',
174+
help: 'Comma separated list of other targets, this invocation '
175+
'will only execute a subset of the intersection and the difference of the '
176+
'compile commands. Use with `shard-id`.'
177+
)
178+
..addOption(
179+
'compile-commands',
180+
help: 'Use the given path as the source of compile_commands.json. This '
181+
'file is created by running "tools/gn". Cannot be used with --target-variant '
182+
'or --src-dir.',
183+
)
184+
..addOption(
185+
'target-variant',
186+
aliases: <String>['variant'],
187+
help: 'The engine variant directory name containing compile_commands.json '
188+
'created by running "tools/gn".\n\nIf not provided, the default is '
189+
'the latest build in the engine defined by --src-dir (or the '
190+
'default path, see --src-dir for details).\n\n'
191+
'Cannot be used with --compile-commands.',
192+
valueHelp: 'host_debug|android_debug_unopt|ios_debug|ios_debug_sim_unopt',
193+
defaultsTo: latestBuild == null ? 'host_debug' : path.basename(latestBuild.path),
194+
)
195+
..addOption('mac-host-warnings-as-errors',
196+
help:
197+
'checks that will be treated as errors when running debug_host on mac.')
198+
..addOption(
199+
'src-dir',
186200
help:
187-
'checks that will be treated as errors when running debug_host on mac.')
188-
..addOption(
189-
'src-dir',
190-
help: 'Path to the engine src directory. Cannot be used with --compile-commands.',
191-
valueHelp: 'path/to/engine/src',
192-
defaultsTo: path.dirname(_engineRoot),
193-
)
194-
..addOption(
195-
'checks',
196-
help: 'Perform the given checks on the code. Defaults to the empty '
197-
'string, indicating all checks should be performed.',
198-
defaultsTo: '',
199-
)
200-
..addFlag(
201-
'enable-check-profile',
202-
help: 'Enable per-check timing profiles and print a report to stderr.',
203-
negatable: false,
204-
);
201+
'Path to the engine src directory.\n\n'
202+
'If not provided, the default is the engine root directory that '
203+
'contains the `clang_tidy` tool.\n\n'
204+
'Cannot be used with --compile-commands.',
205+
valueHelp: 'path/to/engine/src',
206+
defaultsTo: _engineRoot.srcDir.path,
207+
)
208+
..addOption(
209+
'checks',
210+
help: 'Perform the given checks on the code. Defaults to the empty '
211+
'string, indicating all checks should be performed.',
212+
defaultsTo: '',
213+
)
214+
..addFlag(
215+
'enable-check-profile',
216+
help: 'Enable per-check timing profiles and print a report to stderr.',
217+
negatable: false,
218+
);
219+
}
205220

206221
/// Whether to print a help message and exit.
207222
final bool help;
@@ -219,7 +234,7 @@ class Options {
219234
final int? shardId;
220235

221236
/// The root of the flutter/engine repository.
222-
final io.Directory repoPath = io.Directory(_engineRoot);
237+
final io.Directory repoPath = _engineRoot.flutterDir;
223238

224239
/// Argument sent as `warnings-as-errors` to clang-tidy.
225240
final String? warningsAsErrors;
@@ -249,15 +264,15 @@ class Options {
249264
final StringSink _errSink;
250265

251266
/// Print command usage with an additional message.
252-
void printUsage({String? message}) {
267+
void printUsage({String? message, required Engine? engine}) {
253268
if (message != null) {
254269
_errSink.writeln(message);
255270
}
256271
_errSink.writeln(
257272
'Usage: bin/main.dart [--help] [--lint-all] [--lint-head] [--fix] [--verbose] '
258273
'[--diff-branch] [--target-variant variant] [--src-dir path/to/engine/src]',
259274
);
260-
_errSink.writeln(_argParser.usage);
275+
_errSink.writeln(_argParser(defaultEngine: engine).usage);
261276
}
262277

263278
/// Command line argument validation.

‎tools/clang_tidy/pubspec.yaml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@ environment:
1818

1919
dependencies:
2020
args: any
21+
engine_repo_tools: any
2122
meta: any
2223
path: any
2324
process: any
@@ -38,6 +39,8 @@ dependency_overrides:
3839
path: ../../../third_party/dart/pkg/async_helper
3940
collection:
4041
path: ../../../third_party/dart/third_party/pkg/collection
42+
engine_repo_tools:
43+
path: ../pkg/engine_repo_tools
4144
expect:
4245
path: ../../../third_party/dart/pkg/expect
4346
file:

0 commit comments

Comments
 (0)