### Running Document Examples (Bash)

Source: https://github.com/al-the-bear/tom_d4rt/blob/main/tom_d4rt_generator/_copilot_guidelines/example.md

These commands show how to run individual document-based examples from their respective directories. It includes steps for dependency installation, configuration generation, and running the example script.

```bash
cd example/user_guide
dart pub get
dart run tom_d4rt_generator --config d4rt_bridging.json
dart run bin/run_example.dart
```

--------------------------------

### Generate and Test Example

Source: https://github.com/al-the-bear/tom_d4rt/blob/main/tom_d4rt_generator/_copilot_guidelines/example.md

Navigate to the example document directory, fetch dependencies, run the generator with a configuration, and then execute the generated example.

```bash
cd example/<document-name>
dart pub get
dart run tom_d4rt_generator --config d4rt_bridging.json --project .
dart run bin/run_example.dart
```

--------------------------------

### Run Examples

Source: https://github.com/al-the-bear/tom_d4rt/blob/main/tom_d4rt/_copilot_guidelines/build.md

Execute example files to verify their functionality. This includes running a single example or iterating through all examples in the example directory.

```bash
dart run example/basic_execution_example.dart
```

```bash
for f in example/*.dart; do dart run "$f"; done
```

--------------------------------

### Running All Examples

Source: https://github.com/al-the-bear/tom_d4rt/blob/main/tom_d4rt/_copilot_guidelines/example.md

Verifies that all example files compile and execute correctly. This command should be run after adding new examples to ensure they function as expected.

```bash
cd tom_d4rt
dart run example/run_all_examples.dart
```

--------------------------------

### Create Example Directory Structure

Source: https://github.com/al-the-bear/tom_d4rt/blob/main/tom_d4rt_generator/_copilot_guidelines/example.md

Commands to create the necessary directory structure for a new documentation-based example.

```bash
mkdir -p example/<document-name>/lib/src
mkdir -p example/<document-name>/bin
```

--------------------------------

### Example: Setting DART_SDK for Flutter on macOS

Source: https://github.com/al-the-bear/tom_d4rt/blob/main/tom_d4rt_generator/_copilot_guidelines/running_d4rtgen.md

Demonstrates setting the DART_SDK variable for a typical Flutter installation on macOS and verifies the SDK path.

```bash
# macOS with Flutter
export DART_SDK=$HOME/development/flutter/bin/cache/dart-sdk

# Verify
ls $DART_SDK/lib/_internal
# Should show: sdk_library_metadata, dart2js_platform.dill, etc.
```

--------------------------------

### Example File Template

Source: https://github.com/al-the-bear/tom_d4rt/blob/main/tom_d4rt/_copilot_guidelines/example.md

A template for creating new example files, including necessary imports, class definitions, and a main function structure. Use 'async' if the example involves 'await'.

```dart
// Example: {Feature Name}
// From: doc/{source_file.md} - {Section Name}
//
// Brief description of what this example demonstrates.

import 'package:tom_d4rt/d4rt.dart';

// Any native classes/enums needed for the example
class ExampleClass {
  // ...
}

void main() async {  // Use async if example uses await
  final d4rt = D4rt();

  print('=== Section Name ===');
  
  // Example code with explanatory comments
  // ...
}
```

--------------------------------

### Example File Structure

Source: https://github.com/al-the-bear/tom_d4rt/blob/main/tom_d4rt/_copilot_guidelines/example.md

Organizes example files into subfolders based on the source documentation they relate to. Ensures examples are self-contained, have a clear purpose, include documentation headers, and are runnable.

```bash
example/
├── run_all_examples.dart    # Runs all examples to verify they work
├── d4rt_example.dart        # Comprehensive bridging example (original)
├── readme/                  # Examples from README.md
├── user_guide/              # Examples from doc/d4rt_user_guide.md
└── bridging_guide/          # Examples from doc/BRIDGING_GUIDE.md
```

--------------------------------

### Install Application Target

Source: https://github.com/al-the-bear/tom_d4rt/blob/main/tom_d4rt_flutter_test/windows/CMakeLists.txt

Installs the main application executable. It's placed in the root of the installation prefix and marked as a Runtime component.

```cmake
install(TARGETS ${BINARY_NAME} RUNTIME DESTINATION "${CMAKE_INSTALL_PREFIX}"
  COMPONENT Runtime)
```

--------------------------------

### Generate Bridges for Example Project

Source: https://github.com/al-the-bear/tom_d4rt/blob/main/tom_d4rt_generator/_copilot_guidelines/build.md

Navigate to the example directory, fetch dependencies, and then generate bridges from the parent directory.

```bash
cd example
dart pub get
cd ..
dart run bin/d4rt_gen.dart --project=example
```

