Merge pull request #895 from dart-lang/merge-ffi-package

.github/workflows/ffi.yaml

@@ -0,0 +1,73 @@
+name: Dart CI
+
+on:
+  # Run on PRs and pushes to the default branch.
+  push:
+    branches: [main]
+    paths:
+      - '.github/workflows/ffi.yaml'
+      - 'pkgs/ffi/**'
+  pull_request:
+    branches: [main]
+    paths:
+      - '.github/workflows/ffi.yaml'
+      - 'pkgs/ffi/**'
+  schedule:
+    - cron: "0 0 * * 0"
+
+env:
+  PUB_ENVIRONMENT: bot.github
+
+jobs:
+  # Check code formatting and static analysis on a single OS (linux)
+  # against Dart dev.
+  analyze:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: pkgs/ffi/
+    strategy:
+      fail-fast: false
+      matrix:
+        sdk: [dev]
+    steps:
+      - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11
+      - uses: dart-lang/setup-dart@b64355ae6ca0b5d484f0106a033dd1388965d06d
+        with:
+          sdk: ${{ matrix.sdk }}
+      - id: install
+        name: Install dependencies
+        run: dart pub get
+      - name: Check formatting
+        run: dart format --output=none --set-exit-if-changed .
+        if: always() && steps.install.outcome == 'success'
+      - name: Analyze code
+        run: dart analyze --fatal-infos
+        if: always() && steps.install.outcome == 'success'
+
+  # Run tests on a matrix consisting of two dimensions:
+  # 1. OS: ubuntu-latest, (macos-latest, windows-latest)
+  # 2. release channel: dev
+  test:
+    needs: analyze
+    runs-on: ${{ matrix.os }}
+    defaults:
+      run:
+        working-directory: pkgs/ffi/
+    strategy:
+      fail-fast: false
+      matrix:
+        # Add macos-latest and/or windows-latest if relevant for this package.
+        os: [ubuntu-latest]
+        sdk: [beta, dev]
+    steps:
+      - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11
+      - uses: dart-lang/setup-dart@b64355ae6ca0b5d484f0106a033dd1388965d06d
+        with:
+          sdk: ${{ matrix.sdk }}
+      - id: install
+        name: Install dependencies
+        run: dart pub get
+      - name: Run VM tests
+        run: dart test --platform vm
+        if: always() && steps.install.outcome == 'success'

pkgs/ffi/.gitignore

@@ -0,0 +1,3 @@
+.dart_tool
+.packages
+pubspec.lock

pkgs/ffi/AUTHORS

@@ -0,0 +1,6 @@
+# Below is a list of people and organizations that have contributed
+# to the Dart project. Names should be added to the list like so:
+#
+#   Name/Organization <email address>
+
+Google LLC

pkgs/ffi/CHANGELOG.md

