Nimgen is a helper for c2nim to simpilfy and automate the wrapping of C libraries.

Nimgen can be used to automate the process of manipulating C files so that c2nim can be run on them without issues. This includes adding/removing code snippets, removal of complex preprocessor definitions that c2nim doesn't yet comprehend and recursively running on #include files.

Installation

Nimgen can be installed via Nimble:

> nimble install https://github.com/genotrance/nimgen

This will download, build and install nimgen in the standard Nimble package location, typically ~/.nimble. Once installed, it can be run just like c2nim.

Usage

Nimgen is driven by a simple .cfg file that is read using the Nim parsecfg module. The sections of the file are described further below.

> nimgen package.cfg

A Nimble package for a library that is wrapped with nimgen will have the following:-

• The .cfg file that tells nimgen what exactly to do
• Nimgen defined as a dependency defined in the .nimble file
• Steps within the .nimble file to download the source code that is being wrapped

This way, the library source code doesn't need to get checked into the Nimble package and can evolve independently.

Nimble already requires Git so those commands can be assumed to be present to download source from a repository. Mercurial is also suggested but depends on the user. Downloading arbitrary files depends on the OS. For Linux, wget/curl can be assumed. On Windows, powershell can be used.

Capabilities & Limitations

Nimgen supports compiling in C/C++ sources as well as loading in dynamic libraries at this time. Support for static libraries (.a, .lib) are still to come.

To see examples of nimgen in action, the nimssl library is a good example of C code getting compiled in whereas nimbass is an example of linking with a dynamic library.

Nimgen only supports the gcc preprocessor at this time. Support for detecting and using other preprocessors is TBD.

Config file

[n.global]

output = name of the Nimble project once installed, also location to place generated .nim files

filter = string to identify and recurse into library .h files in #include statements and exclude standard headers

[n.include]

List of all directories, one per line, to include in the search path. This is used by:-

• The preprocessor for #include files
• Nimgen to find #include files that are recursively processed

Nimgen also adds {.passC.} declarations into the generated .nim files for these include paths if compiling source files directly.

[n.exclude]

List of all directories or files to exclude from all parsing. If an entry here matches any portion of a file, it is excluded from recursive processing.

[sourcefile]

The following keys apply to library source code and help with generating the .nim files.

recurse = find #include files and process them [default: false]

preprocess = run preprocessor (gcc -E) on file to remove #defines, etc. [default: false] - this is especially useful when c2nim doesn't support complex preprocessor usage

ctags = run ctags on file to filter out function definitions [default: false] - this requires the ctags executable and is an alternative to filter out preprocessor complexity

defines = pulls out simple #defines of ints, floats and hex values for separate conversion [default: false] - works only when preprocess or ctags is used and helps include useful definitions in generated .nim file

flags = flags to pass to the c2nim process in "quotes" [default: --stdcall]. --cdecl, --assumedef, --assumendef may be useful

Multiple entries for the all following keys are possible by appending any .string to the key. E.g. dynlib.win, compile.dir

compile = file or dir of files of source code to {.compile.} into generated .nim

dynlib = dynamic library to load at runtime for generated .nim procs

The following keys apply to library source code (before processing) and generated .nim files (after processing) and allow manipulating the files as required to enable successful wrapping.

create = create a file at exact location with contents specified

search = search string providing context for following prepend/append/replace directives

prepend = string value to prepend into file at beginning or before search

append = string value to append into file at the end or after search

replace = string value to replace search string in file

Feedback

Nimgen is a work in progress and any feedback or suggestions are welcome. It is hosted on GitHub with an MIT license so issues, forks and PRs are most appreciated.