--------------------------------

### Complete tom_build.yaml Example

Source: https://github.com/al-the-bear/tom_d4rt/blob/main/tom_ast_generator/doc/tom_build_configuration_and_cli.md

A comprehensive example of a `tom_build.yaml` file, combining various configuration options for AST generation.

```yaml
# tom_build.yaml
astgen:
  # Scan the workspace for projects
  scan: ../
  recursive: true
  
  # Exclude unnecessary directories
  exclude:
    - '**/node_modules/**'
    - '**/build/**'
    - '**/.dart_tool/**'
    - '**/test/**'
    - '**/example/**'
  
  # Don't even look inside these directories
  recursion-exclude:
    - '**/.git/**'
    - '**/node_modules/**'
  
  # AST file settings
  output: lib/d4rt_ast.g.dart
  
  # Show detailed output
  verbose: true
```

--------------------------------

### Running All Examples

Source: https://github.com/al-the-bear/tom_d4rt/blob/main/tom_d4rt/_copilot_guidelines/documentation.md

Bash command to execute all documented code examples using the Dart SDK. This command verifies that all examples are runnable and included in the test suite.

```bash
dart run example/run_all_examples.dart
```

--------------------------------

### Running All Document Examples (Bash)

Source: https://github.com/al-the-bear/tom_d4rt/blob/main/tom_d4rt_generator/_copilot_guidelines/example.md

This command executes a master script to run all document-based examples. Options are available to only generate bridges or only run the examples.

```bash
dart run example/run_all_examples.dart
dart run example/run_all_examples.dart --generate-only
dart run example/run_all_examples.dart --run-only
```

--------------------------------

### Installation Rules for Application Bundle

Source: https://github.com/al-the-bear/tom_d4rt/blob/main/tom_d4rt_flutter_ast/test/tom_d4rt_flutter_ast_app/windows/CMakeLists.txt

Configures installation rules for the application, ensuring that support files are copied next to the executable. This includes setting the installation prefix and defining destinations for data and libraries.

```cmake
set(BUILD_BUNDLE_DIR "$<TARGET_FILE_DIR:${BINARY_NAME}>")
set(CMAKE_VS_INCLUDE_INSTALL_TO_DEFAULT_BUILD 1)
if(CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT)
  set(CMAKE_INSTALL_PREFIX "${BUILD_BUNDLE_DIR}" CACHE PATH "..." FORCE)
endif()

set(INSTALL_BUNDLE_DATA_DIR "${CMAKE_INSTALL_PREFIX}/data")
set(INSTALL_BUNDLE_LIB_DIR "${CMAKE_INSTALL_PREFIX}")

install(TARGETS ${BINARY_NAME} RUNTIME DESTINATION "${CMAKE_INSTALL_PREFIX}"
  COMPONENT Runtime)

install(FILES "${FLUTTER_ICU_DATA_FILE}" DESTINATION "${INSTALL_BUNDLE_DATA_DIR}"
  COMPONENT Runtime)

install(FILES "${FLUTTER_LIBRARY}" DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
  COMPONENT Runtime)

if(PLUGIN_BUNDLED_LIBRARIES)
  install(FILES "${PLUGIN_BUNDLED_LIBRARIES}"
    DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
    COMPONENT Runtime)
endif()

set(NATIVE_ASSETS_DIR "${PROJECT_BUILD_DIR}native_assets/windows/")
install(DIRECTORY "${NATIVE_ASSETS_DIR}"
   DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
   COMPONENT Runtime)

set(FLUTTER_ASSET_DIR_NAME "flutter_assets")
install(CODE "
  file(REMOVE_RECURSE \"${INSTALL_BUNDLE_DATA_DIR}/${FLUTTER_ASSET_DIR_NAME}\")
  " COMPONENT Runtime)
install(DIRECTORY "${PROJECT_BUILD_DIR}/${FLUTTER_ASSET_DIR_NAME}"
  DESTINATION "${INSTALL_BUNDLE_DATA_DIR}" COMPONENT Runtime)

install(FILES "${AOT_LIBRARY}" DESTINATION "${INSTALL_BUNDLE_DATA_DIR}"
  CONFIGURATIONS Profile;Release
  COMPONENT Runtime)
```

--------------------------------

### Referencing External Example File

Source: https://github.com/al-the-bear/tom_d4rt/blob/main/tom_d4rt/_copilot_guidelines/documentation.md

Markdown syntax for referencing a complete code example file located in the example directory. Use this for examples longer than 20 lines.

```markdown
See [basic_execution_example.dart](../example/user_guide/basic_execution_example.dart) for a complete example.
```

--------------------------------

### Build Configuration Example