@@ -0,0 +1,146 @@
+## 2.1.1
+
+- Require Dart 3.3.0 or greater.
+- Migrate `elementAt` use to `operator +`.
+
+## 2.1.0
+
+- Require Dart 3.0.0 or greater.
+- Expose native equivalent to `free` (`nativeFree`) from `malloc` and
+  `calloc` allocators.
+
+## 2.0.2
+
+- Fixed a typo in a doc comment.
+- Added package topics to the pubspec file.
+
+## 2.0.1
+
+- Only zero out memory on successful allocation on Windows.
+- Upgrade test dev dependency.
+
+## 2.0.0
+
+- Switch Windows memory allocation to use `CoTaskMemAlloc` and `CoTaskMemFree`,
+  which will enable support for `NativeFinalizer`.
+- Require Dart 2.17.0 or greater.
+
+## 1.2.1
+
+Revert added common C integer types as ABI-specific integers.
+Instead, these are available in Dart 2.17.
+
+## 1.2.0 (retracted)
+
+This release requires Dart `2.16.0` or greater.
+
+## 1.2.0-dev.0
+
+Added common C integer types as ABI-specific integers. These common C integer
+types will make their way into `dart:ffi` in 2.17 and be deprecated from this
+package. Having them in this package enables using them in Dart 2.16.
+
+This pre-release requires Dart `2.16.0-118.0.dev` or greater.
+
+## 1.1.2
+
+Fixed unhandled exception in `withZoneArena` (#107).
+
+## 1.1.1
+
+Adds a sanity check to `Pointer<Utf8>` and `Pointer<Utf16>` extension methods
+that receiver is not `nullptr`.
+
+## 1.1.0
+
+Adds the `arena` allocator.
+
+Moves from static analysis with lints in package:pedantic to package:lints.
+
+## 1.0.0
+
+Bumping the version of this package to `1.0.0`.
+
+Removes all deprecated methods, use `0.3.0-nullsafety.3` for migration.
+
+## 0.3.1-nullsafety.0
+
+Deprecates the static methods on `Utf8` and `Utf16` and introduces
+extension methods to replace them.
+
+## 0.3.0-nullsafety.3
+
+Adds back in deprecated `allocate` and `free` to ease migration.
+These will be removed in the next release.
+
+This pre-release requires Dart `2.12.0-259.9.beta` or greater.
+
+## 0.3.0-nullsafety.1
+
+This pre-release requires Dart `2.12.0-259.8.beta` or greater.
+
+Note that this pre-release does _not_ work in Flutter versions containing Dart
+`2.12.0-260.0.dev` - `2.12.0-264.0.dev`.
+Using `Allocator.call` throws a `NoSuchMethodError` in these versions.
+See [Flutter Engine #23954](https://github.com/flutter/engine/pull/23954) for more info.
+
+## 0.3.0-nullsafety.0
+
+Changes `Utf8` and `Utf16` to extend `Opaque` instead of `Struct`.
+This means `.ref` is no longer available and `Pointer<Utf(..)>` should be used.
+See [breaking change #44622](https://github.com/dart-lang/sdk/issues/44622) for more info.
+
+Removes `allocate` and `free`.
+Instead, introduces `calloc` which implements the new `Allocator` interface.
+See [breaking change #44621](https://github.com/dart-lang/sdk/issues/44621) for more info.
+
+This pre-release requires Dart `2.12.0-265.0.dev` or greater.
+
+## 0.2.0-nullsafety.1
+
+Adds an optional named `length` argument to `Utf8.fromUtf8()`.
+
+## 0.2.0-nullsafety.0
+
+Pre-release (non-stable) release supporting null safety.
+Requires Dart 2.12.0 or greater.
+
+## 0.1.3
+
+Stable release incorporating all the previous dev release changes.
+
+Bump SDK constraint to `>= 2.6.0`.
+
+## 0.1.3-dev.4
+
+Bump SDK constraint to `>= 2.6.0-dev.8.2` which contains the new API of `dart:ffi`.
+
+## 0.1.3-dev.3
+
+Replace use of deprecated `asExternalTypedData` with `asTypedList`.
+
+## 0.1.3-dev.2
+
+Incorporate struct API changes, drop type argument of structs.
+
+## 0.1.3-dev.1
+
+* Adds top-level `allocate<T>()` and `free()` methods which can be used as a
+  replacement for the deprecated `Pointer.allocate<T>()` and `Pointer.free()`
+  members in `dart:ffi`.
+
+## 0.1.1+2
+
+* Expand readme
+
+## 0.1.1+1
+
+* Fix documentation link
+
+## 0.1.1
+
+* Add basic Utf16 support
+
+## 0.1.0
+
+* Initial release supporting Utf8

pkgs/ffi/LICENSE

@@ -0,0 +1,27 @@
+Copyright 2019, the Dart project authors. 
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+    * Redistributions of source code must retain the above copyright
+      notice, this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above
+      copyright notice, this list of conditions and the following
+      disclaimer in the documentation and/or other materials provided
+      with the distribution.
+    * Neither the name of Google LLC nor the names of its
+      contributors may be used to endorse or promote products derived
+      from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

pkgs/ffi/README.md

@@ -0,0 +1,11 @@
+[![Build Status](https://github.com/dart-lang/ffi/workflows/Dart%20CI/badge.svg)](https://github.com/dart-lang/ffi/actions?query=workflow%3A"Dart+CI")
+[![pub package](https://img.shields.io/pub/v/ffi.svg)](https://pub.dev/packages/ffi)
+[![package publisher](https://img.shields.io/pub/publisher/ffi.svg)](https://pub.dev/packages/ffi/publisher)
+
+Utilities for working with Foreign Function Interface (FFI) code, incl.
+converting between Dart strings and C strings encoded with UTF-8 and UTF-16.
+
+Please see the [API reference](https://pub.dev/documentation/ffi/latest/ffi/ffi-library.html) for more documentation and the [tests](https://github.com/dart-lang/ffi/tree/main/test) for example usage. 
+
+For additional details about Dart FFI (`dart:ffi`), see
+https://dart.dev/guides/libraries/c-interop.

pkgs/ffi/analysis_options.yaml

@@ -0,0 +1,6 @@
+include: package:lints/recommended.yaml
+
+analyzer:
+  language:
+    strict-casts: true
+    strict-inference: true

pkgs/ffi/example/main.dart

@@ -0,0 +1,18 @@
+import 'dart:ffi';
+
+import 'package:ffi/ffi.dart';
+
+void main() {
+  // Allocate and free some native memory with calloc and free.
+  final pointer = calloc<Uint8>();
+  pointer.value = 3;
+  print(pointer.value);
+  calloc.free(pointer);
+
+  // Use the Utf8 helper to encode zero-terminated UTF-8 strings in native memory.
+  final String myString = '😎👿💬';
+  final Pointer<Utf8> charPointer = myString.toNativeUtf8();
+  print('First byte is: ${charPointer.cast<Uint8>().value}');
+  print(charPointer.toDartString());
+  calloc.free(charPointer);
+}

pkgs/ffi/lib/ffi.dart

@@ -0,0 +1,8 @@
+// Copyright (c) 2019, the Dart project authors.  Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+export 'src/allocation.dart' show calloc, malloc;
+export 'src/arena.dart';
+export 'src/utf8.dart';
+export 'src/utf16.dart';