kylemayes/clang-sys

Rust bindings for libclang.

clang-sys

Rust bindings for libclang.

If you are interested in a somewhat idiomatic Rust wrapper for these bindings, see clang-rs.

Released under the Apache License 2.0.

Documentation

Note that the documentation on https://docs.rs for this crate assumes usage of the runtime Cargo feature as well as the Cargo feature for the latest supported version of libclang (e.g., clang_16_0), neither of which are enabled by default.

Due to the usage of the runtime Cargo feature, this documentation will contain some additional types and functions to manage a dynamically loaded libclang instance at runtime.

Due to the usage of the Cargo feature for the latest supported version of libclang, this documentation will contain constants and functions that are not available in the oldest supported version of libclang (3.5). All of these types and functions have a documentation comment which specifies the minimum libclang version required to use the item.

Supported Versions

To target a version of libclang, enable a Cargo features such as one of the following:

• clang_3_5 - requires libclang 3.5 or later
• clang_3_6 - requires libclang 3.6 or later
• etc...
• clang_15_0 - requires libclang 15.0 or later
• clang_16_0 - requires libclang 16.0 or later

If you do not enable one of these features, the API provided by libclang 3.5 will be available by default.

Note: If you are using Clang 15.0 or later, you should enable the clang_15_0 feature or a more recent version feature. Clang 15.0 introduced a breaking change to the EntityKind enum which resulted in a mismatch between the values returned by libclang and the values for EntityKind defined by this crate in previous versions.

Dependencies

By default, this crate will attempt to link to libclang dynamically. In this case, this crate depends on the libclang shared library (libclang.so on Linux, libclang.dylib on macOS, libclang.dll on Windows). If you want to link to libclang statically instead, enable the static Cargo feature. In this case, this crate depends on the LLVM and Clang static libraries. If you don't want to link to libclang at compiletime but instead want to load it at runtime, enable the runtime Cargo feature.

These libraries can be either be installed as a part of Clang or downloaded here.

Note: The downloads for LLVM and Clang 3.8 and later do not include the libclang.a static library. This means you cannot link to any of these versions of libclang statically unless you build it from source.

Versioned Dependencies

This crate supports finding versioned instances of libclang.so (e.g.,libclang-3.9.so). In the case where there are multiple instances to choose from, this crate will prefer instances with higher versions. For example, the following instances of libclang.so are listed in descending order of preference:

1. libclang-4.0.so
2. libclang-4.so
3. libclang-3.9.so
4. libclang-3.so
5. libclang.so

Note: On BSD distributions, versioned instances of libclang.so matching the pattern libclang.so.* (e.g., libclang.so.7.0) are also included.

Note: On Linux distributions when the runtime features is enabled, versioned instances of libclang.so matching the pattern libclang.so.* (e.g., libclang.so.1) are also included.

Environment Variables

The following environment variables, if set, are used by this crate to find the required libraries and executables:

• LLVM_CONFIG_PATH (compiletime) - provides a full path to an llvm-config executable (including the executable itself [i.e., /usr/local/bin/llvm-config-8.0])
• LIBCLANG_PATH (compiletime) - provides a path to a directory containing a libclang shared library or a full path to a specific libclang shared library
• LIBCLANG_STATIC_PATH (compiletime) - provides a path to a directory containing LLVM and Clang static libraries
• CLANG_PATH (runtime) - provides a path to a clang executable

Linking

Dynamic

libclang shared libraries will be searched for in the following directories:

• the directory provided by the LIBCLANG_PATH environment variable
• the bin and lib directories in the directory provided by llvm-config --libdir
• the directories provided by LD_LIBRARY_PATH environment variable
• a list of likely directories for the target platform (e.g., /usr/local/lib on Linux)
• macOS only: the toolchain directory in the directory provided by xcode-select --print-path

On Linux, running an executable that has been dynamically linked to libclang may require you to add a path to libclang.so to the LD_LIBRARY_PATH environment variable. The same is true on OS X, except the DYLD_LIBRARY_PATH environment variable is used instead.

On Windows, running an executable that has been dynamically linked to libclang requires that libclang.dll can be found by the executable at runtime. See here for more information.

Static