Source: https://github.com/al-the-bear/tom_d4rt/blob/main/tom_d4rt_generator/doc/userbridge_override_design.md

Example of a build.yaml configuration for tom_d4rt, specifying module settings, barrel files, output paths, and user bridge paths.

```yaml
# build.yaml
modules:
  - name: all
    barrelFiles:
      - lib/my_package.dart
    outputPath: lib/src/d4rt_bridges/bridges.dart
    userBridgePath: lib/src/d4rt_bridges/user_bridges/  # Optional
```

--------------------------------

### Run Specific D4rt Example

Source: https://github.com/al-the-bear/tom_d4rt/blob/main/tom_d4rt_generator/_copilot_guidelines/example.md

Execute a single D4rt script example by its name. Navigate to the example directory first.

```bash
dart run run_examples.dart basic
dart run run_examples.dart generic
dart run run_examples.dart inheritance
```

--------------------------------

### Running DCli Examples

Source: https://github.com/al-the-bear/tom_d4rt/blob/main/tom_d4rt_generator/example/d4_test_scripts/README.md

Demonstrates how to execute DCli examples using different tools: `dart run` for JIT compilation, `dcli` for direct execution, and `d4rt` for the D4rt environment.

```bash
# With dart run (JIT compiled)
dart run bin/dcli_scripting_guide/01_hello.dart
```

```bash
# With dcli
dcli bin/dcli_scripting_guide/01_hello.dart
```

```bash
# With d4rt
d4rt bin/dcli_scripting_guide/01_hello.dart
```

--------------------------------

### Run Example Scripts

Source: https://github.com/al-the-bear/tom_d4rt/blob/main/tom_d4rt_generator/_copilot_guidelines/build.md

After generating bridges, navigate to the example directory and run the provided Dart scripts to test the generated bridges.

```bash
cd example
dart run run_examples.dart all
```

--------------------------------

### Installation Rules for Application Bundle

Source: https://github.com/al-the-bear/tom_d4rt/blob/main/tom_d4rt_flutter_test/linux/CMakeLists.txt

Configures the installation process to create a relocatable bundle. It cleans the bundle directory, installs the executable, ICU data, Flutter library, bundled libraries, native assets, and Flutter assets.

```cmake
set(BUILD_BUNDLE_DIR "${PROJECT_BINARY_DIR}/bundle")
if(CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT)
  set(CMAKE_INSTALL_PREFIX "${BUILD_BUNDLE_DIR}" CACHE PATH "..." FORCE)
endif()

install(CODE "
  file(REMOVE_RECURSE \"${BUILD_BUNDLE_DIR}/\")
  " COMPONENT Runtime)

set(INSTALL_BUNDLE_DATA_DIR "${CMAKE_INSTALL_PREFIX}/data")
set(INSTALL_BUNDLE_LIB_DIR "${CMAKE_INSTALL_PREFIX}/lib")

install(TARGETS ${BINARY_NAME} RUNTIME DESTINATION "${CMAKE_INSTALL_PREFIX}"
  COMPONENT Runtime)

install(FILES "${FLUTTER_ICU_DATA_FILE}" DESTINATION "${INSTALL_BUNDLE_DATA_DIR}"
  COMPONENT Runtime)

install(FILES "${FLUTTER_LIBRARY}" DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
  COMPONENT Runtime)

foreach(bundled_library ${PLUGIN_BUNDLED_LIBRARIES})
  install(FILES "${bundled_library}"
    DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
    COMPONENT Runtime)
endforeach(bundled_library)

set(NATIVE_ASSETS_DIR "${PROJECT_BUILD_DIR}native_assets/linux/")
install(DIRECTORY "${NATIVE_ASSETS_DIR}"
   DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
   COMPONENT Runtime)

set(FLUTTER_ASSET_DIR_NAME "flutter_assets")
install(CODE "
  file(REMOVE_RECURSE \"${INSTALL_BUNDLE_DATA_DIR}/${FLUTTER_ASSET_DIR_NAME}\")
  " COMPONENT Runtime)
install(DIRECTORY "${PROJECT_BUILD_DIR}/${FLUTTER_ASSET_DIR_NAME}"
  DESTINATION "${INSTALL_BUNDLE_DATA_DIR}" COMPONENT Runtime)

if(NOT CMAKE_BUILD_TYPE MATCHES "Debug")
  install(FILES "${AOT_LIBRARY}" DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
    COMPONENT Runtime)
endif()
```

--------------------------------

### Installation Bundle Configuration

Source: https://github.com/al-the-bear/tom_d4rt/blob/main/tom_d4rt_flutter_ast/test/tom_d4rt_flutter_ast_app/linux/CMakeLists.txt

