Remove setup phase and usage of --no-sound-null-safety flag (#135, #137) (#164)

Co-authored-by: J-P Nurmi <[email protected]>

Author: mannprerak2

.github/workflows/test-package.yml

@@ -49,8 +49,6 @@ jobs:
         run: dart pub get
       - name: Install libclang-10-dev
         run: sudo apt-get install libclang-10-dev
-      - name: Setup ffigen
-        run: dart run ffigen:setup
       - name: Build test dylib
         run: cd test/native_test && dart build_test_dylib.dart && cd ../..
       - name: Run VM tests

CHANGELOG.md

@@ -1,3 +1,10 @@
+# 2.0.0-dev.3
+- Removed the usage of `--no-sound-null-safety` flag.
+
+# 2.0.0-dev.2
+- Removed setup phase for ffigen. Added new optional config key `llvm-lib`
+to specify path to `llvm/lib` folder.
+
 # 2.0.0-dev.1
 - Added support for passing and returning struct by value in functions.
 

README.md

@@ -36,13 +36,13 @@ typedef _dart_sum = int Function(int a, int b);
 ```
 ## Using this package
 - Add `ffigen` under `dev_dependencies` in your `pubspec.yaml`.
-- Setup for use (see [Setup](#Setup)).
+- Install LLVM (see [Installing LLVM](#installing-llvm)).
 - Configurations must be provided in `pubspec.yaml` or in a custom YAML file (see [configurations](#configurations)).
 - Run the tool- `dart run ffigen`.
 
 Jump to [FAQ](#faq).
 
-## Setup
+## Installing LLVM
 `package:ffigen` uses LLVM. Install LLVM (9+) in the following way.
 
 #### ubuntu/linux
@@ -83,6 +83,16 @@ The following configuration options are available-
 
 ```yaml
 output: 'generated_bindings.dart'
+```
+  </td>
+  </tr>
+  <tr>
+    <td>llvm-lib</td>
+    <td>Path to <i>llvm/lib</i> folder. Required if ffigen is unable to find this at default locations.</td>
+    <td>
+
+```yaml
+llvm-lib: '/usr/local/opt/llvm/lib'
 ```
   </td>
   </tr>
@@ -379,13 +389,12 @@ class ArrayHelper_CXFileUniqueID_data_level0 {
 2. Run `pub run ffigen`.
 
 ## Running Tests
-1. Run setup to build the LLVM wrapper - `pub run ffigen:setup`.
-2. Dynamic library for some tests also need to be built before running the examples.
+1. Dynamic library for some tests need to be built before running the examples.
   1. `cd test/native_test`.
   2. Run `dart build_test_dylib.dart`.
 
 Run tests from the root of the package with `pub run test`.
-
+> Note: If llvm is not installed in one of the default locations, tests may fail.
 ## FAQ
 ### Can ffigen be used for removing underscores or renaming declarations?
 Ffigen supports **regexp based renaming**, the regexp must be a

bin/setup.dart

@@ -15,6 +15,9 @@ ffigen:
   output: 'generated_bindings.dart'
   sort: true
 
+  # This is required if LLVM can't be found in default locations by ffigen.
+  # llvm-lib: '/usr/local/opt/llvm/lib'
+
   # Bash style Glob matching is also supported.
   # TODO(11): Globs dont work on windows if they begin with '.' or '..'.
   headers:

example/libclang-example/pubspec.yaml

@@ -2,34 +2,17 @@
 ## Table of Contents -
 1. [Overview](#overview)
 2. [LibClang](#LibClang)
-    1. [The Wrapper library](#The-Wrapper-library)
-    2. [Generation and Usage](#Generation-and-Usage)
-    3. [Bindings](#Bindings)
+    1. [Bindings](#Bindings)
 3. [Scripts](#scripts)
     1. [ffigen.dart](#ffigen.dart)
-    2. [setup.dart](#setup.dart)
 4. [Components](#components)
     1. [Config Provider](#Config-Provider)
     2. [Header Parser](#Header-Parser)
     3. [Code Generator](#Code-Generator)
 # Overview
 `package:ffigen` simplifies the process of generating `dart:ffi` bindings from C header files. It is simple to use, with the input being a small YAML config file. It requires LLVM (9+) to work. This document tries to give a complete overview of every component without going into too many details about every single class/file.
 # LibClang
-`package:ffigen` binds to LibClang using `dart:ffi` for parsing C header files. A wrapper library must be generated to use it, as `dart:ffi` currently [doesn't support structs by value](https://github.com/dart-lang/ffigen/issues/3).
-## The Wrapper library
-> Note: The wrapper is only needed because `dart:ffi` currently doesn't support Structs by value.
-
-The `wrapper.c` file consists of functions that wrap LibClang functions. Most of them simply convert structs by value to pointers. Except -
-- `clang_visitChildren_wrap` - The bindings for this function internally uses a **list** of **stack** for maintaining the supplied visitor functions. This is required because this function takes a function pointer which itself passes a struct by value. All this effort makes `clang_visitChildren_wrap` behave exactly like `clang_visitChildren`.
-## Generation and Usage
-The files needed for generating the wrapper are in `lib/src/clang_library`.
-> The `wrapper.def` file is only needed on windows because the symbols are otherwise hidden.
-
-The libclang wrapper can be _manually_ generated using `pub run ffigen:setup`. See [setup.dart](#setup.dart) for details.
-
-The generated file is placed in the project's `.dart_tool/ffigen` folder, the file name also specifies the ffigen version (E.g - `_v0_2_4_libclang_wrapper.dylib`), this helps ensure the correct wrapper is being used for its corresponding version.
-
-This dynamic library is then used by [Header Parser](#header-parser) for parsing C files.
+`package:ffigen` binds to LibClang using `dart:ffi` for parsing C header files. 
 ## Bindings
 The config file for generating bindings is `tool/libclang_config.yaml`. The bindings are generated to `lib/src/header_parser/clang_bindings/clang_bindings.dart`. These are used by [Header Parser](#header-parser) for calling libclang functions.
 # Scripts
@@ -38,19 +21,11 @@ This is the main entry point for the user-  `pub run ffigen`.
 - Command-line options:
     - `--verbose`: Sets log level.
     - `--config`: Specifies a config file.
-- `ffigen.dart` will first check if a dynamic library already exists and is up to date. If not, it tries to auto-create it. If that fails, user must excplicitly call [setup.dart](#setup.dart).
 - The internal modules are called by `ffigen.dart` in the following way:
+- `ffigen.dart` will try to find dynamic library in default locations. If that fails, the user must excplicitly specify location in ffigen's config under the key `llvm-lib`.
     - It first creates a `Config` object from an input Yaml file. This is used by other modules.
     - The `parse` method is then invoked to generate a `Library` object.
     - Finally, the code is generated from the `Library` object to the specified file.
-## setup.dart
-Used to generate the wrapper dynamic library. Users will need to explicitly call this if `pub run ffigen` is unable to auto-create the dynamic library.
-> `clang` must be on user's path for `setup.dart` to work.
-
-- Command-line options:
-    - `-I`: Specifies header includes.
-    - `-L`: Specifies library includes.
-- `setup.dart` generates the dynamic library to the project's `.dart_tool/ffigen` folder using `clang`.
 # Components
 ## Config Provider
 The Config Provider holds all the configurations required by other modules.