dynamic_library

This Dart package is focused on providing better experiences related to DynamicLibrary usage in Dart and Flutter projects. This package is used internally at Pieces.app and Runtime.dev.

We considered using the dylib package but found it insufficient to provide descriptive errors when working with dynamic libraries in Dart and Flutter applications. Dynamic libraries could fail to load for any one of the following reasons:

• The file doesn't exist
• The directory we are searching in doesn't exist
• The dynamic library is missing dependencies

The implementation of DynamicLibrary in the Dart standard library fails to say essentially anything other than 'DynamicLibrary fails to load'. When deploying multiple dynamic libraries across multiple platforms, we really need traceability to know if the dynamic library doesn't exist, isn't in the right place, or is missing dependencies to better inform the developer on proper debugging steps or work scope estimation.

Installation

Add the following to your pubspec.yaml:

dependencies:
  dynamic_library: ^1.1.3

Features

• Descriptive Errors: Traceability to know if the dynamic library doesn't exist, isn't in the right place, or is missing dependencies.
• Dependency Resolution: Includes flutterAssetsDirectory and defaultLibraryDirectory functions to assist in dependency resolution across different platforms.
• Path Customization: The fullLibraryName and fullLibraryPath functions support an optional includePrefix argument to toggle the lib prefix, ensuring backward compatibility.
• Flutter Rust Bridge Support: Integrates with and supports initialization of flutter_rust_bridge packages (v2.11.1+).

Project Layout

This package follows the traditional Dart package layout:

• example - example usage
• lib - source code
• scripts/ - utility scripts, including prompt generators for autodoc
• test - tests

This project also has more source code that is used to verify the unique requirements of dynamic libraries for Flutter applications + Dart applications. These tests are currently not in CI/CD and are checked manually for releases, but this will be resolved in the future.

• flutter_example/ - Flutter application to use to test out dynamic library loading in a bundled application
• rust_*/ - the Rust folders are used to build dynamic libraries for testing

Scripts

The scripts/prompts/ directory contains tools to generate structured prompts for LLM-assisted documentation writing (autodoc). These can be used to draft API references, examples, and quickstarts:

• API Reference Prompt Generator: dart run scripts/prompts/autodoc_api_reference_prompt.dart <module_name> <source_dir> [lib_dir]
• Examples Prompt Generator: dart run scripts/prompts/autodoc_examples_prompt.dart <module_name> <source_dir> [lib_dir]
• Quickstart Prompt Generator: dart run scripts/prompts/autodoc_quickstart_prompt.dart <module_name> <source_dir> [lib_dir]

Usage

For comprehensive instructions, see our Dynamic Library Core documentation:

• Quickstart
• Examples
• API Reference

Note: It is recommended to not use searchPath when using this library in compiled applications as there are a lot of cross-platform variables to consider in your application. This searchPath parameter is more useful for running Dart code in a development environment (with binaries in various locations), instead of in production environments.

Contributing

This package uses runtime_ci_tooling (via global activation) for repository scaffolding, CI, and release workflows.

This package is maintained on GitHub