Configures the installation prefix to create a relocatable bundle in the build directory and ensures a clean bundle directory on each build.

```cmake
set(BUILD_BUNDLE_DIR "${PROJECT_BINARY_DIR}/bundle")
if(CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT)
  set(CMAKE_INSTALL_PREFIX "${BUILD_BUNDLE_DIR}" CACHE PATH "..." FORCE)
endif()

install(CODE "
  file(REMOVE_RECURSE \"${BUILD_BUNDLE_DIR}/\")
  " COMPONENT Runtime)

set(INSTALL_BUNDLE_DATA_DIR "${CMAKE_INSTALL_PREFIX}/data")
set(INSTALL_BUNDLE_LIB_DIR "${CMAKE_INSTALL_PREFIX}/lib")
```

--------------------------------

### Document Example Configuration (JSON)

Source: https://github.com/al-the-bear/tom_d4rt/blob/main/tom_d4rt_generator/_copilot_guidelines/example.md

This JSON structure serves as the CLI configuration file for document-based examples. It defines the name, description, modules to be bridged, and the output path for generated bridges.

```json
{
  "$schema": "../../json_schema/d4rt_bridging_schema.json",
  "name": "example_name",
  "description": "Example description",
  "modules": [
    {
      "package": "example_package_name",
      "barrelFile": "lib/example_package.dart"
    }
  ],
  "outputPath": "lib/src/d4rt_bridges/"
}
```

--------------------------------

### Generating Bridges for New Example Projects

Source: https://github.com/al-the-bear/tom_d4rt/blob/main/tom_d4rt_generator/_copilot_guidelines/testing.md

After setting up a new example project, navigate to its directory and run the `d4rtgen` command to generate the necessary bridges.

```bash
cd example/<name>
dart run tom_d4rt_generator:d4rtgen
```

--------------------------------

### Install Application Bundle Components

Source: https://github.com/al-the-bear/tom_d4rt/blob/main/tom_d4rt_flutter_ast/test/tom_d4rt_flutter_ast_app/linux/CMakeLists.txt

Installs the main executable, ICU data, Flutter library, bundled plugin libraries, and native assets into the application bundle.

```cmake
install(TARGETS ${BINARY_NAME} RUNTIME DESTINATION "${CMAKE_INSTALL_PREFIX}"
  COMPONENT Runtime)

install(FILES "${FLUTTER_ICU_DATA_FILE}" DESTINATION "${INSTALL_BUNDLE_DATA_DIR}"
  COMPONENT Runtime)

install(FILES "${FLUTTER_LIBRARY}" DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
  COMPONENT Runtime)

foreach(bundled_library ${PLUGIN_BUNDLED_LIBRARIES})
  install(FILES "${bundled_library}"
    DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
    COMPONENT Runtime)
endforeach(bundled_library)

set(NATIVE_ASSETS_DIR "${PROJECT_BUILD_DIR}native_assets/linux/")
install(DIRECTORY "${NATIVE_ASSETS_DIR}"
   DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
   COMPONENT Runtime)
```

--------------------------------

### Update run_examples.dart for New Example

Source: https://github.com/al-the-bear/tom_d4rt/blob/main/tom_d4rt_generator/_copilot_guidelines/example.md

Add the new D4rt script to the list of available scripts and include necessary bridge imports in the main example runner file.

```dart
import 'package:d4rt_generator_example/d4rt_bridges/new_feature_bridge.dart';

// In availableScripts list:
'new_feature_example.d4rt',
```

--------------------------------

### Example Test File Structure

Source: https://github.com/al-the-bear/tom_d4rt/blob/main/tom_d4rt_flutter_ast/_copilot_guidelines/d4rt_flutter_testing.md

A sample test file demonstrating how to use SendTestRunner to test a specific bridged module. Includes setup and teardown for the test runner.

```dart
// test/my_feature_test.dart
import 'package:flutter_test/flutter_test.dart';
import 'send_test_runner.dart';

void main() {
  setUpAll(() => SendTestRunner.setUp());
  tearDownAll(() => SendTestRunner.tearDown());

  group('EdgeInsets', () {
    test('EdgeInsets.all creates uniform padding', () async {
      final result = await SendTestRunner.send('painting/edge_insets_test.dart');
      
      expect(result.success, isTrue, reason: result.error);
      expect(result.widgetType, contains('Container'));
      expect(result.output, contains('EdgeInsets.all works'));
    });
  });
}
```

--------------------------------

### Specify Project Pattern for AST Generation

Source: https://github.com/al-the-bear/tom_d4rt/blob/main/tom_ast_generator/doc/tom_build_configuration_and_cli.md

Generate AST files for specific projects using glob patterns with the `--project` option. This example targets projects starting with 'tom_' and includes 'my_app'.

