@@ -8,10 +8,10 @@ description: Learn about the experimental macros feature as it develops.
8
8
[ static meta-programming] [ motivation ] to the Dart language.
9
9
10
10
A Dart macro is a user-defineable piece of code that takes in other code as parameters
11
- and operates on it during compile time to create, modify, or add declarations.
11
+ and operates on it in real- time to create, modify, or add declarations.
12
12
13
13
You can think about the macro system in two parts: using macros and writing macros.
14
- This page covers each (at a high level, as *** the feature is still under development *** )
14
+ This page covers each (at a high level, as *** the feature is still in preview *** )
15
15
in the following sections:
16
16
17
17
- [ ** The ` JsonCodable ` macro** ] ( #the-jsoncodable-macro ) :
@@ -22,7 +22,8 @@ common issue of tedious JSON serialization in Dart.
22
22
- [ ** The macros feature in general** ] ( #the-macros-language-feature ) :
23
23
Why we're adding macros to Dart, motivating use cases,
24
24
benefits over existing code gen solutions,
25
- and a cursory overview of how writing macros works.
25
+ and a cursory overview of how writing macros will work in the future once
26
+ the feature is complete.
26
27
27
28
[ spec ] : {{site.repo.dart.lang}}/blob/main/working/macros/feature-specification.md
28
29
[ motivation ] : {{site.repo.dart.lang}}/language/blob/main/working/macros/motivation.md
@@ -31,6 +32,8 @@ and a cursory overview of how writing macros works.
31
32
32
33
::: important
33
34
The ` JsonCodable ` macro is not stable and currently behind an [ experiment flag] [ ] .
35
+ It only works with the [ dev channel] [ channel ] releases of Dart 3.5.0 and later.
36
+
34
37
Functionality is subject to change.
35
38
:::
36
39
@@ -41,37 +44,40 @@ and a `fromJson` deserialization constructor.
41
44
42
45
[ experiment flag ] : /tools/experiment-flags
43
46
[ `JsonCodable` ] : {{site.repo.dart.sdk}}/tree/main/pkg/json
47
+ [ channel ] : /get-dart/#release-channels
44
48
45
49
### Set up the experiment
46
50
47
- 1 . [ Add the package] [ ] to your pubspec and retrieve
51
+ 1 . Switch to the [ dev channel] [ channel ] and upgrade to at least 3.5.0.
52
+
53
+ 2 . [ Add the package] [ ] to your pubspec and retrieve
48
54
its dependencies.
49
- 2 . [ Add the experiment] [ ] to the ` analysis_options.yaml `
55
+ 3 . [ Add the experiment] [ ] to the ` analysis_options.yaml `
50
56
file at the root of your project:
51
57
52
58
``` yaml
53
59
analyzer :
54
60
enable-experiment :
55
61
- macros
56
62
` ` `
57
- 3 . Import it in the file you plan to use it:
63
+ 4 . Import it in the file you plan to use it:
58
64
59
- ` ` ` dart
60
- import 'package:json/json.dart';
61
- ```
65
+ ` ` ` dart
66
+ import 'package:json/json.dart';
67
+ ```
62
68
63
- 4 . Run your project with the experiment flag:
69
+ 5 . Run your project with the experiment flag:
64
70
65
- ``` console
66
- dart --enable-experiment=macros run bin/my_app.dart
67
- ```
71
+ ``` console
72
+ dart --enable-experiment=macros run bin/my_app.dart
73
+ ```
68
74
69
75
[ Add the package ] : /guides/packages
70
76
[ Add the experiment ] : /tools/experiment-flags#using-experiment-flags-with-the-dart-analyzer-command-line-and-ide
71
77
72
78
### Use the macro
73
79
74
- To use the ` JsonCodable ` macro, append the annotation to the class you want to serialize:
80
+ To use the ` JsonCodable ` macro, attach the annotation to the class you want to serialize:
75
81
76
82
``` dart
77
83
import 'package:json/json.dart';
@@ -108,7 +114,9 @@ void main() {
108
114
109
115
### View the generated code
110
116
111
- You can optionally view the generated code.
117
+ Sometimes it can be useful to view the generated code to better understand
118
+ how a macros works, or to inspect the details of what it offers.
119
+
112
120
Click on the "** Go to Augmentation** " link that appears under the annotation
113
121
in your IDE (supported in VSCode and IntelliJ)
114
122
to see how the macro generates ` toJson ` and ` fromJson ` .
@@ -149,11 +157,12 @@ treatment of null and generics, and more, check out [the README][].
149
157
150
158
Dart macros are a * static* metaprogramming, or code generation, solution.
151
159
Unlike * runtime* code generation solutions (like [ build_runner] [ ] ),
152
- macros are fully integrated into the Dart language and executed by the compiler.
160
+ macros are fully integrated into the Dart language
161
+ and executed automatically in the background by Dart tools.
153
162
This makes macros much more efficient than relying on an secondary tool:
154
163
155
164
- ** Nothing extra to run** ;
156
- simply call ` dart ` / ` flutter run <your app> ` and the macro builds with your code.
165
+ macros build in real-time as you write your code.
157
166
- ** No duplicated work** or constant recompiling hurting performance;
158
167
all the building and code generation happen directly in the compiler,
159
168
automatically.
@@ -166,12 +175,14 @@ This makes macros much more efficient than relying on an secondary tool:
166
175
And also far more efficient, and far less error prone, than manually
167
176
writing solutions to these types of problems yourself.
168
177
178
+ {% comment %}
169
179
Check out these examples showing the same JSON serialization
170
180
implemented three different ways:
171
181
172
182
- Using the [ ` JsonCodable ` macro] [ ] .
173
183
- Using the [ ` json_serializable ` code gen package] [ ] .
174
184
- Manually, [ with ` dart:convert ` ] [ ] .
185
+ {% endcomment %}
175
186
176
187
[ build_runner ] : /tools/build_runner
177
188
[ `JsonCodable` macro ] : https://github.com/mit-mit/sandbox/blob/main/explorations/json/dart_jsoncodable/bin/main.dart
@@ -228,7 +239,6 @@ would implement the `ClassDeclarationsMacro` interface:
228
239
macro class MyMacro implements ClassDeclarationsMacro {
229
240
const MyMacro();
230
241
231
-
232
242
// ...
233
243
}
234
244
```
0 commit comments