The availability of llvm-config is not optional for static linking. Ensure that an instance of this executable can be found on your system's path or set the LLVM_CONFIG_PATH environment variable. The required LLVM and Clang static libraries will be searched for in the same way as shared libraries are searched for, except the LIBCLANG_STATIC_PATH environment variable is used in place of the LIBCLANG_PATH environment variable.

Runtime

The clang_sys::load function is used to load a libclang shared library for use in the thread in which it is called. The clang_sys::unload function will unload the libclang shared library. clang_sys::load searches for a libclang shared library in the same way one is searched for when linking to libclang dynamically at compiletime.

clang-sys's Issues

bindgen fails to load libclang.dll

From rust-lang/rust-bindgen#1276

Why can't bindgen find libclang.dll?

D:\3rdparty\reaper_extension_sdk\jmde>bindgen reaper_plugin_functions.h -o reaper.rs
thread 'main' panicked at 'Unable to find libclang: "the `libclang` shared libra
ry at D:\\Program Files\\LLVM\\bin\\libclang.dll could not be opened: %1 is not
a valid Win32 application. (os error 193)"', libcore\result.rs:945:5
stack backtrace:
   0: <unknown>
   1: <unknown>
   2: <unknown>
   3: <unknown>
   4: <unknown>
   5: <unknown>
   6: <unknown>
   7: <unknown>
   8: <unknown>
   9: <unknown>
  10: <unknown>
  11: <unknown>
  12: <unknown>
  13: <unknown>
  14: BaseThreadInitThunk
  15: RtlInitializeExceptionChain
  16: RtlInitializeExceptionChain

Btw, the file "D:\Program Files\LLVM\bin\libclang.dll" exists and has version 4.0.0.0.
An earlier version of bindgen cli was working without problems on this system.

llvm-config --shared-mode not supported

Build fails if static clang is used with dynamic llvm.

llvm-config --libs gives libs specific to its own type of build,

• i.e. -lLLVM-4 for dynamic build (sytem-wide LLVM*.so) or
• -lLLVMLTO -lLLVMPasses -lLLVMObjCARCOpts -lLLVMSymbolize etc. for lib*.a.

You can check llvm-config --shared-mode to know which one LLVM was built for.
If you'd rather force static linking, then use llvm-config --link-static --libs

libclang.so.1 not found on Debian

On Debian 8.5, it looks a lot like #28

The clang lib is /usr/lib/llvm-3.5/lib/libclang.so.1, but I had to create a link named libclang.so to get it to compile.

Error message follow:

Build failed, waiting for other jobs to finish...
error: failed to compile `bindgen v0.18.0`, intermediate artifacts can be found at `/tmp/cargo-install.7B4EzkrL0K9o`

Caused by:
  failed to run custom build command for `clang-sys v0.7.2`
process didn't exit successfully: `/tmp/cargo-install.7B4EzkrL0K9o/release/build/clang-sys-66118395f506ca26/build-script-build` (exit code: 101)
--- stderr
thread 'main' panicked at 'could not find libclang.so, set the LIBCLANG_PATH environment variable to a path where libclang.so can be found', /home/tatref/.cargo/registry/src/github.com-1ecc6299db9ec823/clang-sys-0.7.2/build.rs:42
note: Run with `RUST_BACKTRACE=1` for a backtrace.

It seems that the version I'm using should be clear of this bug?

static build fail

https://travis-ci.org/crabtw/rust-bindgen/jobs/132283528

Proposal: Load libclang on runtime

Some users like me can't get working clang-sys linking to libclang and the only way to get it working was loading it dynamically using dlopen and it's friends, we could mantain two versions of the library like x11-rs does, one linked (x11) and one loading the library at runtime (x11-dl).

Sorry if my english isn't good, i speak spanish :)

Use enum_primitive

It would easier to convert from the c types to the rust enums.
https://github.com/andersk/enum_primitive-rs

Non informative error message when libclang is 32 bits

On fedora the load_manually function looks for clang in /usr/lib instead of /usr/lib64 which makes the ELF not load. Instead of getting the error message:
wrong ELF class: ELFCLASS32
You get the unhelpful message:
the ``libclang`` shared library could not be opened.

