dart_native 0.7.8 icon indicating copy to clipboard operation
dart_native: ^0.7.8 copied to clipboard

Write native code using Dart. This package liberates you from native code and low performance channel.

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.

pub package Build Status Dart CI

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 #

DartNative VersionFlutter RequirementsCodegen Version
0.4.x - 0.7.xFlutter 2.2.0 (Dart 2.13.0)2.x
0.3.xFlutter 1.20.0 (Dart 2.9.1)1.2.x
0.2.xFlutter 1.12.13 (Dart 2.7)1.x

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<int> 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

DartObjective-CSwiftJava
nullnilnilnull
boolBOOLBoolbool
intNSIntegerIntint
doubledoubleDoubledouble
StringNSStringStringString
ListNSArrayArrayList, ArrayList
MapNSDictionaryDictionaryMap, HashMap
SetNSSetSetSet, HashSet
FunctionBlockClosurePromise
Pointervoid *UnsafeMutableRawPointer-
NativeByteNSDataDataDirectByteBuffer
NativeObjectNSObjectNSObjectObject

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.

      @native
      class RuntimeSon extends RuntimeStub {
        RuntimeSon([Class isa]) : super(Class('RuntimeSon'));
        RuntimeSon.fromPointer(Pointer<Void> ptr) : super.fromPointer(ptr);
      }
      
    • 3.2 Annotate your own entry (such asmain()) with @nativeRoot.

      @nativeRoot
      void main() {
        runApp(App());
      }
      
    • 3.3 Run

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

      to generate files into your source directory.

      Note: we recommend running clean first:

      flutter packages pub run build_runner clean
      
  • Step 4: Call autogenerated function in <generated-name>.dn.dart in 3.3. The function name is determined by name in pubspec.yaml.

      @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):

      // 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:

      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):

      // 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:

      public class RuntimeStub {
      
          public List<Integer> getList(List<Integer> list) {
              List<Integer> 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 #

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.

19
likes
115
pub points
69%
popularity

Publisher

unverified uploader

Write native code using Dart. This package liberates you from native code and low performance channel.

Homepage

Documentation

API reference

License

Icon for licenses.BSD-3-Clause (LICENSE)

Dependencies

dart_native_gen, ffi, flutter

More

Packages that depend on dart_native