Skip to content

Latest commit

 

History

History
312 lines (222 loc) · 11.3 KB

developing-packages.md

File metadata and controls

312 lines (222 loc) · 11.3 KB
Raw
layout title permalink
page
Developing Packages & Plugins
/developing-packages/
  • TOC {:toc}

Package introduction

Packages enable the creation of modular code that can be shared easily. A minimal package consists of:

  • A pubspec.yaml file: A metadata file that declares the package name, version, author, etc.

  • A lib directory containing the public code in the package, minimally a single <package-name>.dart file.

Package types {#types}

Packages can contain several kinds of content:

  • Dart packages: General packages written in Dart, for example the path package. Some of these may contain Flutter specific functionality and thus have a dependency on the Flutter framework, restricting their use to Flutter only, for example the fluro package.

  • Plugin packages: A specialized Dart package which contain an API written in Dart code combined with a platform-specific implementation for Android (using Java or Kotlin), and/or for iOS (using ObjC or Swift). A concrete example is the battery plugin package.

Developing Dart packages {#dart}

Step 1: Create the package

To create a Dart package, use the --template=package flag with flutter create:

{% commandline %} flutter create --template=package hello {% endcommandline %}

This creates a package project in the hello/ folder with the following specialized content:

  • lib/hello.dart:
    • The Dart code for the package.
  • test/hello_test.dart:

Step 2: Implement the package

For pure Dart packages, simply add the functionality inside the main lib/<package name>.dart file, or in several files in the lib directory.

To test the package, add unit tests in a test directory.

For additional details on how to organize the package contents, see the Dart library package documentation.

Developing plugin packages {#plugin}

If you want to develop a package that calls into platform-specific APIs, you need to develop a plugin package. A plugin package is a specialized version of a Dart package, that in addition to the content described above also contains platform-specific implementations written for Android (Java or Kotlin code), for iOS (Objective-C or Swift code), or for both. The API is connected to the platform-specific implementation(s) using platform channels.

Step 1: Create the package

To create a plugin package, use the --template=plugin flag with flutter create.

Use the --org option to specify your organization, using reverse domain name notation. This value is used in various package and bundle identifiers in the generated Android and iOS code.

{% commandline %} flutter create --org com.example --template=plugin hello {% endcommandline %}

This creates a plugin project in the hello/ folder with the following specialized content:

  • lib/hello.dart:
    • The Dart API for the plugin.
  • android/src/main/java/com/example/​hello/HelloPlugin.java:
    • The Android platform specific implementation of the plugin API.
  • ios/Classes/HelloPlugin.m:
    • The iOS platform specific implementation of the plugin API.
  • example/:
    • A Flutter app that depends on the plugin, and illustrates how to use it.

By default, the plugin project uses Objective-C for iOS code and Java for Android code. If you prefer Swift or Kotlin, you can specify the iOS language using -i and/or the Android language using -a. For example:

{% commandline %} flutter create --template=plugin -i swift -a kotlin hello {% endcommandline %}

Step 2: Implement the package {#edit-plugin-package}

As a plugin package contains code for several platforms written in several programming languages, some specific steps are needed to ensure a smooth experience.

Step 2a: Define the package API (.dart)

The API of the plugin package is defined in Dart code. Open the main hello/ folder in your favorite Flutter editor. Locate the file lib/hello.dart.

Step 2b: Add Android platform code (.java/.kt)

We recommend you edit the Android code using Android Studio.

Before editing the Android platform code in Android Studio, first make sure that the code has been built at least once (i.e., run the example app from your IDE/editor, or in a terminal execute cd hello/example; flutter build apk).

Next,

  1. Launch Android Studio
  2. Select 'Import project' in 'Welcome to Android Studio' dialog, or select 'File > New > Import Project...'' in the menu, and select the hello/example/android/build.gradle file.
  3. In the 'Gradle Sync' dialog, select 'OK'.
  4. In the 'Android Gradle Plugin Update' dialog, select 'Don't remind me again for this project'.

The Android platform code of your plugin is located in hello/java/com.example.hello/​HelloPlugin.

You can run the example app from Android Studio by pressing the ▶ button.

Step 2c: Add iOS platform code (.h+.m/.swift)

We recommend you edit the iOS code using Xcode.

Before editing the iOS platform code in Xcode, first make sure that the code has been built at least once (i.e., run the example app from your IDE/editor, or in a terminal execute cd hello/example; flutter build ios --no-codesign).

Next,

  1. Launch Xcode
  2. Select 'File > Open', and select the hello/example/ios/Runner.xcworkspace file.

The iOS platform code of your plugin is located in Pods/Development Pods/hello/Classes/ in the Project Navigator.

You can run the example app by pressing the ▶ button.

Step 2d: Connect the API and the platform code

Finally, you need to connect the API written in Dart code with the platform-specific implementations. This is done using platform channels.

Adding documentation

It is recommended practice to add the following documentation to all packages:

  1. A README.md file that introduces the package
  2. A CHANGELOG.md file that documents changes in each version
  3. A LICENSE file containing the terms under which the package is licensed
  4. API documentation for all public APIs (see below for details)

API documentation

When you publish a package, API documentation is automatically generated and published to dartdocs.org, see for example the device_info docs.

If you wish to generate API documentation locally on your developement machine, use the following commands:

  1. Change directory to the location of your package:

    cd ~/dev/mypackage

  2. Tell the documentation tool where the Flutter SDK is (change to reflect where you placed it):

    export FLUTTER_ROOT=~/dev/flutter (on macOS or Linux)

    set FLUTTER_ROOT=~/dev/flutter (on Windows)

  3. Run the dartdoc tool (comes as part of the Flutter SDK):

    $FLUTTER_ROOT/bin/cache/dart-sdk/bin/dartdoc (on macOS or Linux)

    %FLUTTER_ROOT%\bin\cache\dart-sdk\bin\dartdoc (on Windows)

For tips on how to write API documentation, see Effective Dart: Documentation.

Publishing packages {#publish}

Once you have implemented a package, you can publish it on Pub, so that other developers can easily use it.

Prior to publishing, make sure to review the pubspec.yaml, README.md, and CHANGELOG.md files to make sure their content is complete and correct.

Next, run the dry-run command to see if everything passes analysis:

{% commandline %} flutter packages pub publish --dry-run {% endcommandline %}

Finally, run the actual publish command: {% commandline %} flutter packages pub publish {% endcommandline %}

For details on publishing, see the Pub publishing docs.

Handling package interdependencies {#dependencies}

If you are developing a package hello that depends on the Dart API exposed by another package, you need to add that package to the dependencies section of your pubspec.yaml file. The code below makes the Dart API of the url_launcher plugin available to hello:

In hello/pubspec.yaml:

dependencies:
  url_launcher: ^0.4.2

You can now import 'package:url_launcher/url_launcher.dart' and launch(someUrl) in the Dart code of hello.

This is no different from how you include packages in Flutter apps or any other Dart project.

But if hello happens to be a plugin package whose platform-specific code needs access to the platform-specific APIs exposed by url_launcher, you also need to add suitable dependency declarations to your platform-specific build files, as shown below.

Android

In hello/android/build.gradle:

android {
    // lines skipped
    dependencies {
        provided rootProject.findProject(":url_launcher")
    }
}

You can now import io.flutter.plugins.urllauncher.UrlLauncherPlugin and access the UrlLauncherPlugin class in the source code at hello/android/src.

iOS

In hello/ios/hello.podspec:

Pod::Spec.new do |s|
  # lines skipped
  s.dependency 'url_launcher'

You can now #import "UrlLauncherPlugin.h" and access the UrlLauncherPlugin class in the source code at hello/ios/Classes.

Conflict resolution

Suppose you want to use some_package and other_package in your package hello, and both of these depend on url_launcher, but in different versions. Then we have a potential conflict. The best way to avoid this is for package authors to use version ranges rather than specific versions when specifying dependencies.

dependencies:
  url_launcher: ^0.4.2    # Good, any 0.4.x with x >= 2 will do.
  image_picker: '0.1.1'   # Not so good, only 0.1.1 will do.

If some_package declares the dependencies above and other_package declares a compatible url_launcher dependency like '0.4.5' or ^0.4.0, pub will be able to resolve the issue automatically. Similar remarks apply to plugin packages' platform-specific dependencies on Gradle modules and/or Cocoa pods.

Even if some_package and other_package declare incompatible versions for url_launcher, it may still be that they actually use url_launcher in compatible ways. Then the conflict can be dealt with by adding a dependency override declaration to the pubspec.yaml file in hello, forcing the use of a particular version:

Forcing the use of url_launcher version 0.4.3 in hello/pubspec.yaml:

dependencies:
  some_package:
  other_package:
dependency_overrides:
  url_launcher: '0.4.3'

If the conflicting dependency is not itself a package, but an Android-specific library like guava, the dependency override declaration must be added to Gradle build logic instead.

Forcing the use of guava version 23.0 in hello/android/build.gradle:

configurations.all {
    resolutionStrategy {
        force 'com.google.guava:guava:23.0-android'
    }
}

Cocoapods does not currently offer dependency override functionality.