Initial generator: functions, structs, enums

.gitignore

@@ -1,6 +1,32 @@
 # See https://dart.dev/guides/libraries/private-files
 
-# Files and directories created by pub
+# Files and directories created by pub.
 .dart_tool/
 .packages
 pubspec.lock
+
+# Directory created by dartdoc.
+# If you don't generate documentation locally you can remove this line.
+doc/api/
+
+# Avoid committing generated Javascript files:
+*.dart.js
+*.info.json      # Produced by the --dump-info flag.
+*.js             # When generated by dart2js. Don't specify *.js if your
+                 # project includes source files written in JavaScript.
+*.js_
+*.js.deps
+*.js.map
+
+# Generated shared libraries.
+*.so
+*.so.*
+*.dylib
+*.dll
+
+# Directory for quick experiments.
+experiments/
+
+# Files generated by tests for debugging purposes.
+test/debug_generated/*
+!test/debug_generated/readme.md

AUTHORS

@@ -4,3 +4,5 @@
 #   Name/Organization <email address>
 
 Google LLC
+
+Prerak Mann <[email protected]>

CHANGELOG.md

@@ -0,0 +1,5 @@
+# 0.1.0
+- Initial release supporing binding generation for Functions, Structs, Enums.
+- Glob support for specifying headers.
+- HeaderFilter - Include/Exclude declarations from specific header files.
+- Filters - Include/Exclude function, structs and enum declarations using Regexp or Name matching.

README.md

@@ -2,3 +2,69 @@
 
 Experimental generator for [FFI](https://dart.dev/guides/libraries/c-interop)
 bindings.
+
+## Example
+
+For some header file _example.h_:
+```C
+int sum(int a, int b);
+```
+Add configurations to Pubspec File:
+```yaml
+ffigen:
+  output: 'generated_bindings.dart'
+  headers:
+    - 'example.h'
+```
+Output (_generated_bindings.dart_).
+```dart
+DynamicLibrary _dylib;
+
+/// Initialises dynamic library
+void init(DynamicLibrary dylib) {
+  _dylib = dylib;
+}
+
+int sum(int a,int b) {
+  return _sum(a,b);
+}
+
+final _dart_sum _sum = _dylib.lookupFunction<_c_sum, _dart_sum>('sum');
+
+typedef _c_sum = Int32 Function(Int32 a,Int32 b);
+
+typedef _dart_sum = int Function(int a,int b);
+```
+## Using this package
+- clone/download this repository.
+- Build it (see [building](#building)).
+- Add this package as dev_dependency in your `pubspec.yaml`.
+- Configurations must be provided in the pubspec.yaml file under the key `ffigen` (or directly under a seperate yaml file which when u specify it passing `--config filename` when running the tool)
+- Run the tool- `pub run ffigen:generate`.
+
+## Building
+A dynamic library for a wrapper to libclang needs to be generated as it is used by the parser submodule.
+
+#### ubuntu/linux
+1. Install libclangdev - `sudo apt-get install libclang-dev`.
+2. `cd tool/wrapped_libclang`, then run `dart build.dart`.
+
+#### Windows
+1. Install Visual Studio with C++ development support.
+2. Install LLVM.
+3. `cd tool\wrapped_libclang`, then run `dart build.dart`.
+
+#### MacOS
+1. Install LLVM.
+2. `cd tool/wrapped_libclang`, then run `dart build.dart`.
+
+## Trying out examples
+1. `cd examples/<example_u_want_to_run>`, Run `pub get`.
+2. Run `pub run ffigen:generate`.
+
+## Running Tests
+Dynamic library for some tests need to be built before running the examples.
+1. `cd test/native_functions_test`.
+2. Run `dart build_test_dylib.dart`.
+
+Run tests from the root of the package with `pub run test`.

analysis_options.yaml

@@ -1 +1,19 @@
+# Copyright (c) 2020, 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.
+
 include: package:pedantic/analysis_options.yaml
+
+analyzer:
+  strong-mode:
+    implicit-casts: false
+    implicit-dynamic: false
+  errors:
+    omit_local_variable_types: ignore
+
+linter:
+  rules:
+    - directives_ordering
+    - prefer_final_fields
+    - prefer_final_locals
+    - prefer_final_in_for_each

bin/generate.dart

@@ -0,0 +1,176 @@
+// Copyright (c) 2020, 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.
+
+// Executable script to generate bindings for some C library.
+import 'dart:io';
+
+import 'package:args/args.dart';
+import 'package:ffigen/src/config_provider.dart';
+import 'package:ffigen/src/header_parser.dart' as parser;
+import 'package:logging/logging.dart';
+import 'package:yaml/yaml.dart' as yaml;
+
+var _logger = Logger('generate.dart');
+
+void main(List<String> args) {
+  // Parses the cmd args.
+  final result = getArgResults(args);
+
+  // Setup logging level and printing.
+  setupLogger(result);
+
+  // Create a config object.
+  final config = getConfig(result);
+
+  // Parse the bindings according to config object provided.
+  final library = parser.parse(config);
+
+  if (config.sort) {
+    library.sort();
+  }
+
+  // Generate file for the parsed bindings.
+  final gen = File(config.output);
+  library.generateFile(gen);
+  _logger.info('Finished, Bindings generated in ${gen?.absolute?.path}');
+}
+
+Config getConfig(ArgResults result) {
+  _logger.info('Running in ${Directory.current}');
+
+  if (result.wasParsed('config')) {
+    return getConfigFromCustomYaml(result['config'] as String);
+  } else {
+    return getConfigFromPubspec();
+  }
+}
+
+/// Extracts configuration from pubspec file.
+Config getConfigFromPubspec() {
+  final pubspecName = 'pubspec.yaml';
+  final configKey = 'ffigen';
+
+  final pubspecFile = File(pubspecName);
+
+  if (!pubspecFile.existsSync()) {
+    _logger.severe(
+        'Error: $pubspecName not found, please run this tool from the root of your package.');
+    exit(1);
+  }
+
+  // Casting this because pubspec is expected to be a YamlMap.
+
+  // Throws a [YamlException] if it's unable to parse the Yaml.
+  final bindingsConfigMap =
+      yaml.loadYaml(pubspecFile.readAsStringSync())[configKey] as yaml.YamlMap;
+
+  if (bindingsConfigMap == null) {
+    _logger.severe("Couldn't find an entry for '$configKey' in $pubspecName.");
+    exit(1);
+  }
+  return Config.fromYaml(bindingsConfigMap);
+}
+
+/// Extracts configuration from a custom yaml file.
+Config getConfigFromCustomYaml(String yamlPath) {
+  final yamlFile = File(yamlPath);
+
+  if (!yamlFile.existsSync()) {
+    _logger.severe('Error: $yamlPath not found.');
+    exit(1);
+  }
+
+  // Throws a [YamlException] if it's unable to parse the Yaml.
+  final bindingsConfigMap =
+      yaml.loadYaml(yamlFile.readAsStringSync()) as yaml.YamlMap;
+
+  return Config.fromYaml(bindingsConfigMap);
+}
+
+/// Parses the cmd line arguments.
+ArgResults getArgResults(List<String> args) {
+  final parser = ArgParser(allowTrailingOptions: true);
+
+  parser.addSeparator(
+      'FFIGEN: Generate dart bindings from C header files\nUsage:');
+  parser.addOption(
+    'config',
+    help: 'path to Yaml file containing configurations if not in pubspec.yaml',
+  );
+  parser.addOption(
+    'verbose',
+    abbr: 'v',
+    defaultsTo: 'info',
+    allowed: [
+      'all',
+      'fine',
+      'info',
+      'warning',
+      'severe',
+    ],
+  );
+  parser.addFlag(
+    'help',
+    abbr: 'h',
+    help: 'prints this usage',
+    negatable: false,
+  );
+
+  ArgResults results;
+  try {
+    results = parser.parse(args);
+
+    if (results.wasParsed('help')) {
+      print(parser.usage);
+      exit(0);
+    }
+  } catch (e) {
+    print(e);
+    print(parser.usage);
+    exit(1);
+  }
+
+  return results;
+}
+
+/// Sets up the logging level and printing.
+void setupLogger(ArgResults result) {
+  if (result.wasParsed('verbose')) {
+    switch (result['verbose'] as String) {
+      case 'all':
+        // Logs everything, the entire AST touched by our parser.
+        Logger.root.level = Level.ALL;
+        break;
+      case 'fine':
+        // Logs AST parts relevant to user (i.e those included in filters).
+        Logger.root.level = Level.FINE;
+        break;
+      case 'info':
+        // Logs relevant info for general user (default).
+        Logger.root.level = Level.INFO;
+        break;
+      case 'warning':
+        // Logs warnings for relevant stuff.
+        Logger.root.level = Level.WARNING;
+        break;
+      case 'severe':
+        // Logs severe warnings and errors.
+        Logger.root.level = Level.SEVERE;
+        break;
+    }
+    // Setup logger for printing (if verbosity was set by user).
+    Logger.root.onRecord.listen((record) {
+      print('${record.level.name.padRight(8)}: ${record.message}');
+    });
+  } else {
+    // Setup logger for printing (if verbosity was not set by user).
+    Logger.root.onRecord.listen((record) {
+      if (record.level.value > Level.INFO.value) {
+        print('  ${record.level.name.padRight(8)}: ${record.message}');
+      } else {
+        print(record.message);
+      }
+    });
+  }
+}

example/c_json/.gitignore

@@ -0,0 +1,11 @@
+# Files and directories created by pub.
+.dart_tool/
+.packages
+# Remove the following pattern if you wish to check in your lock file.
+pubspec.lock
+
+# Conventional directory for build outputs.
+build/
+
+# Directory created by dartdoc.
+doc/api/

example/c_json/README.md

@@ -0,0 +1,25 @@
+# cJson example
+
+Demonstrates generation of bindings for a C library called
+[cJson](https://github.com/DaveGamble/cJSON) and then using these bindings
+to parse some json.
+
+## Building the cJson dynamic library
+From the root of this repository -
+```
+cd third_party/cjson_library
+cmake .
+make
+```
+
+## Generating bindings
+At the root of this example (`example/c_json`), run -
+```
+pub run ffigen:generate
+```
+This will generate bindings in a file: [cjson_generated_bindings.dart](./cjson_generated_bindings.dart)
+
+## Running the example
+```
+dart main.dart
+```