From 460b3be5d8ab2ac652c244c4cc3a37da87eebc23 Mon Sep 17 00:00:00 2001 From: Ganesh Viswanathan Date: Mon, 4 May 2020 12:01:05 -0500 Subject: [PATCH] Add change log --- CHANGES.md | 57 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 57 insertions(+) create mode 100644 CHANGES.md diff --git a/CHANGES.md b/CHANGES.md new file mode 100644 index 0000000..7c7eaf0 --- /dev/null +++ b/CHANGES.md @@ -0,0 +1,57 @@ +# Nimterop Change History + +## Version 0.5.0 + +This release introduces a new backend for wrapper generation dubbed `ast2` that leverages the Nim compiler AST and renderer. The new design simplifies feature development and already includes all the functionality of the legacy algorithm plus fixes for several open issues. + +The new backend can be leveraged with the `-f:ast2` flag to `toast` or `flags = "-f:ast2"` to `cImport()`. The legacy algorithm will be the default backend for this release but no new functionality or bugfixes are expected going forward. Usage of the legacy algorithm will display a *deprecated* hint to encourage users to test their wrappers with `-f:ast2` and remove any overrides that the new algorithm supports. + +Version 0.6.0 of Nimterop will make `ast2` the default backend and the legacy algorithm will be removed altogether. + +https://github.com/nimterop/nimterop/compare/v0.4.4...v0.5.0 + +### Breaking changes + +- Nimterop now skips generating the `{.header.}` pragma by default in non-dynlib mode. This skips the header file `#include` in the generated code and allows creation of wrappers that do not require presence of the header during compile time. There are cases where this will not work so the `--includeHeader | -H` flag is available to revert to the legacy behavior when required. This change applies to both `ast2` and the legacy backend so if an existing wrapper breaks, test it with `-H` to see if it starts working again. #169 + +- Nimterop defaulted to C++ mode for preprocessing and tree-sitter parsing in all cases unless explicitly informed to use C mode. This has been changed and is now detected based on the file extension. This means some existing wrappers could break since they might contain C++ code or `#include ` which do not work in C mode. Explicitly setting `mode = "cpp"` or `-mcpp` should fix such issues. #176 + +- Enums were originally being mapped to `distint int` - this has been changed to `distinct cint` since the sizes are incorrect on 64-bit and is especially noticeable when types or unions have enum fields. + +- `static inline` functions are no longer wrapped by the legacy backend. The `ast2` backend correctly generates wrappers for such functions but they are only generated when `--includeHeader | -H` is in effect. This is because such functions do not exist in the binary and can only be referenced when the header is compiled in. + +- Support for Nim v0.19.6 has been dropped and the test matrix now covers v0.20.2, v1.0.6, v1.2.0 and devel. + +### New functionality + +- `ast2` includes support for various C constructs that were issues with the legacy backend. These changes should reduce the reliance on `cOverride()` and existing wrappers should attempt to clean up such sections where possible. + - N-dimensional arrays and pointers - #54 + - Synomyms for types - #74 + - Varargs support - #76 + - Nested structs, unions and enums - #137 #147 + - Forward declarations of types - #148 + - Nested function pointers - #155 #156 + - Various enum fixes - #159 #171 + - Map `int arr[]` to `arr: UncheckedArray[cint]` - #174 + +- `ast2` also includes an advanced expression parser that can reliably handle constructs typically seen with `#define` statements and enumeration values: + - Integers + integer like expressions (hex, octal, suffixes) + - Floating point expressions + - Strings and character literals, including C's escape characters + - Math operators `+ - / *` + - Some Unary operators `- ! ~` + - Any identifiers + - C type descriptors `int char` etc + - Boolean values `true false` + - Shift, cast, math or sizeof expressions + - Most type coercions + +- Wrappers can now point to an external plugin file with `cPluginPath()` instead of having to declaring plugins inline with `cPlugin()`. This allows multiple wrappers to share the same plugin. #181 + +- `cImport()` adds support for importing multiple headers in a single call - this enables support for libraries that have many header files that include shared headers and typically cannot be imported in multiple `cImport()` calls since it results in duplicate symbols. Calling `toast` with multiple headers uses the same algorithm. + +- `ast2` now creates Nim doc comments instead of reqular comments which get rendered when the wrapper is run through `nim doc` or the `buildDocs()` API. #197 + +- `toast` now includes `--replace | -G` to manipulate identifier names beyond `--prefix` and `--suffix`. `-G:X=Y` replaces X with Y and `-G:@_[_]+=_` replaces multiple `_` with a single instance using the `@` prefix to enable regular expressions. + +- Nimterop is now able to detect Nim configuration of projects and can better handle cases where defaults such as `nimcacheDir` or `nimblePath` are overridden. This especially enables better interop with workflows that do not depend on Nimble. #151 #153