Skip to content

Commit efea991

Browse files
gaaclarkegaaclarke
authored
[pigeon] Added a contributor's guide. (#324)
1 parent 6daf2b0 commit efea991

5 files changed

Lines changed: 141 additions & 3 deletions

File tree

‎packages/pigeon/CONTRIBUTING.md‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
# Pigeon Contributor's Guide
2+
3+
## Description
4+
5+
Pigeon is a code generation tool that adds type safety to Flutter’s Platform
6+
Channels. This document serves as an overview of how it functions to help
7+
people who would like to contribute to the project.
8+
9+
## State Diagram
10+
11+
Pigeon generates a temporary file in its _LaunchIsolate_, the isolate that is
12+
spawned to run `main()`, then launches another isolate, _PigeonIsolate_, that
13+
uses `dart:mirrors` to parse the generated file, creating an
14+
[AST](https://en.wikipedia.org/wiki/Abstract_syntax_tree), then running code
15+
generators with that AST.
16+
17+
![State Diagram](./docs/pigeon_state.png)
18+
19+
## Source Index
20+
21+
* [ast.dart](./lib/ast.dart) - The data structure for representing the Abstract Syntax Tree.
22+
* [dart_generator.dart](./lib/dart_generator.dart) - The Dart code generator.
23+
* [java_generator.dart](./lib/java_generator.dart) - The Java code generator.
24+
* [objc_generator.dart](./lib/objc_generator.dart) - The Objective-C code
25+
generator (header and source files).
26+
* [generator_tools.dart](./lib/generator_tools.dart) - Shared code between generators.
27+
* [pigeon_cl.dart](./lib/pigeon_cl.dart) - The top-level function executed by
28+
the command line tool in [bin/][./bin].
29+
* [pigeon_lib.dart](./lib/pigeon_lib.dart) - The top-level function for the
30+
PigeonIsolate and the AST generation code.
31+
* [pigeon.dart](./lib/pigeon.dart) - A file of exported modules, the intended
32+
import for users of Pigeon.
33+
34+
## Testing Overview
35+
36+
Pigeon has 3 types of tests, you'll find them all in [run_tests.sh](./run_tests.sh).
37+
38+
* Unit tests - These are the fastest tests that are just typical unit tests,
39+
they may be generating code and checking it against a regular expression to
40+
see if it's correct. Example:
41+
[dart_generator_test.dart](./test/dart_generator_test.dart)
42+
* Compilation tests - These tests generate code, then attempt to compile that
43+
code. These are tests are much slower than unit tests, but not as slow as
44+
integration tests. These tests are typically run against the Pigeon files in
45+
[pigeons](./pigeons).
46+
* Integration tests - These tests generate code, then compile the generated
47+
code, then execute the generated code. It can be thought of as unit-tests run
48+
against the generated code. Examples: [platform_tests](./platform_tests)
49+
50+
## Generated Source Code Example
51+
52+
This is what the temporary generated code that the _PigeonIsolate_ executes
53+
looks like (see [State Diagram](#state-diagram)):
54+
55+
```dart
56+
@dart = 2.12
57+
import 'path/to/supplied/pigeon/file.dart'
58+
import 'dart:io';
59+
import 'dart:isolate';
60+
import 'package:pigeon/pigeon_lib.dart';
61+
void main(List<String> args, SendPort sendPort) async {
62+
sendPort.send(await Pigeon.run(args));
63+
}
64+
```
65+
66+
This is how `dart:mirrors` gets access to the supplied Pigeon file.
67+
68+
## Imminent Plans
69+
70+
* Migrate to Dart Analyzer for AST generation ([issue
71+
78818](https://github.com/flutter/flutter/issues/78818)) - We might have
72+
reached the limitations of using dart:mirrors for parsing the Dart files.
73+
That package has been deprecated and it doesn't support null-safe annotations.
74+
We should migrate to using the Dart Analyzer as the front-end parser.
75+
* Integration tests for Android - Right now we have integration tests for Dart
76+
and iOS. We should add some for Android. It is limiting the speed at which
77+
we can bring in external contributor's contributions to Android / Java.

‎packages/pigeon/docs/pigeon_state.png‎

106 KB
Loading

‎packages/pigeon/docs/pigeon_state.puml‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
@startuml
2+
3+
[*] -> LaunchIsolate
4+
5+
state LaunchIsolate {
6+
[*] --> ParseCommandLineArguments
7+
ParseCommandLineArguments --> WriteTemporarySourceCode
8+
WriteTemporarySourceCode --> SpawnPigeonIsolate
9+
SpawnPigeonIsolate --> WaitForPigeonIsolate
10+
WaitForPigeonIsolate --> [*]
11+
}
12+
13+
LaunchIsolate -> [*]
14+
15+
state PigeonIsolate {
16+
[*] --> ParseCommandLineArguments2
17+
ParseCommandLineArguments2 --> PrintUsage
18+
PrintUsage --> [*]
19+
ParseCommandLineArguments2 --> ExecuteConfigurePigeon
20+
ExecuteConfigurePigeon --> GenerateAST
21+
GenerateAST --> RunGenerators
22+
RunGenerators --> PrintErrors
23+
PrintErrors --> ReturnStatusCode
24+
ReturnStatusCode --> [*]
25+
26+
state GenerateAST {
27+
[*] --> CollectAnnotatedClasses
28+
CollectAnnotatedClasses --> CollectAnnotatedClassesDependencies
29+
CollectAnnotatedClassesDependencies --> BuildAST
30+
BuildAST --> [*]
31+
}
32+
33+
state RunGenerators {
34+
state DartTestGeneratorFork <<fork>>
35+
state DartTestGeneratorJoin <<join>>
36+
[*] --> DartTestGeneratorFork
37+
DartTestGeneratorFork --> DartTestGeneratorJoin
38+
DartTestGeneratorFork --> DartTestGenerator
39+
DartTestGenerator --> DartTestGeneratorJoin
40+
DartTestGeneratorJoin --> [*]
41+
||
42+
state DartGeneratorFork <<fork>>
43+
state DartGeneratorJoin <<join>>
44+
[*] --> DartGeneratorFork
45+
DartGeneratorFork --> DartGeneratorJoin
46+
DartGeneratorFork --> DartGenerator
47+
DartGenerator --> DartGeneratorJoin
48+
DartGeneratorJoin --> [*]
49+
||
50+
state JavaGeneratorFork <<fork>>
51+
state JavaGeneratorJoin <<join>>
52+
[*] --> JavaGeneratorFork
53+
JavaGeneratorFork --> JavaGeneratorJoin
54+
JavaGeneratorFork --> JavaGenerator
55+
JavaGenerator --> JavaGeneratorJoin
56+
JavaGeneratorJoin --> [*]
57+
}
58+
}
59+
60+
@enduml

‎packages/pigeon/lib/dart_generator.dart‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -137,8 +137,8 @@ void _writeFlutterApi(
137137
final String emptyReturnStatement = isMockHandler
138138
? 'return <Object$nullTag, Object$nullTag>{};'
139139
: func.returnType == 'void'
140-
? 'return;'
141-
: 'return null;';
140+
? 'return;'
141+
: 'return null;';
142142
String call;
143143
if (argType == 'void') {
144144
indent.writeln('// ignore message');

‎packages/pigeon/run_tests.sh‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@ set -ex
1111
JAVA_LINTER=checkstyle-8.41-all.jar
1212
JAVA_FORMATTER=google-java-format-1.3-all-deps.jar
1313
GOOGLE_CHECKS=google_checks.xml
14+
GOOGLE_CHECKS_VERSION=7190c47ca5515ad8cb827bc4065ae7664d2766c1
1415
JAVA_ERROR_PRONE=error_prone_core-2.5.1-with-dependencies.jar
1516
DATAFLOW_SHADED=dataflow-shaded-3.7.1.jar
1617
JFORMAT_STRING=jFormatString-3.0.0.jar
@@ -129,7 +130,7 @@ if [ ! -f "ci/$JAVA_FORMATTER" ]; then
129130
curl -L https://github.com/google/google-java-format/releases/download/google-java-format-1.3/$JAVA_FORMATTER > "ci/$JAVA_FORMATTER"
130131
fi
131132
if [ ! -f "ci/$GOOGLE_CHECKS" ]; then
132-
curl -L https://raw.githubusercontent.com/checkstyle/checkstyle/master/src/main/resources/$GOOGLE_CHECKS > "ci/$GOOGLE_CHECKS"
133+
curl -L https://raw.githubusercontent.com/checkstyle/checkstyle/$GOOGLE_CHECKS_VERSION/src/main/resources/$GOOGLE_CHECKS > "ci/$GOOGLE_CHECKS"
133134
fi
134135
if [ ! -f "ci/$JAVA_ERROR_PRONE" ]; then
135136
curl https://repo1.maven.org/maven2/com/google/errorprone/error_prone_core/2.5.1/$JAVA_ERROR_PRONE > "ci/$JAVA_ERROR_PRONE"

0 commit comments

Comments
 (0)