Skip to content

Commit 9c9ec1c

Browse files
dcharkesdcharkes
authored
Merge pull request #895 from dart-lang/merge-ffi-package
2 parents f38afa2 + 9c3fc4c commit 9c9ec1c

18 files changed

+1411
-0
lines changed

‎.github/workflows/ffi.yaml

+73
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
name: Dart CI
2+
3+
on:
4+
# Run on PRs and pushes to the default branch.
5+
push:
6+
branches: [main]
7+
paths:
8+
- '.github/workflows/ffi.yaml'
9+
- 'pkgs/ffi/**'
10+
pull_request:
11+
branches: [main]
12+
paths:
13+
- '.github/workflows/ffi.yaml'
14+
- 'pkgs/ffi/**'
15+
schedule:
16+
- cron: "0 0 * * 0"
17+
18+
env:
19+
PUB_ENVIRONMENT: bot.github
20+
21+
jobs:
22+
# Check code formatting and static analysis on a single OS (linux)
23+
# against Dart dev.
24+
analyze:
25+
runs-on: ubuntu-latest
26+
defaults:
27+
run:
28+
working-directory: pkgs/ffi/
29+
strategy:
30+
fail-fast: false
31+
matrix:
32+
sdk: [dev]
33+
steps:
34+
- uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11
35+
- uses: dart-lang/setup-dart@b64355ae6ca0b5d484f0106a033dd1388965d06d
36+
with:
37+
sdk: ${{ matrix.sdk }}
38+
- id: install
39+
name: Install dependencies
40+
run: dart pub get
41+
- name: Check formatting
42+
run: dart format --output=none --set-exit-if-changed .
43+
if: always() && steps.install.outcome == 'success'
44+
- name: Analyze code
45+
run: dart analyze --fatal-infos
46+
if: always() && steps.install.outcome == 'success'
47+
48+
# Run tests on a matrix consisting of two dimensions:
49+
# 1. OS: ubuntu-latest, (macos-latest, windows-latest)
50+
# 2. release channel: dev
51+
test:
52+
needs: analyze
53+
runs-on: ${{ matrix.os }}
54+
defaults:
55+
run:
56+
working-directory: pkgs/ffi/
57+
strategy:
58+
fail-fast: false
59+
matrix:
60+
# Add macos-latest and/or windows-latest if relevant for this package.
61+
os: [ubuntu-latest]
62+
sdk: [beta, dev]
63+
steps:
64+
- uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11
65+
- uses: dart-lang/setup-dart@b64355ae6ca0b5d484f0106a033dd1388965d06d
66+
with:
67+
sdk: ${{ matrix.sdk }}
68+
- id: install
69+
name: Install dependencies
70+
run: dart pub get
71+
- name: Run VM tests
72+
run: dart test --platform vm
73+
if: always() && steps.install.outcome == 'success'

‎pkgs/ffi/.gitignore

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
.dart_tool
2+
.packages
3+
pubspec.lock

‎pkgs/ffi/AUTHORS

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

‎pkgs/ffi/CHANGELOG.md

