File: README.md

package info (click to toggle)
rust-clang-sys 1.0.1-2
  • links: PTS, VCS
  • area: main
  • in suites: bullseye, sid
  • size: 292 kB
  • sloc: makefile: 4; ansic: 4
file content (133 lines) | stat: -rw-r--r-- 6,412 bytes parent folder | download | duplicates (6)
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
129
130
131
132
133
# clang-sys

[![Crate](https://img.shields.io/crates/v/clang-sys.svg)](https://crates.io/crates/clang-sys)
[![Documentation](https://docs.rs/clang-sys/badge.svg)](https://docs.rs/clang-sys)
[![CI](https://github.com/KyleMayes/clang-sys/workflows/CI/badge.svg?branch=master)](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

There are two versions of the documentation, one for the API exposed when
linking dynamically or statically and one for the API exposed when linking at
runtime (see the
[Dependencies](https://github.com/KyleMayes/clang-sys#dependencies) section
of the README for more information on the linking options).

The only difference between the APIs exposed is that when linking at runtime a
few additional types and functions are exposed to manage the loaded `libclang`
shared library.

* Runtime - [Documentation](https://kylemayes.github.io/clang-sys/runtime/clang_sys)
* Dynamic / Static - [Documentation](https://kylemayes.github.io/clang-sys/default/clang_sys)

## 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

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.