```bash
dart run tom_d4rt_astgen:astgen --project='tom_*_builder,my_app'
```

--------------------------------

### Complete Test File Example for Tom D4rt Generator

Source: https://github.com/al-the-bear/tom_d4rt/blob/main/tom_d4rt_generator/_copilot_guidelines/testing.md

A typical Dart test file structure for testing Tom D4rt generators. It includes setup for test fixtures and temporary output directories, and a group for testing a specific feature category.

```dart
@TestOn('vm')  // Required for subprocess tests
@Timeout(Duration(minutes: 2))  // Bridge generation + subprocess needs time

import 'dart:io';
import 'package:path/path.dart' as p;
import 'package:test/test.dart';
import 'package:tom_d4rt_generator/tom_d4rt_generator.dart';

void main() {
  late String testFixturesDir;
  late String tempOutputDir;

  setUpAll(() {
    testFixturesDir = p.join(Directory.current.path, 'test', 'fixtures');
    tempOutputDir = Directory.systemTemp.createTempSync('test_').path;
  });

  tearDownAll(() {
    try {
      Directory(tempOutputDir).deleteSync(recursive: true);
    } catch (_) {}
  });

  group('Feature Category', () {
    late String generatedCode;
    late BridgeGeneratorResult result;

    setUpAll(() async {
      final generator = BridgeGenerator(
        workspacePath: testFixturesDir,
        skipPrivate: true,
        helpersImport: 'package:tom_d4rt/tom_d4rt.dart',
        sourceImport: 'test_source.dart',
        packageName: 'test_package',
        verbose: false,
      );

      final sourceFile = p.join(testFixturesDir, 'test_source.dart');
      final outputFile = p.join(tempOutputDir, 'test_output.dart');

      result = await generator.generateBridges(
        sourceFiles: [sourceFile],
        outputPath: outputFile,
        moduleName: 'test',
      );

      expect(result.errors, isEmpty, reason: 'Should generate without errors');
      generatedCode = await File(result.outputFiles.first).readAsString();
    });

    test('G-XX-1: feature description [2026-02-10 06:37] (PASS)', () {
      // Inspect generated code
      expect(generatedCode, contains('ExpectedPattern'));
    });
  });
}
```

--------------------------------

### Register Extensions and Finalize Bridges Pattern

Source: https://github.com/al-the-bear/tom_d4rt/blob/main/tom_d4rt_flutter_ast/doc/d4rt_consolidation_plan.md

This example demonstrates the `registerExtensions / finalizeBridges` pattern, a core part of the D4rt architecture. It shows how to register extensions and then finalize bridges, ensuring proper setup and execution of extensions. This pattern is crucial for managing typed execution and extension-hook APIs.

```dart
// Canonical example from `FlutterD4rt`

// Pre-material (inline) pattern:
final myExtensions = <Type, Object>{};

// Post-material (queued) pattern:
final queuedExtensions = <Type, Object>{};

// Register extensions and finalize bridges
final d4rt = FlutterD4rt(
  registerExtensions: myExtensions,
  finalizeBridges: queuedExtensions,
);

// Example usage:
final result = await d4rt.execute<int>(
  (d4rt) => d4rt.unwrapAs<int>() + 1,
);
print(result); // 1
```

--------------------------------

### Scan Directory Configuration Examples

Source: https://github.com/al-the-bear/tom_d4rt/blob/main/tom_ast_generator/doc/tom_build_configuration_and_cli.md

Demonstrates how to configure the `scan` directory for discovering projects in `tom_build.yaml`.

```yaml
scan: .                       # Scan current directory
scan: ../                     # Scan parent directory
scan: packages/               # Scan packages directory
```

--------------------------------

### Workspace Search Algorithm Example

Source: https://github.com/al-the-bear/tom_d4rt/blob/main/tom_ast_generator/doc/astgen_build_yaml.md

Illustrates how the tool resolves `project:name/path` notation by searching the workspace for a `pubspec.yaml` file with a matching name. The example shows a workspace structure and how both sibling and nested directories are correctly identified.

```text
workspace/
├── tom_d4rt_astgen/        ← Current directory
│   └── build.yaml
├── tom_runtime/            ← Found as sibling
│   └── pubspec.yaml (name: tom_runtime)
└── apps/
    └── tom_uam_client/     ← Found as nested directory
        └── pubspec.yaml (name: tom_uam_client)


Both `project:tom_runtime/assets` and `project:tom_uam_client/assets` will be resolved correctly.
```

--------------------------------

### Verification Checklist for D4rt Examples

Source: https://github.com/al-the-bear/tom_d4rt/blob/main/tom_d4rt_generator/_copilot_guidelines/example.md

