dart_ast_json

Dart FFI binding generator for any LLVM Clang JSON AST dump

Dependencies

• build_runner
• code_gen
• LLVM Clang >10.* to produce the AST-dump in JSON

Installing clang on MacOS

brew install llvm

Other great MacOS, iOS related guides

• A great post on installing llvm.
• How to get your framework dependency to run with LLVM you've just installed

Create the dumps

# dump json
clang-10 -Isomewhere/include -c main.c -o build/target.o -Xclang -ast-dump=json -fsyntax-only > project_os_arch.json

# dump record memory layout
clang-10 -Isomewhere/include -c main.c -o build/target.o -Xclang -fdump-record-layouts > project_os_arch.layout

# check for padding optimization
clang-10 -Isomewhere/include -c main.c -o build/target.o -Wpadded

Also useful: -fsave-optimization-record

Current status WIP

• Working on examples, tests and workarounds
• Waiting for the dart team to provide a offset mechanism to solve alignment/padding issues.

Caveats

The generated JSON will be different per ARCH and OS

Grouping commonalities between generated ARCH and OSs is still a manual task.

Dart FFI Limitations

0. Nested structs/unions/etc.
1. Pass by value e.g. Struct/Union/Enum
2. extern C required for C++ code due to name mangling
3. Packed structs
4. No bitfields, DIY bitmasking
5. No union
6. No support for non scalar struct fields, e.g. int meh[2];
7. And more...

Workarounds

0. Each struct depends on the largest member (e.g. another struct), to determine its alignment and padding, use -Wpadded in clang
1. Just don't, especially for big padded structs, don't overflow the stack.
2. Just do it.
3. Clang has a -Wpadded that could provide clues on how to spatially optimize (instead of packing)
4. Don't. Instead use a machine word sized integer, and provide masking where necessary; explicit is better.
5. Use Struct from dart's FFI, but use a single memory location, e.g. a Pointer<Void> as the only field.
6. The workaround is to repeatedly state the field @Int32 int meh_0, meh_1; // etc. to determine the proper alignment and padding. Yuck.

Run program

0. Add a build.yaml with the necessary configuration, see the examples
1. Compile your C/C++ code for your ARCH and OS, with clang, and enable -dump-ast=json
2. Capture the JSON output in a file, <project>_<os>_arch.json, e.g. miniaudio_android_arm64.py. Place the file generated by adding -ast-dump=json file in your lib/src. Then run:

pub run build_runner build

Struct alignment & padding

• Alignment
• The lost art of Structure Packing
• Padding in compilers

Handy commands

Sort out types in the AST JSON:

grep desugaredQualType web/miniaudio.json | grep -v __attr | sed -e 's/^[ \t]*//' | sort | uniq | less

Links

• Pre-processor directives (macro definitions) for ARCH
• Boost lib for C pre-processor directives for arch/os detection
• Moar