Document that --define requires string values to be json encoded when containing certain characters

[schultek]

I ran into a weird issue where it seems that when providing build options like this:

dart run build_runner build --define=some_package:some_builder=some_option="Priority 6"

on Windows the value of that option in the builder includes the " quotes as part of the String.

---

• Dart SDK version: 3.10.4 (stable) (Tue Dec 9 00:01:55 2025 -0800) on "windows_x64"
• build_runner 2.10.4

[schultek]

This was actually a bug on my side. I looked into how options are parsed and it's using jsonDecode on the value, which fails since I didn't escape the \ characters in windows file paths.

I fixed it by wrapping all option values in jsonEncode.

---

It would be nice to have this documented somewhere that is is required to properly escape / json encode values, maybe here: https://pub.dev/packages/build_config#how-is-the-configuration-for-a-builder-resolved