Steps to verify new D4rt examples before committing, including regenerating bridges, running the analyzer, and executing all examples.

```bash
dart run bin/d4rt_generator.dart --project=example
cd example && dart analyze
dart run run_examples.dart all or dart run example/run_all_examples.dart
```

--------------------------------

### Project Path Configuration Examples

Source: https://github.com/al-the-bear/tom_d4rt/blob/main/tom_ast_generator/doc/tom_build_configuration_and_cli.md

Shows different ways to specify the project path using the `project` field in `tom_build.yaml`.

```yaml
project: .                    # Current directory
project: ../my_app            # Parent directory
project: packages/core        # Subdirectory
```

--------------------------------

### Running the AST Generator Tool

Source: https://github.com/al-the-bear/tom_d4rt/blob/main/tom_ast_generator/doc/astgen_build_yaml.md

Command-line examples for executing the `tom_d4rt_astgen` tool. Shows how to use a default or custom configuration file, perform a dry run, enable verbose output, and display help.

```bash
# Use default build.yaml in current directory
dart run tom_d4rt_astgen:astgen

# Specify custom config file
dart run tom_d4rt_astgen:astgen -c my_build.yaml

# Dry run (show what would be done)
dart run tom_d4rt_astgen:astgen --dry-run

# Verbose output
dart run tom_d4rt_astgen:astgen -v

# Show help
dart run tom_d4rt_astgen:astgen --help
```

--------------------------------

### TOM Build Configuration Example

Source: https://github.com/al-the-bear/tom_d4rt/blob/main/tom_ast_generator/doc/tom_build_configuration_and_cli.md

Define AST generation settings, such as output file and verbosity, in the `tom_build.yaml` file.

```yaml
# tom_build.yaml
astgen:
  output: lib/d4rt_ast.g.dart
  verbose: false
```

--------------------------------

### Complete AST Generator Build Configuration Example

Source: https://github.com/al-the-bear/tom_d4rt/blob/main/tom_ast_generator/doc/astgen_build_yaml.md

A comprehensive example of a `build.yaml` file demonstrating different configurations for converting Dart files to AST YAML format, including entrypoints, exclusions, output paths, and import handling.

```yaml
astgen:
  convert:
    # Main application runners
    - entrypoints: lib/*.runner.dart
      exclude:
        - lib/*.test.dart
        - lib/*.g.dart
      output: project:tom_runtime/assets
      root: .
      preserve_structure: false
      include_sourcemap: true
      include_imports: false
      
    # Walker tools with preserved structure
    - entrypoints: example/walkers/bin/**/*.walker.dart
      exclude:
        - example/walkers/bin/**/*.test.dart
      output: project:tom_walkers_runtime/assets/walkers
      root: example/walkers/bin
      preserve_structure: true
      include_sourcemap: true
      include_imports: false
      
    # Utility scripts
    - entrypoints: tools/scripts/*.dart
      output: ../runtime_project/assets/scripts
      root: tools
      preserve_structure: false
      include_sourcemap: false
      include_imports: false
```

--------------------------------

### D4rtgen Version Output Example

Source: https://github.com/al-the-bear/tom_d4rt/blob/main/tom_d4rt_generator/doc/d4rt_generator_cli_user_guide.md

Example output when querying the D4rt Bridge Generator version.

```text
D4rt Bridge Generator 1.0.0+0
```

--------------------------------

### Verbose Output Configuration Examples

Source: https://github.com/al-the-bear/tom_d4rt/blob/main/tom_ast_generator/doc/tom_build_configuration_and_cli.md

Demonstrates how to enable detailed output using the `verbose` field in `tom_build.yaml`.

```yaml
verbose: true                 # Show detailed output
verbose: false                # Show summary only
```

--------------------------------

### Install AOT Library

Source: https://github.com/al-the-bear/tom_d4rt/blob/main/tom_d4rt_flutter_test/test/tom_d4rt_flutter_test_app/windows/CMakeLists.txt

Installs the Ahead-Of-Time (AOT) compiled library, but only for Profile and Release build configurations.

```cmake
install(FILES "${AOT_LIBRARY}" DESTINATION "${INSTALL_BUNDLE_DATA_DIR}"
  CONFIGURATIONS Profile;Release
  COMPONENT Runtime)
```

--------------------------------

### Example Package pubspec.yaml Configuration

Source: https://github.com/al-the-bear/tom_d4rt/blob/main/tom_d4rt_generator/_copilot_guidelines/example.md

Configuration for the pubspec.yaml file of an example package, specifying dependencies on tom_d4rt and tom_d4rt_generator.

