From e69c74d1b15e53115f8bb7adc4d20a15034b604d Mon Sep 17 00:00:00 2001
From: Daco Harkes <dacoharkes@google.com>
Date: Thu, 28 Nov 2024 12:26:26 +0100
Subject: [PATCH] [native_assets_cli] Document exit code behavior (#1762)

Closes: https://github.com/dart-lang/native/issues/33

The behavior is already tested by pkgs/native_assets_builder/test/build_runner/build_runner_build_output_format_test.dart.
---
 pkgs/native_assets_cli/lib/src/api/build.dart | 7 +++++++
 pkgs/native_assets_cli/lib/src/api/link.dart  | 6 ++++++
 2 files changed, 13 insertions(+)

diff --git a/pkgs/native_assets_cli/lib/src/api/build.dart b/pkgs/native_assets_cli/lib/src/api/build.dart
index 5534773ec..c033a8c58 100644
--- a/pkgs/native_assets_cli/lib/src/api/build.dart
+++ b/pkgs/native_assets_cli/lib/src/api/build.dart
@@ -11,6 +11,8 @@ import '../validation.dart';
 
 /// Runs a native assets build.
 ///
+/// Meant to be used in build hooks (`hook/build.dart`).
+///
 /// Can build native assets which are not already available, or expose existing
 /// files. Each individual asset is assigned a unique asset ID.
 ///
@@ -87,6 +89,11 @@ import '../validation.dart';
 ///   });
 /// }
 /// ```
+///
+/// If the [builder] fails, it must `throw`. Build hooks are guaranteed to be
+/// invoked with a process invocation and should return a non-zero exit code on
+/// failure. Throwing will lead to an uncaught exception, causing a non-zero
+/// exit code.
 Future<void> build(
   List<String> arguments,
   Future<void> Function(BuildConfig config, BuildOutputBuilder output) builder,
diff --git a/pkgs/native_assets_cli/lib/src/api/link.dart b/pkgs/native_assets_cli/lib/src/api/link.dart
index 975ec280b..fe3d445bf 100644
--- a/pkgs/native_assets_cli/lib/src/api/link.dart
+++ b/pkgs/native_assets_cli/lib/src/api/link.dart
@@ -11,6 +11,8 @@ import '../validation.dart';
 
 /// Runs a native assets link.
 ///
+/// Meant to be used in link hooks (`hook/link.dart`).
+///
 /// Can link native assets which are not already available, or expose existing
 /// files. Each individual asset is assigned a unique asset ID.
 ///
@@ -30,6 +32,10 @@ import '../validation.dart';
 ///   });
 /// }
 /// ```
+/// If the [linker] fails, it must `throw`. Link hooks are guaranteed to be
+/// invoked with a process invocation and should return a non-zero exit code on
+/// failure. Throwing will lead to an uncaught exception, causing a non-zero
+/// exit code.
 Future<void> link(
   List<String> arguments,
   Future<void> Function(LinkConfig config, LinkOutputBuilder output) linker,