+146
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
## 2.1.1
2+
3+
- Require Dart 3.3.0 or greater.
4+
- Migrate `elementAt` use to `operator +`.
5+
6+
## 2.1.0
7+
8+
- Require Dart 3.0.0 or greater.
9+
- Expose native equivalent to `free` (`nativeFree`) from `malloc` and
10+
`calloc` allocators.
11+
12+
## 2.0.2
13+
14+
- Fixed a typo in a doc comment.
15+
- Added package topics to the pubspec file.
16+
17+
## 2.0.1
18+
19+
- Only zero out memory on successful allocation on Windows.
20+
- Upgrade test dev dependency.
21+
22+
## 2.0.0
23+
24+
- Switch Windows memory allocation to use `CoTaskMemAlloc` and `CoTaskMemFree`,
25+
which will enable support for `NativeFinalizer`.
26+
- Require Dart 2.17.0 or greater.
27+
28+
## 1.2.1
29+
30+
Revert added common C integer types as ABI-specific integers.
31+
Instead, these are available in Dart 2.17.
32+
33+
## 1.2.0 (retracted)
34+
35+
This release requires Dart `2.16.0` or greater.
36+
37+
## 1.2.0-dev.0
38+
39+
Added common C integer types as ABI-specific integers. These common C integer
40+
types will make their way into `dart:ffi` in 2.17 and be deprecated from this
41+
package. Having them in this package enables using them in Dart 2.16.
42+
43+
This pre-release requires Dart `2.16.0-118.0.dev` or greater.
44+
45+
## 1.1.2
46+
47+
Fixed unhandled exception in `withZoneArena` (#107).
48+
49+
## 1.1.1
50+
51+
Adds a sanity check to `Pointer<Utf8>` and `Pointer<Utf16>` extension methods
52+
that receiver is not `nullptr`.
53+
54+
## 1.1.0
55+
56+
Adds the `arena` allocator.
57+
58+
Moves from static analysis with lints in package:pedantic to package:lints.
59+
60+
## 1.0.0
61+
62+
Bumping the version of this package to `1.0.0`.
63+
64+
Removes all deprecated methods, use `0.3.0-nullsafety.3` for migration.
65+
66+
## 0.3.1-nullsafety.0
67+
68+
Deprecates the static methods on `Utf8` and `Utf16` and introduces
69+
extension methods to replace them.
70+
71+
## 0.3.0-nullsafety.3
72+
73+
Adds back in deprecated `allocate` and `free` to ease migration.
74+
These will be removed in the next release.
75+
76+
This pre-release requires Dart `2.12.0-259.9.beta` or greater.
77+
78+
## 0.3.0-nullsafety.1
79+
80+
This pre-release requires Dart `2.12.0-259.8.beta` or greater.
81+
82+
Note that this pre-release does _not_ work in Flutter versions containing Dart
83+
`2.12.0-260.0.dev` - `2.12.0-264.0.dev`.
84+
Using `Allocator.call` throws a `NoSuchMethodError` in these versions.
85+
See [Flutter Engine #23954](https://github.com/flutter/engine/pull/23954) for more info.
86+
87+
## 0.3.0-nullsafety.0
88+
89+
Changes `Utf8` and `Utf16` to extend `Opaque` instead of `Struct`.
90+
This means `.ref` is no longer available and `Pointer<Utf(..)>` should be used.
91+
See [breaking change #44622](https://github.com/dart-lang/sdk/issues/44622) for more info.
92+
93+
Removes `allocate` and `free`.
94+
Instead, introduces `calloc` which implements the new `Allocator` interface.
95+
See [breaking change #44621](https://github.com/dart-lang/sdk/issues/44621) for more info.
96+
97+
This pre-release requires Dart `2.12.0-265.0.dev` or greater.
98+
99+
## 0.2.0-nullsafety.1
100+
101+
Adds an optional named `length` argument to `Utf8.fromUtf8()`.
102+
103+
## 0.2.0-nullsafety.0
104+
105+
Pre-release (non-stable) release supporting null safety.
106+
Requires Dart 2.12.0 or greater.
107+
108+
## 0.1.3
109+
110+
Stable release incorporating all the previous dev release changes.
111+
112+
Bump SDK constraint to `>= 2.6.0`.
113+
114+
## 0.1.3-dev.4
115+
116+
Bump SDK constraint to `>= 2.6.0-dev.8.2` which contains the new API of `dart:ffi`.
117+
118+
## 0.1.3-dev.3
119+
120+
Replace use of deprecated `asExternalTypedData` with `asTypedList`.
121+
122+
## 0.1.3-dev.2
123+
124+
Incorporate struct API changes, drop type argument of structs.
125+
126+
## 0.1.3-dev.1
127+
128+
* Adds top-level `allocate<T>()` and `free()` methods which can be used as a
129+
replacement for the deprecated `Pointer.allocate<T>()` and `Pointer.free()`
130+
members in `dart:ffi`.
131+
132+
## 0.1.1+2
133+
134+
* Expand readme
135+
136+
## 0.1.1+1
137+
138+
* Fix documentation link
139+
140+
## 0.1.1
141+
142+
* Add basic Utf16 support
143+
144+
## 0.1.0
145+
146+
* Initial release supporting Utf8

‎pkgs/ffi/LICENSE

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

‎pkgs/ffi/README.md

+11
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
[![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")
2+
[![pub package](https://img.shields.io/pub/v/ffi.svg)](https://pub.dev/packages/ffi)
3+
[![package publisher](https://img.shields.io/pub/publisher/ffi.svg)](https://pub.dev/packages/ffi/publisher)
4+
5+
Utilities for working with Foreign Function Interface (FFI) code, incl.
6+
converting between Dart strings and C strings encoded with UTF-8 and UTF-16.
7+
8+
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.
9+
10+
For additional details about Dart FFI (`dart:ffi`), see
11+
https://dart.dev/guides/libraries/c-interop.

‎pkgs/ffi/analysis_options.yaml

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
include: package:lints/recommended.yaml
2+
3+
analyzer:
4+
language:
5+
strict-casts: true
6+
strict-inference: true

‎pkgs/ffi/example/main.dart

+18
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
import 'dart:ffi';
2+
3+
import 'package:ffi/ffi.dart';
4+
5+
void main() {
6+
// Allocate and free some native memory with calloc and free.
7+
final pointer = calloc<Uint8>();
8+
pointer.value = 3;
9+
print(pointer.value);
10+
calloc.free(pointer);
11+
12+
// Use the Utf8 helper to encode zero-terminated UTF-8 strings in native memory.
13+
final String myString = '😎👿💬';
14+
final Pointer<Utf8> charPointer = myString.toNativeUtf8();
15+
print('First byte is: ${charPointer.cast<Uint8>().value}');
16+
print(charPointer.toDartString());
17+
calloc.free(charPointer);
18+
}

‎pkgs/ffi/lib/ffi.dart

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

0 commit comments

Comments
 (0)