```yaml
name: <document_name>_example
description: Example from <document-name>.md
version: 1.0.0
publish_to: none

environment:
  sdk: ^3.0.0

dependencies:
  tom_d4rt:
    path: ../../../../tom_d4rt

dev_dependencies:
  tom_d4rt_generator:
    path: ../..
```

--------------------------------

### Regenerate Example Bridges

Source: https://github.com/al-the-bear/tom_d4rt/blob/main/tom_d4rt_generator/_copilot_guidelines/build.md

After making changes to the generator, regenerate the bridges for the example project and verify compilation and functionality.

```bash
# From tom_d4rt_generator directory
dart run bin/d4rt_gen.dart --project=example

# Verify generated bridges compile
cd example && dart analyze lib/d4rt_bridges/

# Verify example scripts still work
dart run run_examples.dart all
```

--------------------------------

### Fetch Dependencies

Source: https://github.com/al-the-bear/tom_d4rt/blob/main/tom_d4rt/_copilot_guidelines/build.md

Ensure all project dependencies are downloaded and ready for use.

```bash
dart pub get
```

--------------------------------

### Dart Sealed Class: Basic Example

Source: https://github.com/al-the-bear/tom_d4rt/blob/main/tom_d4rt_flutter_ast/doc/testlog_20260429-step3-flutterD4rt-cutover/tom_ast_generator.log.txt

A basic example of a sealed class hierarchy representing different states.

```dart
sealed class Result {
  const Result();
}

class Success extends Result {
  final String data;
  const Success(this.data);
}

class Error extends Result {
  final String message;
  const Error(this.message);
}

class Loading extends Result {
  const Loading();
}
```

--------------------------------

### Bundle File Format Example

Source: https://github.com/al-the-bear/tom_d4rt/blob/main/tom_d4rt_ast/doc/d4rt_ast_architecture_design.md

Illustrates the structure of a .ast bundle file, which is a ZIP archive containing gzipped JSON AST files and a manifest.

```json
my_script.ast (ZIP)
├── manifest.json
│   {
│     "version": "1.0",
│     "entryPoint": "bin/main.dart",
│     "files": {
│       "0.ast.json": "bin/main.dart",
│       "1.ast.json": "lib/utils.dart",
│       "2.ast.json": "lib/models/user.dart"
│     }
│   }
├── 0.ast.json (gzip)  ← SCompilationUnit JSON for main.dart
├── 1.ast.json (gzip)  ← SCompilationUnit JSON for utils.dart
└── 2.ast.json (gzip)  ← SCompilationUnit JSON for user.dart
```

--------------------------------

### Example .ast.yaml output with sourcemap

Source: https://context7.com/al-the-bear/tom_d4rt/llms.txt

Illustrates the structure of an .ast.yaml file when include_sourcemap is enabled, showing source file information and generation timestamp.

```yaml
# Example .ast.yaml output (when include_sourcemap: true)
sourcemap:
  source_file: /workspace/lib/tools/my_tool.runner.dart
  generated_at: 2025-01-15T10:30:45.123Z
ast:
  # Serialized AST nodes (declarations, statements, expressions, type info)
```

--------------------------------

### D4RT CustomPainter Usage Example

Source: https://github.com/al-the-bear/tom_d4rt/blob/main/tom_d4rt_flutter_ast/_copilot_guidelines/d4rt_flutter_testing_extended.md

Example of how to use the generated D4rtCustomPainter with callback implementations for drawing and repaint logic.

```dart
final painter = D4rtCustomPainter(
  onPaint: (canvas, size) {
    canvas.drawCircle(Offset(size.width/2, size.height/2), 50.0, Paint()..color = Colors.red);
  },
  onShouldRepaint: (old) => false,
);
return CustomPaint(painter: painter, size: Size(200, 200));
```

--------------------------------

### Main Example Package Structure (Tree)

Source: https://github.com/al-the-bear/tom_d4rt/blob/main/tom_d4rt_generator/_copilot_guidelines/example.md

This outlines the directory structure of the main example package, which serves as a demonstration of the bridge generator. It includes source classes, generated bridges, and D4rt scripts.

```tree
example/
├── pubspec.yaml                # Example package definition
 analysis_options.yaml       # Analyzer config
 generate_bridges.dart       # Local generation script
 run_examples.dart           # Runs D4rt scripts with generated bridges
 lib/
  ├── test_classes.dart       # Barrel export of test classes
  ├── d4rt_bridges.dart       # Barrel export of generated bridges
  ├── test_classes/           # Source classes to be bridged
  │   ├── basic_classes.dart
  │   ├── generic_classes.dart
  │   ├── inheritance_classes.dart
  │   ├── callback_classes.dart
  │   ├── operator_classes.dart
  │   ├── enum_classes.dart
  │   └── global_members.dart
  └── d4rt_bridges/           # Generated bridge files
      ├── basic_bridge.dart
      ├── generic_bridge.dart
      ├── inheritance_bridge.dart
      ├── callback_bridge.dart
      ├── operator_bridge.dart
      ├── enum_bridge.dart
      └── global_bridge.dart
scripts/                    # D4rt scripts demonstrating bridges
  ├── basic_example.d4rt
  ├── generic_example.d4rt
  ├── inheritance_example.d4rt
  ├── callbacks_example.d4rt
  └── operators_example.d4rt
└── test/                       # Unit tests for generated bridges
    ├── test_bridge_context.dart
    ├── test_covariance.dart
    └── ...
```

