hs-bindgen-1.0.0.0: known-issues.md

# Known Issues

Whenever we cut a `hs-bindgen` release, our goal is of course to release a
product without known bugs. However, this is not always practical: some bugs
have so little impact that holding up a release until they are fixed would be
counterproductive. We list these known issues in this file.

This file is bundled with each release, and is a record of which bugs are known
to be present in that specific release. Its purpose is to enable users to
quickly scan through and see if any are relevant to them. It does not replace
the [issue tracker][issue-tracker]: bugs should be reported and discussed there,
and the details of each bug can be found there also.

## Missing type class instances can result in invalid generated code

> https://github.com/well-typed/hs-bindgen/issues/2253
> https://github.com/well-typed/hs-bindgen/issues/786
> https://github.com/well-typed/hs-bindgen/issues/1621
> https://github.com/well-typed/hs-bindgen/issues/2200

Datatypes generated by `hs-bindgen` are equipped with a number of type class
instances. If an instance of class `C` for some type `B` depends on the `C`
instance for another type `A`, but that instance is missing, we might generate
invalid code (that fails to compile). The primary reason why `A` might not
have the instance is a hand-written binding specification.

## Return-by-value of const-struct results in invalid code

> https://github.com/well-typed/hs-bindgen/issues/1514

Related to #1515, but even more obscure: we generate invalid code for functions
that return a struct _by value_ which is _itself_ marked `const`:

```c
struct S { int x; };
const struct S f1();
```

Note that this `const` qualifier here is pointless anyway.

## Return-by-value of struct-of-const results in invalid code

> https://github.com/well-typed/hs-bindgen/issues/1515

We generate invalid code for functions that return a struct _by value_ where
that struct has _const_ fields:

```c
struct S { const int x; int y; };
struct S f1();
```

## Literate mode fails to detect changes in dependent C files

> https://github.com/well-typed/hs-bindgen/issues/1583

When using `hs-bindgen` in literate mode, bindings won't be re-generated when
the C headers have changed.

## Some parse failures are not printed

> https://github.com/well-typed/hs-bindgen/issues/1851

Trace messages for unnamed declarations that cannot be selected are lost in some
cases. In the following example, the reason that the declarations cannot be
selected (`long double` is not supported) is not shown.

```c
struct foo {
  struct {
     long double not_supported;
  } field;
};
```

## Generated bindings for undef-ed macros fail to compile

> https://github.com/well-typed/hs-bindgen/issues/1956

Bindings for a declaration that uses a macro that is later undefined still
use the macro and therefore fail to compile. Example:

```c
#define T int
void foo (T x);
#undef T
```

## Enums with a macro-defined underlying type are not reparsed

> https://github.com/well-typed/hs-bindgen/issues/2119

Given

```c
#define A int
enum E : A { enumerator };
```

we will use `CInt` rather than the `A` newtype as the enum's underlying type.

## Reparsing of some headers may fail

> https://github.com/well-typed/hs-bindgen/issues/2148

In `hs-bindgen`, parsing and initial analysis of the C code (memory layout etc.)
are offloaded to `clang`; we use `clang` both in "compile" and in "preprocess"
mode; the latter when we are "reparsing" C code to recover macro information. In
rare cases `clang` in "compile" mode succeeds where "preprocess" mode fails;
when this happens, you might see an error such as

```
We tried to run the clang executable to preprocess select macro invocations, but it failed to run.
```

## Selection might miss redeclared declarations

> https://github.com/well-typed/hs-bindgen/issues/2282

When, say, a `struct` declaration occurs _twice_ in a header (or its transitive
`#include`s), we only store one of the locations. Consequently, if a selection
predicate matches the _other_ location, the declaration might not be selected
and would be omitted from the generated bindings.

## Reparse range is sometimes inaccurate

> https://github.com/well-typed/hs-bindgen/issues/2286

In order to recover macro information, `hs-bindgen` needs to reparse
declarations; this process starts by asking `libclang` for the location of the
first and final token. Sometimes `libclang` reports these locations incorrectly;
we try to correct for this, but don't always succeed. When we don't succeed, we
will fail to recover macro information and fall back on the parse as `libclang`
itself previously reported it. This only happens in rare circumstances, and only
with macros with arguments.




[issue-tracker]: https://github.com/well-typed/hs-bindgen/issues