1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
|
# clang-sys
[](https://crates.io/crates/clang-sys)
[](https://docs.rs/clang-sys)
[](https://github.com/KyleMayes/clang-sys/actions?query=workflow%3ACI)
Rust bindings for `libclang`.
If you are interested in a Rust wrapper for these bindings, see
[clang-rs](https://github.com/KyleMayes/clang-rs).
Supported on the stable, beta, and nightly Rust channels.<br/>
Minimum supported Rust version: **1.40.0**
Released under the Apache License 2.0.
## [Documentation](https://docs.rs/clang-sys)
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_11_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 one of the following Cargo features:
* `clang_3_5` - requires `libclang` 3.5 or later
* `clang_3_6` - requires `libclang` 3.6 or later
* `clang_3_7` - requires `libclang` 3.7 or later
* `clang_3_8` - requires `libclang` 3.8 or later
* `clang_3_9` - requires `libclang` 3.9 or later
* `clang_4_0` - requires `libclang` 4.0 or later
* `clang_5_0` - requires `libclang` 5.0 or later
* `clang_6_0` - requires `libclang` 6.0 or later
* `clang_7_0` - requires `libclang` 7.0 or later
* `clang_8_0` - requires `libclang` 8.0 or later
* `clang_9_0` - requires `libclang` 9.0 or later
* `clang_10_0` - requires `libclang` 10.0 or later
* `clang_11_0` - requires `libclang` 11.0 or later
If you do not enable one of these features, the API provided by `libclang` 3.5 will be available by
default.
## 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](http://llvm.org/releases/download.html).
**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](https://msdn.microsoft.com/en-us/library/7d83bc18.aspx) 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.
|
