README.md
1# clang-sys
2
3[](https://crates.io/crates/clang-sys)
4[](https://travis-ci.org/KyleMayes/clang-sys)
5[](https://ci.appveyor.com/project/KyleMayes/clang-sys-vtvy5/branch/master)
6
7Rust bindings for `libclang`.
8
9If you are interested in a Rust wrapper for these bindings, see
10[clang-rs](https://github.com/KyleMayes/clang-rs).
11
12Supported on the stable, beta, and nightly Rust channels.
13
14Released under the Apache License 2.0.
15
16## Supported Versions
17
18To target a version of `libclang`, enable one of the following Cargo features:
19
20* `clang_3_5` - requires `libclang` 3.5 or later
21 ([Documentation](https://kylemayes.github.io/clang-sys/3_5/clang_sys))
22* `clang_3_6` - requires `libclang` 3.6 or later
23 ([Documentation](https://kylemayes.github.io/clang-sys/3_6/clang_sys))
24* `clang_3_7` - requires `libclang` 3.7 or later
25 ([Documentation](https://kylemayes.github.io/clang-sys/3_7/clang_sys))
26* `clang_3_8` - requires `libclang` 3.8 or later
27 ([Documentation](https://kylemayes.github.io/clang-sys/3_8/clang_sys))
28* `clang_3_9` - requires `libclang` 3.9 or later
29 ([Documentation](https://kylemayes.github.io/clang-sys/3_9/clang_sys))
30* `clang_4_0` - requires `libclang` 4.0 or later
31 ([Documentation](https://kylemayes.github.io/clang-sys/4_0/clang_sys))
32* `clang_5_0` - requires `libclang` 5.0 or later
33 ([Documentation](https://kylemayes.github.io/clang-sys/5_0/clang_sys))
34* `clang_6_0` - requires `libclang` 6.0 or later
35 ([Documentation](https://kylemayes.github.io/clang-sys/6_0/clang_sys))
36* `clang_7_0` - requires `libclang` 7.0 or later
37 ([Documentation](https://kylemayes.github.io/clang-sys/7_0/clang_sys))
38* `clang_8_0` - requires `libclang` 8.0 or later
39 ([Documentation](https://kylemayes.github.io/clang-sys/8_0/clang_sys))
40
41If you do not enable one of these features, the API provided by `libclang` 3.5 will be available by
42default.
43
44## Dependencies
45
46By default, this crate will attempt to link to `libclang` dynamically. In this case, this crate
47depends on the `libclang` shared library (`libclang.so` on Linux, `libclang.dylib` on macOS,
48`libclang.dll` on Windows). If you want to link to `libclang` statically instead, enable the
49`static` Cargo feature. In this case, this crate depends on the LLVM and Clang static libraries. If
50you don't want to link to `libclang` at compiletime but instead want to load it at runtime, enable
51the `runtime` Cargo feature.
52
53These libraries can be either be installed as a part of Clang or downloaded
54[here](http://llvm.org/releases/download.html).
55
56**Note:** The downloads for LLVM and Clang 3.8 and later do not include the `libclang.a` static
57library. This means you cannot link to any of these versions of `libclang` statically unless you
58build it from source.
59
60### Versioned Dependencies
61
62This crate supports finding versioned instances of `libclang.so` (e.g.,`libclang-3.9.so`).
63In the case where there are multiple instances to choose from, this crate will prefer instances with
64higher versions. For example, the following instances of `libclang.so` are listed in descending
65order of preference:
66
671. `libclang-4.0.so`
682. `libclang-4.so`
693. `libclang-3.9.so`
704. `libclang-3.so`
715. `libclang.so`
72
73**Note:** On BSD distributions, versioned instances of `libclang.so` matching the pattern
74`libclang.so.*` (e.g., `libclang.so.7.0`) are also included.
75
76**Note:** On Linux distributions when the `runtime` features is enabled, versioned instances of
77`libclang.so` matching the pattern `libclang.so.*` (e.g., `libclang.so.1`) are also included.
78
79## Environment Variables
80
81The following environment variables, if set, are used by this crate to find the required libraries
82and executables:
83
84* `LLVM_CONFIG_PATH` **(compiletime)** - provides a path to an `llvm-config` executable
85* `LIBCLANG_PATH` **(compiletime)** - provides a path to a directory containing a `libclang` shared
86 library or a path to a specific `libclang` shared library
87* `LIBCLANG_STATIC_PATH` **(compiletime)** - provides a path to a directory containing LLVM and
88 Clang static libraries
89* `CLANG_PATH` **(runtime)** - provides a path to a `clang` executable
90
91## Linking
92
93### Dynamic
94
95`libclang` shared libraries will be searched for in the following directories:
96
97* the directory provided by the `LIBCLANG_PATH` environment variable
98* the `bin` and `lib` directories in the directory provided by `llvm-config --libdir`
99* the directories provided by `LD_LIBRARY_PATH` environment variable
100* a list of likely directories for the target platform (e.g., `/usr/local/lib` on Linux)
101* **macOS only:** the toolchain directory in the directory provided by `xcode-select --print-path`
102
103On Linux, running an executable that has been dynamically linked to `libclang` may require you to
104add a path to `libclang.so` to the `LD_LIBRARY_PATH` environment variable. The same is true on OS
105X, except the `DYLD_LIBRARY_PATH` environment variable is used instead.
106
107On Windows, running an executable that has been dynamically linked to `libclang` requires that
108`libclang.dll` can be found by the executable at runtime. See
109[here](https://msdn.microsoft.com/en-us/library/7d83bc18.aspx) for more information.
110
111### Static
112
113The availability of `llvm-config` is not optional for static linking. Ensure that an instance of
114this executable can be found on your system's path or set the `LLVM_CONFIG_PATH` environment
115variable. The required LLVM and Clang static libraries will be searched for in the same way as
116shared libraries are searched for, except the `LIBCLANG_STATIC_PATH` environment variable is used in
117place of the `LIBCLANG_PATH` environment variable.
118
119### Runtime
120
121The `clang_sys::load` function is used to load a `libclang` shared library for use in the thread in
122which it is called. The `clang_sys::unload` function will unload the `libclang` shared library.
123`clang_sys::load` searches for a `libclang` shared library in the same way one is searched for when
124linking to `libclang` dynamically at compiletime.
125
){kind=link}
){kind=link}