Futhark

Futhark consists of two components:

1. Øpir (or opir): A helper program compiled with libclang. It uses Clang to parse C headers and produces a JSON output containing all definitions with Nim-friendly types.
2. futhark module: Provides the importc macro. This macro reads the JSON output from Øpir and applies user-defined overrides (like rename or retype) before generating the final Nim definitions.

Futhark and Øpir cache their results, so subsequent compilations are as fast as using pre-generated Nim files.

Unlike tools like c2nim (which attempts to parse C manually) or nimterop (which uses treesitter), Futhark uses Clang.

By leveraging Clang, Futhark understands both C syntax and C semantics. This allows it to resolve macros and #ifdef statements automatically, providing the final definitions to the Nim translation process. This results in higher fidelity when wrapping complex C headers.

To distribute bindings without requiring users to have Futhark or Clang installed, use the outputPath option in the importc block. This allows you to check the generated .nim files into your version control system.

Recommended Pattern: Use a when defined(useFuthark) switch to allow users to either use your shipped generated.nim file or regenerate it using Futhark themselves.

Example Implementation:

when defined(useFuthark) or defined(useFutharkForExample):
  import futhark, os

  importc:
    outputPath currentSourcePath.parentDir / "generated.nim"
    path "<path to library>"
    "libfile.h"
else:
  include "generated.nim"

Notes:

• If outputPath is a file, use -d:futharkRebuild to update it when changes are made to the importc block.
• If outputPath is a folder, Futhark will store files with an appended hash for caching purposes.

Futhark generates code with when defined statements and numbered identifiers to ensure compatibility with pre-wrapped libraries and avoid collisions. If you want more readable output for documentation or manual inspection, you can control these behaviors using define switches.

Futhark is currently in beta. Users should be aware of the following limitations:

• No C++ support: It is designed for C.
• Macro limitations: It does not currently support function-style macros.
• Beta stability: Occasional bugs or hiccups may occur with unusual C syntax.

Futhark marks all C objects as {.pure, inheritable.}. This allows you to use standard Nim destructor patterns to manage C object lifecycles. To implement a destructor, define a =destroy procedure for a type that inherits from a Futhark-wrapped object.

Example:

type TAudioEngine = object of maEngine

proc `=destroy`(engine: var TAudioEngine) = 
  maEngineUninit(engine.addr)

type TAudioEngine = object of maEngine # maEngine is a type wrapped by Futhark

proc `=destroy`(engine: var TAudioEngine) = 
  maEngineUninit(engine.addr)

If you are building a library that must implement procedures defined in a C header, use the forward keyword within an importc block. This tells Futhark to generate exportc pragmas instead of importc, creating forward declarations that Nim expects to be implemented elsewhere.

Usage:

importc:
  forward "proc_to_forward"

Advanced usage with custom pragmas:

importc:
  forward "proc_to_forward", customPragma("Hello world"), used

Debugging: Use the -d:echoForwards flag to print the generated signatures (including argument names) to the terminal during compilation.

To add custom pragmas to any Futhark-generated output, add a pragmasCallback to your importc block.

Callback Signature: proc(name: string, kind: SymbolKind, pragmas: var seq[NimNode])

The pragmas sequence is pre-populated with existing pragmas; you can modify it to add, remove, or completely redefine the pragmas attached to a symbol (e.g., adding discardable to procedures).

importc:
  pragmasCallback myPragmaProc

proc myPragmaProc(name: string, kind: SymbolKind, pragmas: var seq[NimNode]) = 
  # implementation

To make C types more idiomatic in Nim (e.g., converting a raw pointer to an UncheckedArray), use the retype directive.

Syntax: retype <object>.<field>, <Nim type>

Note that <object> and <field> must be the renamed Nim identifiers, not the original C names.

Example: To change a C array field some_element* some_field to a Nim UncheckedArray:

retype some_object.some_field, ptr UncheckedArray[some_element]

If you need to redefine an entire object, you can define the type in Nim before the importc block. Futhark wraps its definitions in when declared(SomeType) guards, so your custom definition will take precedence. Warning: You must ensure your custom type matches the C memory layout exactly.

importc:
  retype my_struct.my_field, ptr UncheckedArray[cint]