README.md
1# clang-sys
2
3[](https://crates.io/crates/clang-sys)
4[](https://docs.rs/clang-sys)
5[](https://github.com/KyleMayes/clang-sys/actions?query=workflow%3ACI)
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.<br/>
13Minimum supported Rust version: **1.40.0**
14
15Released under the Apache License 2.0.
16
17## Documentation
18
19There are two versions of the documentation, one for the API exposed when
20linking dynamically or statically and one for the API exposed when linking at
21runtime (see the
22[Dependencies](https://github.com/KyleMayes/clang-sys#dependencies) section
23of the README for more information on the linking options).
24
25The only difference between the APIs exposed is that when linking at runtime a
26few additional types and functions are exposed to manage the loaded `libclang`
27shared library.
28
29* Runtime - [Documentation](https://kylemayes.github.io/clang-sys/runtime/clang_sys)
30* Dynamic / Static - [Documentation](https://kylemayes.github.io/clang-sys/default/clang_sys)
31
32## Supported Versions
33
34To target a version of `libclang`, enable one of the following Cargo features:
35
36* `clang_3_5` - requires `libclang` 3.5 or later
37* `clang_3_6` - requires `libclang` 3.6 or later
38* `clang_3_7` - requires `libclang` 3.7 or later
39* `clang_3_8` - requires `libclang` 3.8 or later
40* `clang_3_9` - requires `libclang` 3.9 or later
41* `clang_4_0` - requires `libclang` 4.0 or later
42* `clang_5_0` - requires `libclang` 5.0 or later
43* `clang_6_0` - requires `libclang` 6.0 or later
44* `clang_7_0` - requires `libclang` 7.0 or later
45* `clang_8_0` - requires `libclang` 8.0 or later
46* `clang_9_0` - requires `libclang` 9.0 or later
47* `clang_10_0` - requires `libclang` 10.0 or later
48* `clang_11_0` - requires `libclang` 11.0 or later
49
50If you do not enable one of these features, the API provided by `libclang` 3.5 will be available by
51default.
52
53## Dependencies
54
55By default, this crate will attempt to link to `libclang` dynamically. In this case, this crate
56depends on the `libclang` shared library (`libclang.so` on Linux, `libclang.dylib` on macOS,
57`libclang.dll` on Windows). If you want to link to `libclang` statically instead, enable the
58`static` Cargo feature. In this case, this crate depends on the LLVM and Clang static libraries. If
59you don't want to link to `libclang` at compiletime but instead want to load it at runtime, enable
60the `runtime` Cargo feature.
61
62These libraries can be either be installed as a part of Clang or downloaded
63[here](http://llvm.org/releases/download.html).
64
65**Note:** The downloads for LLVM and Clang 3.8 and later do not include the `libclang.a` static
66library. This means you cannot link to any of these versions of `libclang` statically unless you
67build it from source.
68
69### Versioned Dependencies
70
71This crate supports finding versioned instances of `libclang.so` (e.g.,`libclang-3.9.so`).
72In the case where there are multiple instances to choose from, this crate will prefer instances with
73higher versions. For example, the following instances of `libclang.so` are listed in descending
74order of preference:
75
761. `libclang-4.0.so`
772. `libclang-4.so`
783. `libclang-3.9.so`
794. `libclang-3.so`
805. `libclang.so`
81
82**Note:** On BSD distributions, versioned instances of `libclang.so` matching the pattern
83`libclang.so.*` (e.g., `libclang.so.7.0`) are also included.
84
85**Note:** On Linux distributions when the `runtime` features is enabled, versioned instances of
86`libclang.so` matching the pattern `libclang.so.*` (e.g., `libclang.so.1`) are also included.
87
88## Environment Variables
89
90The following environment variables, if set, are used by this crate to find the required libraries
91and executables:
92
93* `LLVM_CONFIG_PATH` **(compiletime)** - provides a full path to an `llvm-config` executable
94 (including the executable itself [i.e., `/usr/local/bin/llvm-config-8.0`])
95* `LIBCLANG_PATH` **(compiletime)** - provides a path to a directory containing a `libclang` shared
96 library or a full path to a specific `libclang` shared library
97* `LIBCLANG_STATIC_PATH` **(compiletime)** - provides a path to a directory containing LLVM and
98 Clang static libraries
99* `CLANG_PATH` **(runtime)** - provides a path to a `clang` executable
100
101## Linking
102
103### Dynamic
104
105`libclang` shared libraries will be searched for in the following directories:
106
107* the directory provided by the `LIBCLANG_PATH` environment variable
108* the `bin` and `lib` directories in the directory provided by `llvm-config --libdir`
109* the directories provided by `LD_LIBRARY_PATH` environment variable
110* a list of likely directories for the target platform (e.g., `/usr/local/lib` on Linux)
111* **macOS only:** the toolchain directory in the directory provided by `xcode-select --print-path`
112
113On Linux, running an executable that has been dynamically linked to `libclang` may require you to
114add a path to `libclang.so` to the `LD_LIBRARY_PATH` environment variable. The same is true on OS
115X, except the `DYLD_LIBRARY_PATH` environment variable is used instead.
116
117On Windows, running an executable that has been dynamically linked to `libclang` requires that
118`libclang.dll` can be found by the executable at runtime. See
119[here](https://msdn.microsoft.com/en-us/library/7d83bc18.aspx) for more information.
120
121### Static
122
123The availability of `llvm-config` is not optional for static linking. Ensure that an instance of
124this executable can be found on your system's path or set the `LLVM_CONFIG_PATH` environment
125variable. The required LLVM and Clang static libraries will be searched for in the same way as
126shared libraries are searched for, except the `LIBCLANG_STATIC_PATH` environment variable is used in
127place of the `LIBCLANG_PATH` environment variable.
128
129### Runtime
130
131The `clang_sys::load` function is used to load a `libclang` shared library for use in the thread in
132which it is called. The `clang_sys::unload` function will unload the `libclang` shared library.
133`clang_sys::load` searches for a `libclang` shared library in the same way one is searched for when
134linking to `libclang` dynamically at compiletime.
135
){kind=link}
){kind=link}
){kind=link}