--------------------------------

### Basic Flat Output Configuration

Source: https://github.com/al-the-bear/tom_d4rt/blob/main/tom_ast_generator/test/README_TEST.md

Configures astgen to convert entrypoint files into a flat output directory without preserving the source structure. Includes sourcemap metadata.

```yaml
- entrypoints: lib/*.runner.dart
  output: project:astgen_test_output/assets
  root: .
  preserve_structure: false
  include_sourcemap: true
```

--------------------------------

### Install AOT Library

Source: https://github.com/al-the-bear/tom_d4rt/blob/main/tom_d4rt_flutter_ast/test/tom_d4rt_flutter_ast_app/linux/CMakeLists.txt

Installs the Ahead-Of-Time (AOT) compiled library into the application bundle, but only for non-Debug build configurations.

```cmake
if(NOT CMAKE_BUILD_TYPE MATCHES "Debug")
  install(FILES "${AOT_LIBRARY}" DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
    COMPONENT Runtime)
endif()
```

--------------------------------

### Install Flutter Assets

Source: https://github.com/al-the-bear/tom_d4rt/blob/main/tom_d4rt_flutter_ast/test/tom_d4rt_flutter_ast_app/linux/CMakeLists.txt

Installs the Flutter assets directory into the application bundle, ensuring it's refreshed on each build.

```cmake
set(FLUTTER_ASSET_DIR_NAME "flutter_assets")
install(CODE "
  file(REMOVE_RECURSE \"${INSTALL_BUNDLE_DATA_DIR}/${FLUTTER_ASSET_DIR_NAME}\")
  " COMPONENT Runtime)
install(DIRECTORY "${PROJECT_BUILD_DIR}/${FLUTTER_ASSET_DIR_NAME}"
  DESTINATION "${INSTALL_BUNDLE_DATA_DIR}" COMPONENT Runtime)
```

--------------------------------

### D4rtUserBridge Annotation Example

Source: https://github.com/al-the-bear/tom_d4rt/blob/main/tom_d4rt_generator/doc/userbridge_override_design.md

Example of using the @D4rtUserBridge annotation to associate a user bridge class with a specific target class.

```dart
@D4rtUserBridge(MyList)
class MyListUserBridge { ... }
```

--------------------------------

### Simplified buildkit.yaml Configuration

Source: https://github.com/al-the-bear/tom_d4rt/blob/main/tom_d4rt_generator/_copilot_guidelines/generator_strategies.md

Demonstrates a simplified buildkit.yaml configuration using a single barrel file, reducing the need for complex exclude patterns and export handling.

```yaml
- name: dcli
  barrelFiles:
    - package:dcli/dcli.dart    # Single barrel is sufficient
  barrelImport: package:dcli/dcli.dart
  outputPath: lib/src/d4rt_bridges/dcli_bridges.b.dart
```

--------------------------------

### Complete GlobalsUserBridge Example

Source: https://github.com/al-the-bear/tom_d4rt/blob/main/tom_d4rt_generator/doc/userbridge_override_design.md

A comprehensive example of a GlobalsUserBridge class, demonstrating overrides for global variables, getters, and top-level functions.

```dart
import 'package:tom_d4rt/d4rt.dart';

class GlobalsUserBridge extends D4UserBridge {
  // Global variable overrides
  static Object? overrideGlobalVariableAppName() => 'OverriddenApp';
  static Object? overrideGlobalVariableMaxRetries() => 10;
  
  // Global getter overrides (return a getter function)
  static Object? Function() overrideGlobalGetterVscode() => 
      () => VSCode.vsCode;
  static Object? Function() overrideGlobalGetterCurrentTime() => 
      () => DateTime.now();
  
  // Top-level function overrides
  static Object? overrideGlobalFunctionGreet(
    Object? visitor,
    List<Object?> positional,
    Map<String, Object?> named,
    List<Object?>? typeArgs,
  ) {
    final name = D4.getRequiredArg<String>(positional, 0, 'name', 'greet');
    return 'Hello, $name!';
  }
}
```