Skip to content

Commit a18dd11

Browse files
authored
[ffigen] API docs (#3707)
1 parent 6fd87c3 commit a18dd11

23 files changed

Lines changed: 184 additions & 84 deletions

File tree

‎pkgs/ffigen/CHANGELOG.md‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,12 @@
11
## 22.1.0-wip
22

3-
- The YAML configuration format is deprecated and will be removed in a future release.
3+
- The YAML configuration format is deprecated and will be removed in a future
4+
release.
45
- Added `Input.appendCompilerOptions` to allow appending custom compiler
5-
options to default options instead of replacing them.
6+
options to default options instead of replacing them. Removed
7+
`defaultCompilerOpts` from the public API, since it is now redundant and was
8+
always a hack.
9+
- Remove internal details from the public API of `ImportedType`.
610
- Default to C++17 compiler options when C++ bindings are enabled.
711
- Preserve documentation comments on same-name typedefs when generating the
812
underlying type binding.

‎pkgs/ffigen/README.md‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -16,10 +16,10 @@ Rust. For more details, see https://dart.dev/guides/libraries/c-interop.
1616
FFIgen also supports calling ObjC code.
1717
For details see https://dart.dev/guides/libraries/objective-c-interop.
1818

19-
More FFIgen documentation can be found [here](doc/README.md).
19+
More FFIgen documentation can be found [here](https://github.com/dart-lang/native/tree/main/pkgs/ffigen/doc).
2020

2121
> [!NOTE]
22-
> The YAML configuration format is deprecated and will be removed in a future version. Please migrate to the programmatic Dart generator API. You can use the migration skill in [`skills/ffigen-migrate-yaml-to-dart`](skills/ffigen-migrate-yaml-to-dart) to automate the migration with an agent, but it also serves as good documentation if doing the migration manually.
22+
> The YAML configuration format is deprecated and will be removed in a future version. Please migrate to the programmatic Dart generator API. You can use the migration skill in [`skills/ffigen-migrate-yaml-to-dart`](https://github.com/dart-lang/native/tree/main/pkgs/ffigen/skills/ffigen-migrate-yaml-to-dart) to automate the migration with an agent, but it also serves as good documentation if doing the migration manually.
2323
2424
## Getting Started
2525

@@ -126,13 +126,13 @@ app has been created via `dart create ffigen_example`.
126126

127127
That's it! Run your app with `dart run` to see it in action!
128128

129-
The complete and runnable example can be found in [example/add](example/add).
129+
The complete and runnable example can be found in [example/add](https://github.com/dart-lang/native/tree/main/pkgs/ffigen/example/add).
130130

131131
## More Examples
132132

133-
The `code_asset` package contains [comprehensive examples](../code_assets/example)
133+
The `code_asset` package contains [comprehensive examples](https://github.com/dart-lang/native/tree/main/pkgs/code_assets/example)
134134
that showcase FFIgen. Additional examples that show how FFIgen can be used
135-
in different scenarios can also be found in the [example](example/) directory.
135+
in different scenarios can also be found in the [example](https://github.com/dart-lang/native/tree/main/pkgs/ffigen/example) directory.
136136

137137
## Requirements
138138

‎pkgs/ffigen/example/add/pubspec.yaml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ description: A simple end-to-end example showcasing FFIgen.
33
publish_to: none
44

55
environment:
6-
sdk: '>=3.8.0 <4.0.0'
6+
sdk: '>=3.10.0 <4.0.0'
77

88
dependencies:
99
code_assets: any

‎pkgs/ffigen/example/objective_c/pubspec.yaml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
name: objective_c_example
66

77
environment:
8-
sdk: '>=3.8.0 <4.0.0'
8+
sdk: '>=3.10.0 <4.0.0'
99

1010
dependencies:
1111
args: ^2.6.0

‎pkgs/ffigen/example/objective_c/tool/ffigen.dart‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -54,6 +54,6 @@ FfiGenerator getConfig([Uri? packageRoot]) {
5454
}
5555

5656
Future<void> main() async {
57-
Logger.root.level = Level.SEVERE;
57+
Logger.root.level = .SEVERE;
5858
await getConfig().generate(logger: Logger.root);
5959
}

‎pkgs/ffigen/example/simple/pubspec.yaml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
name: simple_example
66

77
environment:
8-
sdk: '>=3.8.0 <4.0.0'
8+
sdk: '>=3.10.0 <4.0.0'
99

1010
dependencies:
1111
ffi: ^2.0.1

‎pkgs/ffigen/example/swift/pubspec.yaml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
name: swift_example
66

77
environment:
8-
sdk: '>=3.8.0 <4.0.0'
8+
sdk: '>=3.10.0 <4.0.0'
99

1010
dependencies:
1111
args: ^2.6.0

‎pkgs/ffigen/lib/ffigen.dart‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@
1010
/// @docImport 'src/config_provider.dart';
1111
library;
1212

13-
export 'src/code_generator/imports.dart' show ImportedType, LibraryImport;
13+
export 'src/code_generator/imports.dart' show LibraryImport;
1414
export 'src/config_provider.dart'
1515
show
1616
BindingStyle,
@@ -36,7 +36,6 @@ export 'src/config_provider.dart'
3636
Version,
3737
Versions,
3838
YamlConfig,
39-
defaultCompilerOpts,
4039
importFromSymbolFile,
4140
importFromSymbolFiles,
4241
iosSdkPath,

‎pkgs/ffigen/lib/src/code_generator/imports.dart‎

Lines changed: 29 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,9 @@
22
// for details. All rights reserved. Use of this source code is governed by a
33
// BSD-style license that can be found in the LICENSE file.
44

5+
import 'package:meta/meta.dart';
6+
7+
import '../config_provider/public_ast.dart' as public_ast;
58
import '../context.dart';
69
import '../visitor/ast.dart';
710

@@ -22,7 +25,7 @@ class LibraryImport extends AstNode {
2225
const LibraryImport(
2326
this.name,
2427
this._importPath, {
25-
String? importPathWhenImportedByPackageObjC,
28+
@internal String? importPathWhenImportedByPackageObjC,
2629
}) : _importPathWhenImportedByPackageObjC =
2730
importPathWhenImportedByPackageObjC;
2831

@@ -36,6 +39,7 @@ class LibraryImport extends AstNode {
3639

3740
// The import path, which may be different if this library is being imported
3841
// into package:objective_c's generated code.
42+
@internal
3943
String importPath(bool generateForPackageObjectiveC) {
4044
if (!generateForPackageObjectiveC) return _importPath;
4145
return _importPathWhenImportedByPackageObjC ?? _importPath;
@@ -50,37 +54,34 @@ class LibraryImport extends AstNode {
5054

5155
/// An imported type which will be used in the generated code.
5256
class ImportedType extends Type {
53-
/// The [LibraryImport] representing the library where this type is defined.
54-
final LibraryImport libraryImport;
55-
56-
/// The Dart representation of the C type. Must be an FFI `NativeType` (e.g.
57-
/// `'Int64'`, `'Pointer<Void>'`, or the name of a `Struct`).
58-
final String cType;
57+
final public_ast.ImportedType _type;
5958

60-
/// The Dart representation of the type (e.g. `'int'`, `'double'`).
61-
final String dartType;
62-
63-
/// The type as it appears in native code (e.g. `'int64_t'` or `'time_t'`).
64-
final String nativeType;
65-
66-
/// An optional default value expression for this type when used as an
67-
/// optional parameter.
68-
final String? defaultValue;
59+
LibraryImport get libraryImport => _type.libraryImport;
60+
String get cType => _type.cType;
61+
String get dartType => _type.dartType;
62+
String get nativeType => _type.nativeType;
63+
String? get defaultValue => _type.defaultValue;
64+
bool get importedDartType => _type.importedDartType;
6965

70-
/// Whether the [dartType] is an import from the [libraryImport].
71-
///
72-
/// When `true`, [dartType] will be prefixed with the import prefix in
73-
/// generated Dart signatures.
74-
final bool importedDartType;
66+
public_ast.ImportedType get toPublic => _type;
7567

7668
ImportedType(
77-
this.libraryImport,
78-
this.cType,
79-
this.dartType,
80-
this.nativeType, {
81-
this.defaultValue,
82-
this.importedDartType = false,
83-
});
69+
LibraryImport libraryImport,
70+
String cType,
71+
String dartType,
72+
String nativeType, {
73+
String? defaultValue,
74+
bool importedDartType = false,
75+
}) : _type = public_ast.ImportedType(
76+
libraryImport,
77+
cType,
78+
dartType,
79+
nativeType,
80+
defaultValue: defaultValue,
81+
importedDartType: importedDartType,
82+
);
83+
84+
ImportedType.fromPublic(this._type);
8485

8586
@override
8687
String getCType(Context context) =>

‎pkgs/ffigen/lib/src/code_generator/type.dart‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ abstract class Type extends AstNode {
1818
/// Get base type for any type.
1919
///
2020
/// E.g int** has base [Type] of int.
21-
/// double[2][3] has base [Type] of double.
21+
/// `double[2][3]` has base [Type] of double.
2222
Type get baseType => this;
2323

2424
/// Get base Array type.

0 commit comments

Comments
 (0)