Skip to content

Commit c26f756

Browse files
authored
[record_use] Record use cases (dart-lang#2976)
Document all the `package:record_use` use cases and what features they would need from `package:record_use` and the compiler implementations populating the recorded use file.
1 parent 4fe954c commit c26f756

6 files changed

Lines changed: 367 additions & 0 deletions

File tree

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# Use cases for `package:record_use`
2+
3+
This directory contains documents describing various use cases for the
4+
`record_use` package. Each document outlines a specific scenario where the
5+
package can be used to gather information about code for purposes like
6+
tree-shaking, code generation, or analysis.
7+
8+
## Use Cases
9+
10+
- [Icon Font Tree-Shaking](./icon_data.md): Reducing the size of icon fonts in
11+
Flutter applications by tree-shaking unused icons.
12+
- [ICU4X Data Tree-Shaking](./icu4x.md): Tree-shaking native code in the `icu4x`
13+
library to reduce binary size.
14+
- [Jaspr Widget Trees](./jaspr.md): Extracting information from Jaspr widget
15+
trees to generate CSS, similar to Tailwind CSS.
16+
- [JNIgen ProGuard Rules](./jnigen.md): Generating ProGuard rules for
17+
Java/Kotlin code used via `jnigen` to enable code shrinking.
18+
- [Message Translation Tree-Shaking](./messages.md): Shrinking translation
19+
files by removing unused messages.
Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
# Icon data record_use
2+
3+
The goal here is to be able to tree-shake icon fonts in Flutter. Currently, this
4+
is a custom-built solution in Flutter. This should be the capability of a
5+
package.
6+
7+
Dart API and use:
8+
9+
```dart
10+
class IconData {
11+
const IconData(
12+
this.codePoint, {
13+
this.fontFamily,
14+
this.fontPackage,
15+
this.matchTextDirection = false,
16+
this.fontFamilyFallback,
17+
});
18+
}
19+
```
20+
21+
```dart
22+
abstract final class GalleryIcons {
23+
static const IconData tooltip = IconData(0xe900, fontFamily: 'GalleryIcons');
24+
static const IconData text_fields_alt = IconData(0xe901, fontFamily: 'GalleryIcons');
25+
// ...
26+
}
27+
```
28+
29+
## Information needed for tree-shaking
30+
31+
Const instances inside Dart code (const instances inside annotations are not
32+
reachable at runtime, and thus can never be used).
33+
34+
Note that `const` constructors can be called in non-`const` contexts. To
35+
reliably track all uses, we need to record both `const` instances and all calls
36+
to `const` constructors, regardless of whether the call site is `const`.
37+
38+
* https://github.com/dart-lang/native/issues/2911
39+
40+
Moreover, we need the arguments to the const constructor calls and the fields of
41+
the const instances.
42+
43+
### Static getters won't work.
44+
45+
Since this API is already in active use, we cannot simply change the API to
46+
static getters, as that would prevent const:
47+
48+
```dart
49+
abstract final class GalleryIcons {
50+
static IconData get tooltip => IconData(0xe900, fontFamily: 'GalleryIcons');
51+
static IconData get text_fields_alt => IconData(0xe901, fontFamily: 'GalleryIcons');
52+
// ...
53+
}
54+
```
55+
56+
An API with static getters (disallowing const instances) would enable two other
57+
possiblities of recording uses.
58+
59+
1. Record each static getter in `GalleryIcons` individually, no arguments.
60+
(Static calls we are aiming for in v1.0)
61+
2. Record the non-const constructor of `IconData` with the const argument values.
62+
This requires:
63+
64+
* https://github.com/dart-lang/native/issues/2907
65+
66+
Flutter actively makes everything const, so forcing this API to be non-const is
67+
a no-go.
68+
69+
## Links
70+
71+
* https://api.flutter.dev/flutter/cupertino/CupertinoIcons-class.html
72+
* https://github.com/flutter/flutter/pull/174860
Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
# Icu4x record_use
2+
3+
This is a rust library, and the goal is to tree-shake native code if symbols are
4+
not reachable from Dart code to cut down binary size from ~40MB to a couple of
5+
MBs.
6+
7+
## Information needed for tree-shaking
8+
9+
The native symbols that are reachable:
10+
11+
```dart
12+
@ffi.Native<ffi.Pointer<ffi.Void> Function(ffi.Size, ffi.Size)>(
13+
symbol: 'diplomat_alloc',
14+
isLeaf: true,
15+
)
16+
external ffi.Pointer<ffi.Void> _diplomat_alloc(int len, int align);
17+
```
18+
([[source](https://github.com/unicode-org/icu4x/blob/e5a29a7d591157e8906bbd3f00021f164031f7cd/ffi/dart/lib/src/bindings/lib.g.dart#L237C1-L237C68))
19+
20+
21+
The link hook needs to know `diplomat_alloc` is reachable or not.
22+
23+
This can be achieved by knowing whether the static function `_diplomat_alloc` is reachable.
24+
25+
### Mapping Dart identifiers to native identifiers
26+
27+
The file containing the external static functions is a generated file.
28+
29+
The link hook could import a generated file that contains the mapping:
30+
31+
```dart
32+
const dartStaticCallToNativeSymbol = {
33+
'diplomat_alloc': '_diplomat_alloc',
34+
// ...
35+
};
36+
```
37+
38+
## Links
39+
40+
* https://pub.dev/packages/icu4x
Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
# Jaspr Component Trees record_use
2+
3+
Jaspr is a web framework. The goal is to generate a minimal CSS file containing
4+
only the styles used in a Jaspr application. This is achieved by using
5+
`record_use` to extract information about which components are used and what
6+
styles they apply. This enables a "Tailwind-like" experience where developers
7+
use style utilities and the final CSS is tree-shaken.
8+
9+
For example, a `Column` component might have styling options passed to its
10+
constructor:
11+
12+
```dart
13+
class Column extends Component {
14+
@RecordUse()
15+
const Column({this.spacing = 0, this.crossAxisAlignment = 'start'});
16+
17+
@override
18+
Iterable<Component> build(BuildContext context) {
19+
// ...
20+
}
21+
}
22+
```
23+
24+
When this component is used, we want to record the constructor call, including
25+
the arguments:
26+
27+
```dart
28+
class MyComponent extends Component {
29+
@override
30+
Iterable<Component> build(BuildContext context) {
31+
return [
32+
Column(spacing: 42, crossAxisAlignment: 'center'),
33+
];
34+
}
35+
}
36+
```
37+
38+
A link-time hook can then process all recorded uses of `Column`. From the
39+
`spacing` and `crossAxisAlignment` arguments, it can generate the required CSS
40+
rules and emit them into a single CSS file for the application:
41+
42+
```css
43+
.column-spacing-42 {
44+
padding: 42px;
45+
}
46+
47+
.column-cross-axis-center {
48+
align-items: center;
49+
}
50+
```
51+
52+
## Information required for CSS generation
53+
54+
To generate the CSS, the link hook needs to know about all constructor calls to
55+
components that are annotated with `@RecordUse`.
56+
57+
* **`const` constructor calls**:
58+
These are the most common in component trees. We need to record the static
59+
calls to these `const` constructors and the values of their arguments.
60+
See: https://github.com/dart-lang/native/issues/2911
61+
62+
* **`const` instances**:
63+
`const` instances of components are also common. The hook needs to be aware
64+
of these instances and their field values.
65+
(We are _not_ interested in any of these const instances occurring in
66+
annotations, such as https://github.com/dart-lang/native/issues/2719.)
67+
68+
* **Non-`const` constructor calls**:
69+
Component trees are not always `const`. To ensure all styles are captured, we
70+
also need to record non-`const` constructor calls.
71+
See: https://github.com/dart-lang/native/issues/2907
72+
73+
By collecting this information, a tool can build a complete picture of which
74+
styling primitives are used in an application and generate an optimized CSS file.
75+
76+
## Links
77+
78+
* https://github.com/schultek/jaspr
79+
* https://github.com/schultek/universal_widgets
Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
# JNIgen record_use
2+
3+
JNIgen generates Dart bindings to Java/Kotlin code. After tree-shaking the generated
4+
Dart code not all Java/Kotlin code is reachable. To tree-shake the unreachable
5+
Java/Kotlin code we want to generate ProGuard rules that list all the
6+
reachable Java/Kotlin classes, methods, and fields.
7+
8+
## Information needed for tree-shaking
9+
10+
### 1. Which classes are possibly instantiated.
11+
12+
```dart
13+
class PDDocument extends jni$_.JObject {
14+
PDDocument.fromReference(
15+
jni$_.JReference reference,
16+
);
17+
18+
factory PDDocument() {
19+
return PDDocument.fromReference(
20+
_new$(_class.reference.pointer, _id_new$ as jni$_.JMethodIDPtr)
21+
.reference);
22+
}
23+
24+
factory PDDocument.new$1(
25+
jni$_.JObject? memUsageSetting,
26+
);
27+
}
28+
```
29+
30+
This requires tracking non-const (factory) constructor calls.
31+
32+
* https://github.com/dart-lang/native/issues/2907
33+
34+
Because the `JObjects` are wrappers around native pointers, none of the JNIgen
35+
generated classes will ever have const constructors.
36+
37+
### 2. Which methods, getters and setters are reachable.
38+
39+
```dart
40+
class PDDocument extends jni$_.JObject {
41+
void addPage(
42+
jni$_.JObject? page,
43+
)
44+
}
45+
```
46+
47+
This requires tracking instance calls, or generating a static call inside the
48+
instance call. JNIgen already generates a static field (with a static getter)
49+
that could be annotated to record a static call:
50+
51+
```dart
52+
class PDDocument extends jni$_.JObject {
53+
static final _addPage = jni$_.ProtectedJniExtensions.lookup<
54+
jni$_.NativeFunction<
55+
jni$_.JThrowablePtr Function(
56+
jni$_.Pointer<jni$_.Void>,
57+
jni$_.JMethodIDPtr,
58+
jni$_.VarArgs<(jni$_.Pointer<jni$_.Void>,)>)>>(
59+
'globalEnv_CallVoidMethod')
60+
.asFunction<
61+
jni$_.JThrowablePtr Function(jni$_.Pointer<jni$_.Void>,
62+
jni$_.JMethodIDPtr, jni$_.Pointer<jni$_.Void>)>();
63+
64+
void addPage(
65+
final _$page = page?.reference ?? jni$_.jNullReference;
66+
_addPage(reference.pointer, _id_addPage as jni$_.JMethodIDPtr,
67+
_$page.pointer)
68+
.check();
69+
)
70+
}
71+
```
72+
73+
Java fields in JNIgen generated code are Dart getters and setters.
74+
75+
* https://github.com/dart-lang/native/issues/2906
76+
77+
### 3. Mapping Dart identifiers to native identifiers
78+
79+
For each class-use and method/field-use the link hook in JNIgen needs to know
80+
the original Java/Kotlin unique name.
81+
82+
Since JNIgen is already a code generator, this can be achieved by generating a
83+
file that maps Dart identifiers to Java identifiers:
84+
85+
```dart
86+
const dartToJava = {
87+
DartMethodIdentifer(
88+
importUrl: 'package:foo/foo.dart',
89+
name: 'Bar',
90+
methodName: 'baz',
91+
) : JavaMethodIdentifier(
92+
qualifiedImport: 'org.foo.foo',
93+
name: 'Bar',
94+
methodName: 'baz',
95+
),
96+
// ...
97+
}
98+
```
99+
100+
## Links
101+
102+
* https://pub.dev/packages/jnigen
Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
# messages record_use
2+
3+
The goal of this package is to provide translation. The goal of using link hooks
4+
is to be able to shrink the translation files based on use.
5+
6+
```dart
7+
class MessageTable {
8+
@RecordUse()
9+
static String lookup(int id, String appId) => // ...
10+
11+
@RecordUse()
12+
static String evaluate(int id, String appId, List<dynamic> args) =>
13+
// ...
14+
}
15+
```
16+
17+
```dart
18+
String translateFoo() => lookup(/*int id of foo*/0, 'baz');
19+
20+
String translateBar(String name) => evaluate(/*int id of foo*/0, 'baz', name);
21+
```
22+
23+
The calls to the translate methods are almost always generated. Either by a
24+
transformer as a compiler plugin or by an external code generator that generates
25+
the API for the translations.
26+
27+
If a transformer is used, the pre-transform code looks something like:
28+
29+
```dart
30+
class Intl {
31+
static String message(String messageText,
32+
{String? desc = '',
33+
Map<String, Object>? examples,
34+
String? locale,
35+
String? name,
36+
List<Object>? args,
37+
String? meaning,
38+
bool? skip});
39+
}
40+
```
41+
42+
An `id` is generated based on the calls to `message` and the message calls are
43+
transformed to the `lookup` and `evaluate` calls.
44+
45+
This transformation step might not be needed if we can reconstruct the
46+
id-generation in the link hook.
47+
48+
## Information needed for tree-shaking
49+
50+
The uses of the static methods, and their const argument values.
51+
52+
## Links
53+
54+
* https://pub.dev/packages/intl
55+
* https://pub.dev/packages/messages

0 commit comments

Comments
 (0)