rustc version:
rustc 1.17.0-nightly (0f34b532a 2017-02-21) binary: rustc commit-hash: 0f34b532af590d25e9178f87c620931dd671cc2e commit-date: 2017-02-21 host: x86_64-unknown-linux-gnu release: 1.17.0-nightly LLVM version: 3.9

Regression when finding libraries.

See rust-lang/rust-bindgen#1411.

Continuous build

You could add a travis build to your crate.

Versioned libclang.so on Ubuntu

On Ubuntu 16.04, the clang packages (at least libclang-3.9-dev) don't contain libclang.so, but only a versioned shared library. This versioned library is called libclang-3.9.so. It might be useful to, in addition to searching for versioned libs that have the version appended, also search for the Ubuntu-style versioned library.

custom static build fails, because build uses llvm-config --libs without using --libdir

I built static llvm and clang, and did make install to custom, non-standard directories.

Static build.rs of clang-sys get_llvm_libraries() only queries llvm-config --libs, but this output just lists lib names (-lLLVMLTO -lLLVMPasses) and lacks any -L flags required to find them.

This fixes the build for me:

print!("-L {} ", run_llvm_config(&["--libdir"]).expect("libdir"));

Is LIBCLANG_STATIC really useful?

since you can use the cargo feature.
cc @nox

All functions in Functions should be marked as unsafe

Everything in the struct Functions comes from FFI, and none of these functions should be considered safe.

Test MacOS

Could someone test llvm-config --libdir on MacOS?

Steal .travis.yml from rust-bindgen

ld: library not found for -lclang.dy

I'm trying to use clang-sys on macOS as follows:

clang-sys = { version = "0.24.0", features = ["clang_6_0"] }

The build fails with:

error: linking with `cc` failed: exit code: 1
  |
  = note: "cc" "-m64" "-L" "$HOME/.rustup/toolchains/nightly-x86_64-apple-darwin/lib/rustlib/x86_64-apple-darwin/lib" "$PROJECT/target/debug/deps/test_main-f36430e3bd34d135.1y16o1qfye96o7m0.rcgu.o" "$PROJECT/target/debug/deps/test_main-f36430e3bd34d135.2339ye2qsut5jzf1.rcgu.o" "$PROJECT/target/debug/deps/test_main-f36430e3bd34d135.2xs38k3nu4oe9uo6.rcgu.o" "$PROJECT/target/debug/deps/test_main-f36430e3bd34d135.3fiyi1r0f9gw01la.rcgu.o" "$PROJECT/target/debug/deps/test_main-f36430e3bd34d135.3rngp6bm2u2q5z0y.rcgu.o" "$PROJECT/target/debug/deps/test_main-f36430e3bd34d135.4011gx3bwpzq03se.rcgu.o" "$PROJECT/target/debug/deps/test_main-f36430e3bd34d135.4oc10dk278mpk1vy.rcgu.o" "$PROJECT/target/debug/deps/test_main-f36430e3bd34d135.4xq48u46a1pwiqn7.rcgu.o" "$PROJECT/target/debug/deps/test_main-f36430e3bd34d135.4ypvbwho0bu5tnww.rcgu.o" "$PROJECT/target/debug/deps/test_main-f36430e3bd34d135.8xzrsc1ux72v29j.rcgu.o" "$PROJECT/target/debug/deps/test_main-f36430e3bd34d135.oa3rad818d8sgn4.rcgu.o" "-o" "$PROJECT/target/debug/deps/test_main-f36430e3bd34d135" "$PROJECT/target/debug/deps/test_main-f36430e3bd34d135.crate.allocator.rcgu.o" "-Wl,-dead_strip" "-nodefaultlibs" "-L" "$PROJECT/target/debug/deps" "-L" "/usr/local/opt/llvm/lib" "-L" "$HOME/.rustup/toolchains/nightly-x86_64-apple-darwin/lib/rustlib/x86_64-apple-darwin/lib" "$HOME/.rustup/toolchains/nightly-x86_64-apple-darwin/lib/rustlib/x86_64-apple-darwin/lib/libtest-8b11cd23e28267c4.rlib" "$HOME/.rustup/toolchains/nightly-x86_64-apple-darwin/lib/rustlib/x86_64-apple-darwin/lib/libterm-97c75d65953833c3.rlib" "$HOME/.rustup/toolchains/nightly-x86_64-apple-darwin/lib/rustlib/x86_64-apple-darwin/lib/libgetopts-96e8d9c41fd5f863.rlib" "$PROJECT/target/debug/deps/$PROJECT-9d25e484d92983e9.rlib" "$PROJECT/target/debug/deps/libclang_sys-7109b6c4a521deab.rlib" "$PROJECT/target/debug/deps/liblibc-aecf7ee5e4c12d5c.rlib" "$PROJECT/target/debug/deps/libglob-186622082d7523d5.rlib" "$HOME/.rustup/toolchains/nightly-x86_64-apple-darwin/lib/rustlib/x86_64-apple-darwin/lib/libstd-90d0baaa628316fc.rlib" "$HOME/.rustup/toolchains/nightly-x86_64-apple-darwin/lib/rustlib/x86_64-apple-darwin/lib/libpanic_unwind-2501f1a43ee00253.rlib" "$HOME/.rustup/toolchains/nightly-x86_64-apple-darwin/lib/rustlib/x86_64-apple-darwin/lib/liballoc_jemalloc-1ebc0af87eedc756.rlib" "$HOME/.rustup/toolchains/nightly-x86_64-apple-darwin/lib/rustlib/x86_64-apple-darwin/lib/libunwind-d5a51010c907c42d.rlib" "$HOME/.rustup/toolchains/nightly-x86_64-apple-darwin/lib/rustlib/x86_64-apple-darwin/lib/liballoc_system-776df9543761d8dc.rlib" "$HOME/.rustup/toolchains/nightly-x86_64-apple-darwin/lib/rustlib/x86_64-apple-darwin/lib/liblibc-56ad06cec3622785.rlib" "$HOME/.rustup/toolchains/nightly-x86_64-apple-darwin/lib/rustlib/x86_64-apple-darwin/lib/liballoc-54ae7b5ec4f1ba32.rlib" "$HOME/.rustup/toolchains/nightly-x86_64-apple-darwin/lib/rustlib/x86_64-apple-darwin/lib/libcore-585d1da946bc8c2f.rlib" "$HOME/.rustup/toolchains/nightly-x86_64-apple-darwin/lib/rustlib/x86_64-apple-darwin/lib/libcompiler_builtins-a06451ee7f3e01cf.rlib" "-l" "clang.dy" "-l" "System" "-l" "resolv" "-l" "pthread" "-l" "c" "-l" "m"
  = note: ld: library not found for -lclang.dy
          clang: error: linker command failed with exit code 1 (use -v to see invocation)

