hooks library
Build-hook integration for packages that ship prebuilt native libraries.
Import this library in your hook/build.dart to use
PrebuiltCodeAssetBuilder, NativeProjectBuilder, or the convenience
nativePrebuiltBuild function.
This library re-exports the core package (native_prebuilt.dart),
the build orchestration layer (build.dart), and the builder
utilities (PrebuiltCodeAssetBuilder, NativeProjectBuilder).
Classes
- AndroidBuildTarget
- Platform-specific build configuration for Android.
- AndroidNdkToolchain
- Android NDK toolchain implementation.
- AppleBuildTarget
- Platform-specific build configuration for Apple platforms.
- AppleSdkToolchain
- Apple SDK toolchain implementation.
- ApplyPatches
- Applies one or more patch files to the source directory.
- Architecture
- A hardware architecture which the Dart VM can run on.
- ArchiveEntry
- Describes an entry within a tar/gz archive.
- ArchiveReader
-
Reads
.tar.gzarchives and extracts selected entries. - ArchiveSelectionContext
- Context for selecting an entry from an archive.
- ArchiveSource
- Source code downloaded as an immutable archive.
- ArchiveSourceProvider
- Resolves ArchiveSource specifications.
- ArtifactCache
- Backwards-compatible facade around ArtifactInstaller.
- ArtifactInstaller
- Installs a prebuilt artifact into a cache directory.
- ArtifactPayload
- Describes the expected native binary payload within an archive.
- AtomicFile
- Utility for writing files atomically using a temporary file + rename.
- BuildCache
- Persistent build cache for step-level caching.
- BuildStepConfig
- Base type for all build step configurations.
- BuiltNativeArtifact
- A built native artifact ready for packaging.
- CacheLock
- A best-effort cross-process file lock for cache population.
- CallbackSourceBuilder
- A callback-based source builder for one-off build logic.
- CmakeBuildStep
- CMake build step for native libraries.
- CmakeBuildStepConfig
- CmakeConfigureStep
- CMake configure step.
- CmakeConfigureStepConfig
- CommandStep
- Generic command execution step.
- CommandStepConfig
- CopyStep
- Copy files or directories.
- CopyStepConfig
- DefaultArtifactInstaller
- Default implementation for downloading, verifying, extracting, and validating prebuilt artifacts.
- DownloadArchiveStep
- Download and extract an archive step.
- DownloadArchiveStepConfig
- DynamicLibraryPayload
-
A shared/dynamic library (
.so,.dylib,.dll). - ExportArtifactStep
- Artifact export step for native builds.
- ExportArtifactStepConfig
- GitApplyPatchStep
- Apply a git patch.
- GitApplyPatchStepConfig
- GitCheckoutStep
- Git checkout step.
- GitCheckoutStepConfig
- GitHubReleaseSource
- Artifacts are hosted as GitHub Release assets.
- GitLabReleaseSource
- Artifacts are hosted as GitLab release assets.
- GitSource
- Source code fetched from a Git repository.
- GitSourceProvider
- Resolves GitSource specifications.
- HookBuilderSourceBuilder
-
Adapter that wraps a hooks
Builderas a SourceBuilder. - HttpDownloader
- Downloads files from HTTP(S) URLs with retry, proxy support, and redirect following.
- HttpDownloadPolicy
- Policy for configuring HTTP download behavior.
- IOSSdk
-
The iOS SDK (device or simulator) in
IOSCodeConfig.targetSdk. - LocalPrebuiltResolver
-
Resolves prebuilts from the local
.prebuilt/directory. - LocalSource
- Source code already present in the workspace.
- LocalSourceProvider
- Resolves LocalSource specifications.
- MsvcToolchain
- MSVC toolchain implementation.
- NativeArtifactCompanion
- A companion entry in an artifact declaration.
- NativeArtifactDeclaration
- Declarative description of an artifact to export.
- NativeArtifactEntry
- An entry within a native artifact bundle.
- NativeAssetSpec
- Specification for a native asset to be built or resolved.
- NativeBinaryInfo
- Information about an inspected binary.
- NativeBinaryInspector
- Validates that a file is a correctly-typed native binary for its expected target.
- NativeBuildContext
- Configuration for a native build.
- NativeBuildDefinition
- Definition of how to build a native project for different platforms.
- NativeBuildDirectories
- Directories used during a native build.
- NativeBuildRecipe
- Abstract interface for a native build recipe.
- NativeBuildResult
- Result of a native build operation.
- NativeBuildStep
- A single step in a native build recipe.
- NativeHookConfiguration
- Hook configuration for a native build.
- NativeProject
- A complete native project definition combining prebuilts, sources, and build logic.
- NativeProjectBuilder
- High-level builder that orchestrates the complete native build pipeline.
- NativeProjectExecutor
- Shared build entry point for CLI, hooks, CI, and tests.
- NativeStepContext
- Context passed to individual build steps.
- NativeStepFingerprint
- Fingerprint for a build step, used for caching.
- NativeStepResult
- Result of executing a single build step.
- NativeTarget
- Canonical representation of a native build target.
- NativeTargetPattern
- A pattern that matches native build targets.
- NativeTargetRecipe
- A recipe associated with a target pattern.
- NoOpSourceBuilder
- A no-op source builder used as a placeholder in source fallback configurations where the actual build is handled by a separate recipe system (e.g. NativeBuildRecipe).
- OS
- An operating system which the Dart VM can run on.
- PlatformToolchain
- Platform toolchain interface for native builds.
- PrebuiltArtifact
- Describes a single prebuilt native artifact within a PrebuiltManifest.
- PrebuiltCodeAssetBuilder
-
A declarative
Builderthat resolves prebuilt native libraries from GitHub Releases. - PrebuiltManifest
- A complete manifest of prebuilt native artifacts for a single package.
- PrebuiltPolicy
- Policy for preferring prebuilt artifacts vs building from source.
- PrebuiltResolutionContext
- Context passed to resolvers during the resolution chain.
- PrebuiltResolver
- Abstract interface for resolving prebuilt artifacts.
- ProcessResult
- Result of a process execution.
- ProcessRunner
- Runs external processes with logging and error handling.
- ProcessRunnerInterface
- Abstract interface for running external processes.
- ReleaseSource
- Describes where prebuilt artifacts are published.
- ResolutionAttempt
- A single resolution attempt.
- ResolvedFile
- A file that has been resolved and is ready to use.
- ResolvedPrebuilt
- Result of attempting to resolve a prebuilt artifact.
- ResolvedPrebuiltFound
- A prebuilt was found and installed successfully.
- ResolvedPrebuiltNotFound
- No prebuilt was found; the caller should fall back to building from source.
- ResolvedSource
- A resolved source directory ready for preparation and building.
- RunCommand
- Runs a custom shell command in the source directory.
- Resolves prebuilts from the shared hook cache (outputDirectoryShared) by downloading from the release source.
- SourceBuilder
- Compiles source code into a native library.
- SourceBuildResult
- Result of a successful source build.
- SourceFallback
- Configuration for source-based fallback when no prebuilt is available.
- SourceFallbackResolver
- Resolves and builds from source as a fallback when prebuilts fail.
- SourcePreparation
- A preparation step applied to source code before building.
- SourceProvider
- Resolves a SourceSpecification into a ResolvedSource directory.
- SourceResolutionContext
- Context passed to source providers during resolution.
- SourceSpecification
- Describes where source code comes from.
- StaticLibraryPayload
-
A static library (
.aarchive). - StepBuildRecipe
- Composable build recipe that executes a sequence of steps.
- StripStep
- Strip debug symbols from a binary.
- StripStepConfig
- ToolchainRegistry
- Registry of available platform toolchains.
- UserDefinePrebuiltResolver
-
Resolves prebuilts from
hooks.user_definesconfiguration. - VcpkgToolchain
- vcpkg toolchain implementation.
- WindowsBuildTarget
- Platform-specific build configuration for Windows.
Enums
- NativeArtifactKind
- Kind of native artifact produced by a build.
- NativeArtifactRole
- Role of an artifact entry within a native artifact bundle.
- NetworkPolicy
- Controls network access during source resolution.
- PrebuiltSource
- Describes which resolver was used.
- SourceOrigin
- How source code was acquired.
Functions
-
canonicalDynamicLibraryName(
NativeTarget target, String libraryStem) → String - Returns the canonical dynamic library filename for a target and stem.
-
canonicalLibraryName(
{required NativeTarget target, required String libraryStem, required ArtifactPayload payload}) → String - Returns the canonical library filename for a payload type.
-
canonicalStaticLibraryName(
NativeTarget target, String libraryStem) → String - Returns the canonical static library filename for a target and stem.
-
computeCacheKey(
NativeProject project, NativeTarget target) → String - Compute a project-scoped cache key for a target.
-
detect(
[Directory? workingDirectory]) → NativeProject? -
Attempts to auto-discover a NativeProject from the nearest
native_prebuilt.yaml. -
expectedLibraryName(
{required NativeTarget target, required String stem}) → String -
Expected library filename for a given
targetand librarystem. -
fingerprintHash(
String input) → String - Compute a reproducible SHA-256 hex digest for use in build fingerprints.
-
fingerprintHashMultiple(
List< String> inputs) → String - Compute a SHA-256 hex digest from multiple string inputs.
-
generateManifest(
{required NativePrebuiltConfig config, required String tag, required bool allowMissing, Directory? builtLibraryDir, Directory? releaseAssetsDir, bool toleratePartialBuiltLibrary = false}) → Future< PrebuiltManifest> -
hostTarget(
) → NativeTarget - Returns a NativeTarget for the current host machine.
-
isLockManifestOutput(
String outputPath) → bool -
isRetryableStatusCode(
int statusCode) → bool - Whether the given HTTP status code should be retried.
-
isStaticArchiveName(
String name) → bool -
Whether the
nameappears to be a static library archive. -
isTransientError(
Object error) → bool - Classifies whether an error is transient and worth retrying.
-
isWasmName(
String name) → bool -
Whether the
nameappears to be a WebAssembly module. -
libraryMatchRank(
String basename, String canonicalName) → int - Ranks library name matches for deterministic selection.
-
matchesLibraryName(
String basename, {required String canonicalName, required bool acceptVersionedNames}) → bool -
Whether the given filename matches a canonical library name, including
versioned variants like
libfoo.so.1.2. -
nativePrebuiltBuild(
List< String> args, {NativeProject? project}) → Future<void> - High-level convenience function for hook entrypoints.
-
packageBuiltLibrary(
{required File builtFile, required File archiveFile}) → Future< void> -
parseTarget(
String label) → NativeTarget? - Parse a target label into a NativeTarget.
-
renderLockManifest(
PrebuiltManifest manifest) → String -
renderManifest(
NativePrebuiltConfig config, PrebuiltManifest manifest, String tag) → String -
renderManifestOutput(
NativePrebuiltConfig config, PrebuiltManifest manifest, String tag, String outputPath) → String -
renderPayload(
ArtifactPayload payload) → String -
renderReleaseSource(
ReleaseSource source) → String -
resolveConfigFile(
[String? configPath, Directory? workingDirectory]) → File? -
Resolves the nearest
native_prebuilt.yamlstarting atworkingDirectoryand walking up parent directories. -
retryBackoff(
int attempt) → Duration - Computes a backoff delay for the given attempt number (0-indexed).
-
runNativePrebuiltCli(
List< String> args, {NativeProject? project}) → Future<void> -
Runs the
native_prebuiltCLI. -
shouldBuildFromSource(
HookInput input) → bool -
Reads the
build_from_sourceuser-defined flag frominput. -
supportedTargetLabels(
NativeProject project) → List< String> -
supportedTargets(
NativeProject project) → Iterable< NativeTarget> -
targetFromCodeConfig(
CodeConfig config) → NativeTarget -
Creates a NativeTarget from a
CodeConfigprovided by the build hook. -
targetFromPlatformLabel(
String label) → NativeTarget
Exceptions / Errors
- BinaryArchitectureException
- Thrown when a binary has the wrong architecture for its target.
- BinaryFormatException
- Thrown when a binary does not match the expected format.
- HttpDownloadException
- Exception thrown when an HTTP download fails.
- SourcePreparationException
- Exception thrown when a source preparation step fails.
- TimeoutException
- Exception thrown when a timeout occurs during download.