"--blocklist-file" option doesn't work as advertized

[mathieupoirier]

Hi,

I am trying to generate Rust bindings for headers found in the Xen project. Some files, like xenctrl.h include system headers that I do not want to generate bindings for. I am using this script to call bindgen.

Reading the documentation option --blocklist-file should do exactly what I want but system files unistd.h and stdio.h are parsed by bindgen, which generates errors due to macros such as __attribute_malloc__. I also tried using --no-include-path-detection which also doesn't seem to work in accordance to the documentation.

I am using bindgen 0.65.1

What am I doing wrong?

Thanks,
Mathieu

[pvdrz]

Hey, so I did a quick check with a header that only has #include <unistd.h> and I think what's going on is that blocklist-* methods are non transitive (which is documented), meaning that anything included by unistd.h from other files will not be blocklisted.

To expand a little bit further, if what you want is only include items from your input headers you'd have to use --allowlist-file instead, which would include only the items on the files you pass to it and any dependency they have. So if for example, one of these were to use FILE it would include FILE from stdio.h too. You can disable those transitive dependencies by using --no-recursive-allowlist which would only allow items in the files you explicitly mentioned.

[mathieupoirier]

Hi Christian,

First, just to make sure we are looking at the same thing, can you point out where in the documentation it is mentionned that blocklist-* is non transitive?

Second, I experimented with --allowlist-file using a very simple setup made of 3 files: file1.h, file2.h and file_list.h.

Scenario 1:
$ bindgen file1.h --allowlist-file=file1.h -o bindings.rs
Works as expected, i.e I only see a single definition in bindings.rs.

Scenario 2:
$ bindgen /path/to/headers/file1.h --allowlist-file=file1.h -o bindings.rs
Doesn't work at all. The resulting bindings.rs file is empty.

Scenario 3:
$ bindgen file_list.h --allowlist-file=file1.h -o bindings.rs -- -I/path/to/headers/
Same as above, i.e the resulting bindings.rs is empty.

I had to do the following to get the output I was looking for:
bindgen file_list.h --allowlist-file=/path/to/headers/file1.h --allowlist-file=/path/to/headers/file2.h -o bindings.rs -- -I/path/to/headers/

Is there a way to use --allowlist-file without having to specify absolute path? Once again, pointing me to the right documentation would likely go a long way.

Many thanks for the help.

[pvdrz]

Hi Christian,

Hi Mathieu! 👋

First, just to make sure we are looking at the same thing, can you point out where in the documentation it is mentionned that blocklist-* is non transitive?

It is not stated explicitly. The documentation for allowlist_file mentions its transitive property and the blocklist_file does not. One could infer that the latter won't be transitive but I agree, it should be explicitly stated.

Second, I experimented with --allowlist-file using a very simple setup made of 3 files: file1.h, file2.h and file_list.h.

Scenario 1: $ bindgen file1.h --allowlist-file=file1.h -o bindings.rs Works as expected, i.e I only see a single definition in bindings.rs.

Scenario 2: $ bindgen /path/to/headers/file1.h --allowlist-file=file1.h -o bindings.rs Doesn't work at all. The resulting bindings.rs file is empty.

As the allowlist_file documentation states, you should check the regular expression arguments section. In a nutshell, bindgen tries to match the regex to the whole identifier. In this case file1.h doesn't match /path/to/headers/file1.h. You need to use .*file1.h to get the desired effect. This is done because in all the other use cases of allowlist_* users most likely want to allow an item based on its complete name (e.g. Allowlisting the FILE type should only allow FILE and not _IO_FILE or stuff like that) and it was kept this way for consistency.

Scenario 3: $ bindgen file_list.h --allowlist-file=file1.h -o bindings.rs -- -I/path/to/headers/ Same as above, i.e the resulting bindings.rs is empty.

I had to do the following to get the output I was looking for: bindgen file_list.h --allowlist-file=/path/to/headers/file1.h --allowlist-file=/path/to/headers/file2.h -o bindings.rs -- -I/path/to/headers/

Is there a way to use --allowlist-file without having to specify absolute path? Once again, pointing me to the right documentation would likely go a long way.

Yeah this is just consequence of the "match the whole path" rule. Prepending .* to the name of the file should give you the desired effect.

Many thanks for the help.

Thanks for your comments. If you have any suggestions on how this could be improved I'd be happy to read them. For now I'll update the blocklist_* documentation mentioning it's lack of transitivity and probably add an extra comment on allowlist_file and blocklist_file mentioning that they always try to match the whole path.

[mathieupoirier]

Everything you wrote above works as you said. Very much appreciated.