Somehow it tries to use libclang.dy, and not libclang.dylib.

Also, v0.23.0 compiles just fine.

linking with `cc` failed: exit code: 1

Hi! I am trying to use statically link clang-sys on Mac in my pet hello world project. So I downloaded and compiled libclang version 6_0_0 and it has all the necessary files (libclang.a llvm-config etc). Here's my Cargo.toml

[package]
name = "hello_libclang"
version = "0.1.0"
authors = ["Oleksii Dykan <[email protected]>"]

[dependencies]

[dependencies.clang-sys]
version = "0.24.0"
features = ["static", "clang_6_0"]

and here's my main.rs:

extern crate clang_sys;

fn main() {
    println!("Hello, world!");
}

I try to compile it with the following command:

LLVM_CONFIG_PATH=~/Desktop/clang-test/build/bin/llvm-config LIBCLANG_STATIC_PATH=~/Desktop/clang-test/build/lib LIBCLANG_PATH=~/Desktop/clang-test/build/lib cargo build

however, on the compilation time I get the following error:

error: linking with `cc` failed: exit code: 1

Do you know what could be the reason for that? Thanks in advance!

Improve llvm search path

Currently build.rs contains a hard-coded, os-specific list of directories to search. I think it could be improved by simply using the output of llvm-config --libdir, maybe with a fallback with the current search path.

dyld: Library not loaded: @rpath/libclang.dylib

Building bindgen on my OS X (Yosemite) all works fine but once I execute it:

> target/debug/bindgen
dyld: Library not loaded: @rpath/libclang.dylib
  Referenced from: /Users/philipp/local.ch/rust-bindgen/target/debug/bindgen
  Reason: image not found
