@@ -82,6 +82,66 @@ import '../validation.dart';
8282/// guaranteed to be invoked with a process invocation and should return a
8383/// non-zero exit code on failure. Throwing will lead to an uncaught exception,
8484/// causing a non-zero exit code.
85+ ///
86+ /// ## Debugging
87+ ///
88+ /// When a build hook doesn't work as expected, you can investigate the
89+ /// intermediate files generated by the Dart and Flutter SDK build process.
90+ ///
91+ /// The most important files for debugging are located in a subdirectory
92+ /// specific to your hook's execution. The path is of the form
93+ /// `.dart_tool/hooks_runner/<package_name>/<some_hash>/` , where
94+ /// `<package_name>` is the name of the package containing the hook. Inside, you
95+ /// will find:
96+ ///
97+ /// * `input.json` : The configuration and data passed into your build hook.
98+ /// * `output.json` : The JSON data that your build hook produced.
99+ /// * `stdout.txt` : Any standard output from your build hook.
100+ /// * `stderr.txt` : Any error messages or exceptions.
101+ ///
102+ /// When you run a build, hooks for all dependencies are executed, so you might
103+ /// see multiple package directories.
104+ ///
105+ /// The `<some_hash>` is a checksum of the [BuildConfig] in the `input.json` . If
106+ /// you are unsure which hash directory to inspect within your package's hook
107+ /// directory, you can delete the `.dart_tool/hooks_runner/<package_name>/`
108+ /// directory and re-run the command that failed. The newly created directory
109+ /// will be for the latest invocation.
110+ ///
111+ /// You can step through your code with a debugger by running the build hook
112+ /// from its source file and providing the `input.json` via the `--config` flag:
113+ ///
114+ /// ```sh
115+ /// dart run hook/build.dart --config .dart_tool/hooks_runner/<package_name>/<some_hash>/input.json
116+ /// ```
117+ ///
118+ /// To debug in VS Code, you can create a `launch.json` file in a `.vscode`
119+ /// directory in your project root. This allows you to run your hook with a
120+ /// debugger attached.
121+ ///
122+ /// Here is an example configuration:
123+ ///
124+ /// ```json
125+ /// {
126+ /// "version": "0.2.0",
127+ /// "configurations": [
128+ /// {
129+ /// "name": "Debug Build Hook",
130+ /// "type": "dart",
131+ /// "request": "launch",
132+ /// "program": "hook/build.dart",
133+ /// "args": [
134+ /// "--config",
135+ /// ".dart_tool/hooks_runner/your_package_name/some_hash/input.json"
136+ /// ]
137+ /// }
138+ /// ]
139+ /// }
140+ /// ```
141+ ///
142+ /// Again, make sure to replace `your_package_name` , and `some_hash` with the
143+ /// actual paths from your project. After setting this up, you can run the
144+ /// "Debug Build Hook" configuration from the "Run and Debug" view in VS Code.
85145Future <void > build (
86146 List <String > arguments,
87147 Future <void > Function (BuildInput input, BuildOutputBuilder output) builder,
@@ -122,8 +182,8 @@ Future<void> build(
122182
123183/// Links assets in a `hook/link.dart` .
124184///
125- /// If a link hook is defined (`hook/link.dart` ) then `link` must be called
126- /// by that hook, to write the [BuildInput.outputFile] , even if the [linker]
185+ /// If a link hook is defined (`hook/link.dart` ) then `link` must be called by
186+ /// that hook, to write the [BuildInput.outputFile] , even if the [linker]
127187/// function has no work to do.
128188///
129189/// Can link native assets which are not already available, or expose existing
@@ -152,6 +212,66 @@ Future<void> build(
152212/// guaranteed to be invoked with a process invocation and should return a
153213/// non-zero exit code on failure. Throwing will lead to an uncaught exception,
154214/// causing a non-zero exit code.
215+ ///
216+ /// ## Debugging
217+ ///
218+ /// When a link hook doesn't work as expected, you can investigate the
219+ /// intermediate files generated by the Dart and Flutter SDK build process.
220+ ///
221+ /// The most important files for debugging are located in a subdirectory
222+ /// specific to your hook's execution. The path is of the form
223+ /// `.dart_tool/hooks_runner/<package_name>/<some_hash>/` , where
224+ /// `<package_name>` is the name of the package containing the hook. Inside, you
225+ /// will find:
226+ ///
227+ /// * `input.json` : The configuration and data passed into your link hook.
228+ /// * `output.json` : The JSON data that your link hook produced.
229+ /// * `stdout.txt` : Any standard output from your link hook.
230+ /// * `stderr.txt` : Any error messages or exceptions.
231+ ///
232+ /// When you run a build, hooks for all dependencies are executed, so you might
233+ /// see multiple package directories.
234+ ///
235+ /// The `<some_hash>` is a checksum of the [LinkConfig] in the `input.json` . If
236+ /// you are unsure which hash directory to inspect within your package's hook
237+ /// directory, you can delete the `.dart_tool/hooks_runner/<package_name>/`
238+ /// directory and re-run the command that failed. The newly created directory
239+ /// will be for the latest invocation.
240+ ///
241+ /// You can step through your code with a debugger by running the link hook from
242+ /// its source file and providing the `input.json` via the `--config` flag:
243+ ///
244+ /// ```sh
245+ /// dart run hook/link.dart --config .dart_tool/hooks_runner/<package_name>/<some_hash>/input.json
246+ /// ```
247+ ///
248+ /// To debug in VS Code, you can create a `launch.json` file in a `.vscode`
249+ /// directory in your project root. This allows you to run your hook with a
250+ /// debugger attached.
251+ ///
252+ /// Here is an example configuration:
253+ ///
254+ /// ```json
255+ /// {
256+ /// "version": "0.2.0",
257+ /// "configurations": [
258+ /// {
259+ /// "name": "Debug Link Hook",
260+ /// "type": "dart",
261+ /// "request": "launch",
262+ /// "program": "hook/link.dart",
263+ /// "args": [
264+ /// "--config",
265+ /// ".dart_tool/hooks_runner/your_package_name/some_hash/input.json"
266+ /// ]
267+ /// }
268+ /// ]
269+ /// }
270+ /// ```
271+ ///
272+ /// Again, make sure to replace `your_package_name` , and `some_hash` with the
273+ /// actual paths from your project. After setting this up, you can run the
274+ /// "Debug Link Hook" configuration from the "Run and Debug" view in VS Code.
155275Future <void > link (
156276 List <String > arguments,
157277 Future <void > Function (LinkInput input, LinkOutputBuilder output) linker,
0 commit comments