dart_native

DartNative

DartNative operates as a bridge to communicate between Dart and native APIs.

Replaces the low-performing Flutter channel with faster and more concise code.

Features

Dynamic synchronous & asynchronous channeling

DartNative calls any native API dynamically. It supports both synchronous and asynchronous channeling.

Direct call between multi-language interfaces

Serialization of parameters and return values like Flutter Channel is no longer required. DartNative provides direct calls and automatic object marshalling between language interfaces.

Dart finalizer

Dart finalizer is only supported above Flutter 3(Dart 2.17), but with DartNative it is available in Dart Flutter 2.2.0(Dart 2.13.0) and up.

Autogenerate succinct bridging code

DartNative supports automatic type conversion so its bridging code is shorter & simpler than the Flutter channel.

The design and vision of this package:

Requirements

Supported Platforms

iOS & macOS & Android

Usage

Basic usage: Interface binding

Add dart_native to dependencies and build_runner to dev_dependencies. Then you can write code. Here are some examples:

Dart calls Native

Dart code:

final interface = Interface("MyFirstInterface");
// Example for string type.
String helloWorld() {
    return interface.invokeMethodSync('hello', args: ['world']);
}
// Example for num type.
Future sum(int a, int b) {
    return interface.invokeMethod('sum', args: [a, b]);
}

Corresponding Objective-C code:

@implementation DNInterfaceDemo

// Register interface name.
InterfaceEntry(MyFirstInterface)

// Register method "hello".
InterfaceMethod(hello, myHello:(NSString *)str) {
    return [NSString stringWithFormat:@"hello %@!", str];
}

// Register method "sum".
InterfaceMethod(sum, addA:(int32_t)a withB:(int32_t)b) {
    return @(a + b);
}

@end

Corresponding Java code:

// load libdart_native.so
DartNativePlugin.loadSo();

@InterfaceEntry(name = "MyFirstInterface")
public class InterfaceDemo extends DartNativeInterface {

    @InterfaceMethod(name = "hello")
    public String hello(String str) {
        return "hello " + str;
    }

    @InterfaceMethod(name = "sum")
    public int sum(int a, int b) {
        return a + b;
    }
}

NOTE: If your so path is custom, you need pass specific path.

DartNativePlugin.loadSoWithCustomPath("xxx/libdart_native.so");

And before using DartNative in dart, first invoke dartNativeInitCustomSoPath(). It will get path from channel.

Native calls Dart

Dart code:

interface.setMethodCallHandler('totalCost',
        (double unitCost, int count, List list) async {
    return {'totalCost: ${unitCost * count}': list};
});

Corresponding Objective-C code:

[self invokeMethod:@"totalCost"
         arguments:@[@0.123456789, @10, @[@"testArray"]]
            result:^(id _Nullable result, NSError * _Nullable error) {
    NSLog(@"%@", result);
}];

Corresponding Java code:

invokeMethod("totalCost", new Object[]{0.123456789, 10, Arrays.asList("hello", "world")},
             new DartNativeResult() {
                @Override
                public void onResult(@Nullable Object result) {
                    Map retMap = (Map) result;
                    // do something
                }

                @Override
                public void error(@Nullable String errorMessage) {
                    // do something
                }
              }
);

Dart finalizer

final foo = Bar(); // A custom instance.
unitTest.addFinalizer(() { // register a finalizer callback.
  print('The instance of \'foo\' has been destroyed!'); // When `foo` is destroyed by GC, this line of code will be executed.
});

Data types support

Advanced usage: Invoke methods dynamically

• Step 1: Add dart_native to dependencies and build_runner to dev_dependencies.

• Step 2: Generate Dart wrapper code with @dartnative/codegen or write Dart code manually.

• Step 3: Generate code for automatic type conversion using dart_native_gen with the following steps (3.1-3.3):

  • 3.1 Annotate a Dart wrapper class with @native.

    dart复制

    @native
    class RuntimeSon extends RuntimeStub {
      RuntimeSon([Class isa]) : super(Class('RuntimeSon'));
      RuntimeSon.fromPointer(Pointer ptr) : super.fromPointer(ptr);
    }

  • 3.2 Annotate your own entry (such asmain()) with @nativeRoot.

    dart复制

    @nativeRoot
    void main() {
      runApp(App());
    }

  • 3.3 Run

    bash复制

    flutter packages pub run build_runner build --delete-conflicting-outputs 

    to generate files into your source directory.

    Note: we recommend running clean first:

    bash复制

    flutter packages pub run build_runner clean

• Step 4: Call autogenerated function in .dn.dart in 3.3. The function name is determined by name in pubspec.yaml.

  dart复制

  @nativeRoot
  void main() {
    // Function name is generated by name in pubspec.yaml.
    runDartNativeExample(); 
    runApp(App());
  }

• Step 5: Then you can write code. Here are some examples:

  • 5.1 iOS:

    Dart code (generated):

    dart复制

    // new Objective-C object.
    RuntimeStub stub = RuntimeStub();
    
    // Dart function will be converted to Objective-C block.
    stub.fooBlock((NSObject a) {
        print('hello block! ${a.toString()}');
        return 101;
    });
    
    // support built-in structs.
    CGRect rect = stub.fooCGRect(CGRect(4, 3, 2, 1));
    print(rect);
    

    Corresponding Objective-C code:

    objc复制

    typedef int(^BarBlock)(NSObject *a);
    
    @interface RuntimeStub
    
    - (CGRect)fooCGRect:(CGRect)rect;
    - (void)fooBlock:(BarBlock)block;
    
    @end

    More iOS examples see: ios_unit_test.dart

  • 5.2 Android:

    Dart code (generated):

    dart复制

    // new Java object.
    RuntimeStub stub = RuntimeStub();
    
    // get java list.
    List list = stub.getList([1, 2, 3, 4]);
    
    // support interface.
    stub.setDelegateListener(DelegateStub());
    

    Corresponding Java code:

    java复制

    public class RuntimeStub {
    
        public List getList(List list) {
            List returnList = new ArrayList<>();
            returnList.add(1);
            returnList.add(2);
            return returnList;
        }
    
        public void setDelegateListener(SampleDelegate delegate) {
            delegate.callbackInt(1);
        }
    }

    More android examples see: android_unit_test.dart

NOTE: If you use dart_native on macOS, you must use use_frameworks! in your Podfile.

Documentation

Further reading

• 告别 Flutter Channel，调用 Native API 仅需一行代码！
• 如何实现一行命令自动生成 Flutter 插件
• 用 Dart 来写 Objective-C 代码
• 谈谈 dart_native 混合编程引擎的设计
• DartNative Memory Management: Object
• DartNative Memory Management: C++ Non-Object
• DartNative Struct
• 在 Flutter 中玩转 Objective-C Block
• Passing Out Parameter in DartNative

FAQs

Q: Failed to lookup symbol (dlsym(RTLD_DEFAULT, InitDartApiDL): symbol not found) on macOS archive.

A: Select one solution:

1. Use dynamic library: Add use_frameworks! in Podfile.
2. Select Target Runner -> Build Settings -> Strip Style -> change from "All Symbols" to "Non-Global Symbols"

Contribution

• If you need help or you'd like to ask a general question, open an issue.
• If you found a bug, open an issue.
• If you have a feature request, open an issue.
• If you want to contribute, submit a pull request.

License

DartNative is available under the BSD 3-Clause License. See the LICENSE file for more info.