Trace/BPT trap: 5

my libclang.dylib is here: /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/lib/libclang.dylib

and xcode-select -p outputs /Applications/Xcode.app/Contents/Developer, so all seems fine. Any hints?

Add a get_include_dir function

Clang doesn't have a reliable builtin method to get the include directory for system headers. A better get_include_dir could be included in your crate.
https://github.com/crabtw/rust-bindgen/issues/317

Unknown enum variants returned by libclang cause crash in clang-sys builds targeting earlier versions of libclang

If clang-sys is compiled to target clang_3_5 but is linked against libclang 3.9 a crash (SIGSEGV or stack overflow) occurs when libclang returns an enum variant unknown to clang-sys that is then used in a match expression.

I filed a "bug" with rust-lang although it seems this is intended behavior for rust. Possible solutions are to cast the enums to an int or use int constants instead to avoid this problem, perhaps re-wrapping them as an enum. rust-lang/rust#36927

Some other discussions of this issue:

https://internals.rust-lang.org/t/c-style-enums-in-ffi-and-a-proposal-to-lump-in-with-unions/2744
https://users.rust-lang.org/t/backward-compatibility-of-enums/5224
rust-lang/rfcs#757

Panic in clang_sys::support::Clang::find

In particular, when called with None. Minimal example:

extern crate clang_sys;

fn main() {
    clang_sys::support::Clang::find(None);
}

This is with clang-sys 0.7.1.

Improve libclang selection to find highest version

servo/servo#21478

Next release?

Are you planning a new release soon? I can't wait to use the recent improvements.

search LD_LIBRARY_PATH for libclang

I'm trying to use ffmpeg-sys (which depends on bindgen and thus clang-sys) in a Heroku-like environment. In that environment, apt packages (using heroku-buildpack-apt) are not installed in their default location, but in another user-writable directory. LD_LIBRARY_PATH is set so the folder where libclang-3.9.so (in my case) can be found is included.

I think it would be sensible to include all directories in LD_LIBRARY_PATH in the locations searched for the libclang shared library. This would happen automatically if clang-sys were linked with libclang in the normal way, so I think it would be sensible to match that behaviour when loading the library at runtime.

Why is xcode-select searched before llvm-config on MacOSX ?

Why is xcode-select searched first for the path, and llvm-config second on MacOS X?

If I have an LLVM compiled from source, and put it on my path, llvm-config will always return the correct result, but xcode-select will return the paths for some other LLVM (the one bundled with whatever SDK is active).

The build script should not rely on `cfg!(target_os)`

cfg!(target_os) in a build script will be evaluated against the build host instead of the target one, preventing cross-compilation.

Test Windows

Could someone test llvm-config --libdir on Windows?

Feature detection

If I compile with clang_3_9, does the build script checks if clang 3.9 is available?

`support::parse_search_paths()` should not `.expect(include_start)`

(The title refers to https://github.com/KyleMayes/clang-sys/blob/master/src/support.rs#L185)

It's as the title says - To give more context, I ran into a panic caused by this when using bindgen and it took me a while to figure out that it was because my clang is the one provided by Emscripten 1.37 which, unlike the "regular" clang, only outputs the "#include "[...]" search starts here:" line but not the "#include <[...]> search starts here:" one.

Also, seeing only that line as the message I got from the resulting panic was confusing to me.

I suggest that, instead of panicking, an empty Vec be returned.

How to compile libclang version 6_0_0 to statically link

A noob question here. I would like to use your library together with clang-rs. However, due to some limitations, I need it statically linked. As you mentioned in the README, I would need to manually compile the libclang for version 6_0_0 to statically link it. Are there any good references of how to do it? Thanks in advance!

Support for clang 8.0

I know it's a bit early, but I need some features that landed right after clang 7.0 branched. Here's my code in case you're interested https://github.com/michaelwu/clang-sys/tree/clang-8.0 .

parse_version fails on debian Jessie

running the rust-bindgen tests, which uses cargo-sys
---- builder_state stdout ----
thread 'builder_state' panicked at 'called Result::unwrap() on an Err value: ParseIntError { kind: InvalidDigit }', ../src/libcore/result.rs
...
17: 0x559314b80437 - clang_sys::support::parse_version::h797e147fe3900f18
at /clean/devenv/rust/cargo/registry/src/github.com-88ac128001ac3a9a/clang-sys-0.6.0/src/support.rs:89
18: 0x559314b7fea5 - clang_sys::support::Clang::new::hdc3ebf8b18e7e1ba
at /clean/devenv/rust/cargo/registry/src/github.com-88ac128001ac3a9a/clang-sys-0.6.0/src/support.rs:32
....

clang --version on this system outputs:
Debian clang version 3.5.0-10 (tags/RELEASE_350/final) (based on LLVM 3.5.0)

Can't find standard include with XCode Beta

See https://github.com/crabtw/rust-bindgen/issues/361

Missing comment functions

http://clang.llvm.org/doxygen/group__CINDEX__COMMENT.html
Notably clang_HTMLTagComment_getTagName

Static link failure

https://travis-ci.org/crabtw/rust-bindgen/jobs/129524942

Error on 3.4

Not directly related but https://travis-ci.org/crabtw/rust-bindgen/builds/132627863
It only happens on 3.4, I'm trying to see why.

Travis build of bindgen

Maybe we don't need so many builds for bindgen since you also use travis? Do you also test static link?
What do you think?

no clang_parseTranslationUnit2 on clang 3.4

https://travis-ci.org/crabtw/rust-bindgen/jobs/132845265

thread 'main' panicked at 'function not loaded: clang_Type_getNumTemplateArguments on travis-ci

Not sure what's happen here. The build on my local machine works fine. But on travis-ci.org I get this error:

• https://api.travis-ci.org/jobs/227893001/log.txt?deansi=true

[build.rs] LIBRARIES -> `llvm-config --libs`

llvm-config --libs should be used instead of the hardcoded list in build.rs.

Support minimum version

It would be useful for cases where we require a certain minimum version of clang to be used to provide an error if that version can't be found.

On fedora clang-sys finds the 32 bit version of libclang

on fedora, clang-sys should look first in the /usr/lib64 directory if it is a 64 bit binary. Currently it looks in the /usr/lib directory which contains the 32 bit versions of the library. This causes error #48.

Add DYLD_LIBRARY_PATH to the README

https://github.com/crabtw/rust-bindgen/blob/2b7143317227107adc1186e34a027fa1ad625b39/README.md#building
You should add it to your readme, maybe also with a mention to LD_LIBRARY_PATH, maybe.

Expose location of C headers

For my project I need to compile a bit of extra C code that uses clang functions.

However, in my build script I'm unable to find the right directory that contains the headers.

Could you expose that information? It's usually done by setting links and emitting Cargo variable cargo:include=, so that other build scripts can find it via DEP_CLANG_INCLUDE env var.

I can make a PR if you're interested.

Merge the clang.rs file from bindgen into clang-sys

It would be more useful here. What do you think?

Can't find clang on Ubuntu

On Ubuntu, LLVM binaries have the version number appended to their name, like so:

$clang[TAB][TAB]
clang-3.5                     clang-format-diff-3.5
clang++-3.5                   clang-modernize-3.5
clang-apply-replacements-3.5  clang-query-3.5
clang-check-3.5               clang-tblgen-3.5
clang-format-3.5              clang-tidy-3.5

support::Clang::find can't find clang this way.

Use `glob` in build.rs

https://doc.rust-lang.org/glob/glob/index.html

Allow for non-standard clang install paths on macOS

I just ran into an issue with coreaudio-sys by way of rust-bindgen by way of clang-sys where it was not able to find the path to my libclang.dylib.

I managed to pin it down to this line, where the shared library search path points to a typical Xcode installation location. However, I'm a Cocoa dev who bounces around between Xcode versions a lot and have to maintain a folder structure for managing different Xcode versions in different locations. This path being hardcoded, alongside the fact that I can't get RLS to account for environment variables and I don't have my own version of LLVM installed, has left me with limited options here.

Instead of hardcoding this path, can we change this behavior to do a search based on the return from xcode-select -p? I see that we're already checking for some output from xcodebuild to find the clang executable, so it wouldn't be antithetical to the design of the rest of the crate.

Mac build broken

https://travis-ci.org/crabtw/rust-bindgen/jobs/129245610