fork/rules_rust

git clone https://git.julia.blue/fork/rules_rust

P1n3appl3Deploying to gh-pages from @ P1n3appl3/rules_rust@c3d71edd99fe764bf831a95ba2a9c486fc0b9e9c 🚀482a21cf

gh-pages
22.0 KiB311 linesraw
1<!DOCTYPE HTML>
2<html lang="en" class="light sidebar-visible" dir="ltr">
3    <head>
4        <!-- Book generated using mdBook -->
5        <meta charset="UTF-8">
6        <title>bindgen - rules_rust</title>
7
8
9        <!-- Custom HTML head -->
10
11        <meta name="description" content="">
12        <meta name="viewport" content="width=device-width, initial-scale=1">
13        <meta name="theme-color" content="#ffffff">
14
15        <link rel="icon" href="favicon.svg">
16        <link rel="shortcut icon" href="favicon.png">
17        <link rel="stylesheet" href="css/variables.css">
18        <link rel="stylesheet" href="css/general.css">
19        <link rel="stylesheet" href="css/chrome.css">
20        <link rel="stylesheet" href="css/print.css" media="print">
21
22        <!-- Fonts -->
23        <link rel="stylesheet" href="FontAwesome/css/font-awesome.css">
24        <link rel="stylesheet" href="fonts/fonts.css">
25
26        <!-- Highlight.js Stylesheets -->
27        <link rel="stylesheet" href="highlight.css">
28        <link rel="stylesheet" href="tomorrow-night.css">
29        <link rel="stylesheet" href="ayu-highlight.css">
30
31        <!-- Custom theme stylesheets -->
32
33
34        <!-- Provide site root to javascript -->
35        <script>
36            var path_to_root = "";
37            var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "navy" : "light";
38        </script>
39        <!-- Start loading toc.js asap -->
40        <script src="toc.js"></script>
41    </head>
42    <body>
43    <div id="body-container">
44        <!-- Work around some values being stored in localStorage wrapped in quotes -->
45        <script>
46            try {
47                var theme = localStorage.getItem('mdbook-theme');
48                var sidebar = localStorage.getItem('mdbook-sidebar');
49
50                if (theme.startsWith('"') && theme.endsWith('"')) {
51                    localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
52                }
53
54                if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
55                    localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
56                }
57            } catch (e) { }
58        </script>
59
60        <!-- Set the theme before any content is loaded, prevents flash -->
61        <script>
62            var theme;
63            try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
64            if (theme === null || theme === undefined) { theme = default_theme; }
65            const html = document.documentElement;
66            html.classList.remove('light')
67            html.classList.add(theme);
68            html.classList.add("js");
69        </script>
70
71        <input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
72
73        <!-- Hide / unhide sidebar before it is displayed -->
74        <script>
75            var sidebar = null;
76            var sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
77            if (document.body.clientWidth >= 1080) {
78                try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
79                sidebar = sidebar || 'visible';
80            } else {
81                sidebar = 'hidden';
82            }
83            sidebar_toggle.checked = sidebar === 'visible';
84            html.classList.remove('sidebar-visible');
85            html.classList.add("sidebar-" + sidebar);
86        </script>
87
88        <nav id="sidebar" class="sidebar" aria-label="Table of contents">
89            <!-- populated by js -->
90            <mdbook-sidebar-scrollbox class="sidebar-scrollbox"></mdbook-sidebar-scrollbox>
91            <noscript>
92                <iframe class="sidebar-iframe-outer" src="toc.html"></iframe>
93            </noscript>
94            <div id="sidebar-resize-handle" class="sidebar-resize-handle">
95                <div class="sidebar-resize-indicator"></div>
96            </div>
97        </nav>
98
99        <div id="page-wrapper" class="page-wrapper">
100
101            <div class="page">
102                <div id="menu-bar-hover-placeholder"></div>
103                <div id="menu-bar" class="menu-bar sticky">
104                    <div class="left-buttons">
105                        <label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
106                            <i class="fa fa-bars"></i>
107                        </label>
108                        <button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
109                            <i class="fa fa-paint-brush"></i>
110                        </button>
111                        <ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
112                            <li role="none"><button role="menuitem" class="theme" id="light">Light</button></li>
113                            <li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
114                            <li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
115                            <li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
116                            <li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
117                        </ul>
118                        <button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
119                            <i class="fa fa-search"></i>
120                        </button>
121                    </div>
122
123                    <h1 class="menu-title">rules_rust</h1>
124
125                    <div class="right-buttons">
126                        <a href="print.html" title="Print this book" aria-label="Print this book">
127                            <i id="print-button" class="fa fa-print"></i>
128                        </a>
129                        <a href="https://github.com/bazelbuild/rules_rust" title="Git repository" aria-label="Git repository">
130                            <i id="git-repository-button" class="fa fa-github"></i>
131                        </a>
132
133                    </div>
134                </div>
135
136                <div id="search-wrapper" class="hidden">
137                    <form id="searchbar-outer" class="searchbar-outer">
138                        <input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
139                    </form>
140                    <div id="searchresults-outer" class="searchresults-outer hidden">
141                        <div id="searchresults-header" class="searchresults-header"></div>
142                        <ul id="searchresults">
143                        </ul>
144                    </div>
145                </div>
146
147                <!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
148                <script>
149                    document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
150                    document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
151                    Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
152                        link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
153                    });
154                </script>
155
156                <div id="content" class="content">
157                    <main>
158                        <!-- Generated with Stardoc: http://skydoc.bazel.build -->
159<h1 id="rules_rust_bindgen"><a class="header" href="#rules_rust_bindgen">rules_rust_bindgen</a></h1>
160<p>These rules are for using <a href="https://github.com/rust-lang/rust-bindgen">Bindgen</a> to generate <a href="http://www.rust-lang.org/">Rust</a> bindings to C (and some C++) libraries.</p>
161<h2 id="rules"><a class="header" href="#rules">Rules</a></h2>
162<ul>
163<li><a href="#rust_bindgen">rust_bindgen</a></li>
164<li><a href="#rust_bindgen_library">rust_bindgen_library</a></li>
165<li><a href="#rust_bindgen_toolchain">rust_bindgen_toolchain</a></li>
166</ul>
167<h2 id="setup"><a class="header" href="#setup">Setup</a></h2>
168<p>To use the Rust bindgen rules, add the following to your <code>WORKSPACE</code> file to add the
169external repositories for the Rust bindgen toolchain (in addition to the <a href="https://bazelbuild.github.io/rules_rust/#setup">rust rules setup</a>):</p>
170<pre><code class="language-python">load("@rules_rust_bindgen//:repositories.bzl", "rust_bindgen_dependencies", "rust_bindgen_register_toolchains")
171
172rust_bindgen_dependencies()
173
174rust_bindgen_register_toolchains()
175
176load("@rules_rust_bindgen//:transitive_repositories.bzl", "rust_bindgen_transitive_dependencies")
177
178rust_bindgen_transitive_dependencies()
179</code></pre>
180<p>Bindgen aims to be as hermetic as possible so will end up building <code>libclang</code> from <a href="https://github.com/llvm/llvm-project">llvm-project</a> from
181source. If this is found to be undesirable then no Bindgen related calls should be added to your WORKSPACE and instead
182users should define their own repositories using something akin to <a href="https://bazelbuild.github.io/rules_rust/crate_universe.html">crate_universe</a> and define their own
183toolchains following the instructions for <a href="#rust_bindgen_toolchain">rust_bindgen_toolchain</a>.</p>
184<hr />
185<hr />
186<p><a id="rust_bindgen"></a></p>
187<h2 id="rust_bindgen"><a class="header" href="#rust_bindgen">rust_bindgen</a></h2>
188<pre>
189rust_bindgen(<a href="#rust_bindgen-name">name</a>, <a href="#rust_bindgen-bindgen_flags">bindgen_flags</a>, <a href="#rust_bindgen-cc_lib">cc_lib</a>, <a href="#rust_bindgen-clang_flags">clang_flags</a>, <a href="#rust_bindgen-header">header</a>, <a href="#rust_bindgen-merge_cc_lib_objects_into_rlib">merge_cc_lib_objects_into_rlib</a>,
190             <a href="#rust_bindgen-wrap_static_fns">wrap_static_fns</a>)
191</pre>
192<p>Generates a rust source file from a cc_library and a header.</p>
193<p><strong>ATTRIBUTES</strong></p>
194<div class="table-wrapper"><table><thead><tr><th style="text-align: left">Name</th><th style="text-align: left">Description</th><th style="text-align: left">Type</th><th style="text-align: left">Mandatory</th><th style="text-align: left">Default</th></tr></thead><tbody>
195<tr><td style="text-align: left"><a id="rust_bindgen-name"></a>name</td><td style="text-align: left">A unique name for this target.</td><td style="text-align: left"><a href="https://bazel.build/concepts/labels#target-names">Name</a></td><td style="text-align: left">required</td><td style="text-align: left"></td></tr>
196<tr><td style="text-align: left"><a id="rust_bindgen-bindgen_flags"></a>bindgen_flags</td><td style="text-align: left">Flags to pass directly to the bindgen executable. See https://rust-lang.github.io/rust-bindgen/ for details.</td><td style="text-align: left">List of strings</td><td style="text-align: left">optional</td><td style="text-align: left"><code>[]</code></td></tr>
197<tr><td style="text-align: left"><a id="rust_bindgen-cc_lib"></a>cc_lib</td><td style="text-align: left">The cc_library that contains the <code>.h</code> file. This is used to find the transitive includes.</td><td style="text-align: left"><a href="https://bazel.build/concepts/labels">Label</a></td><td style="text-align: left">required</td><td style="text-align: left"></td></tr>
198<tr><td style="text-align: left"><a id="rust_bindgen-clang_flags"></a>clang_flags</td><td style="text-align: left">Flags to pass directly to the clang executable.</td><td style="text-align: left">List of strings</td><td style="text-align: left">optional</td><td style="text-align: left"><code>[]</code></td></tr>
199<tr><td style="text-align: left"><a id="rust_bindgen-header"></a>header</td><td style="text-align: left">The <code>.h</code> file to generate bindings for.</td><td style="text-align: left"><a href="https://bazel.build/concepts/labels">Label</a></td><td style="text-align: left">required</td><td style="text-align: left"></td></tr>
200<tr><td style="text-align: left"><a id="rust_bindgen-merge_cc_lib_objects_into_rlib"></a>merge_cc_lib_objects_into_rlib</td><td style="text-align: left">When True, objects from <code>cc_lib</code> will be copied into the <code>rlib</code> archive produced by the rust_library that depends on this <code>rust_bindgen</code> rule (using <code>BuildInfo</code> provider)</td><td style="text-align: left">Boolean</td><td style="text-align: left">optional</td><td style="text-align: left"><code>True</code></td></tr>
201<tr><td style="text-align: left"><a id="rust_bindgen-wrap_static_fns"></a>wrap_static_fns</td><td style="text-align: left">Whether to create a separate .c file for static fns. Requires nightly toolchain, and a header that actually needs this feature (otherwise bindgen won't generate the file and Bazel complains).</td><td style="text-align: left">Boolean</td><td style="text-align: left">optional</td><td style="text-align: left"><code>False</code></td></tr>
202</tbody></table>
203</div>
204<p><a id="rust_bindgen_toolchain"></a></p>
205<h2 id="rust_bindgen_toolchain"><a class="header" href="#rust_bindgen_toolchain">rust_bindgen_toolchain</a></h2>
206<pre>
207rust_bindgen_toolchain(<a href="#rust_bindgen_toolchain-name">name</a>, <a href="#rust_bindgen_toolchain-bindgen">bindgen</a>, <a href="#rust_bindgen_toolchain-clang">clang</a>, <a href="#rust_bindgen_toolchain-default_rustfmt">default_rustfmt</a>, <a href="#rust_bindgen_toolchain-libclang">libclang</a>, <a href="#rust_bindgen_toolchain-libstdcxx">libstdcxx</a>)
208</pre>
209<p>The tools required for the <code>rust_bindgen</code> rule.</p>
210<p>This rule depends on the <a href="https://crates.io/crates/bindgen"><code>bindgen</code></a> binary crate, and it
211in turn depends on both a clang binary and the clang library. To obtain these dependencies,
212<code>rust_bindgen_dependencies</code> imports bindgen and its dependencies.</p>
213<pre><code class="language-python">load("@rules_rust_bindgen//:defs.bzl", "rust_bindgen_toolchain")
214
215rust_bindgen_toolchain(
216    name = "bindgen_toolchain_impl",
217    bindgen = "//my/rust:bindgen",
218    clang = "//my/clang:clang",
219    libclang = "//my/clang:libclang.so",
220    libstdcxx = "//my/cpp:libstdc++",
221)
222
223toolchain(
224    name = "bindgen_toolchain",
225    toolchain = "bindgen_toolchain_impl",
226    toolchain_type = "@rules_rust_bindgen//:toolchain_type",
227)
228</code></pre>
229<p>This toolchain will then need to be registered in the current <code>WORKSPACE</code>.
230For additional information, see the <a href="https://docs.bazel.build/versions/master/toolchains.html">Bazel toolchains documentation</a>.</p>
231<p><strong>ATTRIBUTES</strong></p>
232<div class="table-wrapper"><table><thead><tr><th style="text-align: left">Name</th><th style="text-align: left">Description</th><th style="text-align: left">Type</th><th style="text-align: left">Mandatory</th><th style="text-align: left">Default</th></tr></thead><tbody>
233<tr><td style="text-align: left"><a id="rust_bindgen_toolchain-name"></a>name</td><td style="text-align: left">A unique name for this target.</td><td style="text-align: left"><a href="https://bazel.build/concepts/labels#target-names">Name</a></td><td style="text-align: left">required</td><td style="text-align: left"></td></tr>
234<tr><td style="text-align: left"><a id="rust_bindgen_toolchain-bindgen"></a>bindgen</td><td style="text-align: left">The label of a <code>bindgen</code> executable.</td><td style="text-align: left"><a href="https://bazel.build/concepts/labels">Label</a></td><td style="text-align: left">optional</td><td style="text-align: left"><code>None</code></td></tr>
235<tr><td style="text-align: left"><a id="rust_bindgen_toolchain-clang"></a>clang</td><td style="text-align: left">The label of a <code>clang</code> executable.</td><td style="text-align: left"><a href="https://bazel.build/concepts/labels">Label</a></td><td style="text-align: left">optional</td><td style="text-align: left"><code>None</code></td></tr>
236<tr><td style="text-align: left"><a id="rust_bindgen_toolchain-default_rustfmt"></a>default_rustfmt</td><td style="text-align: left">If set, <code>rust_bindgen</code> targets will always format generated sources with <code>rustfmt</code>.</td><td style="text-align: left">Boolean</td><td style="text-align: left">optional</td><td style="text-align: left"><code>True</code></td></tr>
237<tr><td style="text-align: left"><a id="rust_bindgen_toolchain-libclang"></a>libclang</td><td style="text-align: left">A cc_library that provides bindgen's runtime dependency on libclang.</td><td style="text-align: left"><a href="https://bazel.build/concepts/labels">Label</a></td><td style="text-align: left">optional</td><td style="text-align: left"><code>None</code></td></tr>
238<tr><td style="text-align: left"><a id="rust_bindgen_toolchain-libstdcxx"></a>libstdcxx</td><td style="text-align: left">A cc_library that satisfies libclang's libstdc++ dependency. This is used to make the execution of clang hermetic. If None, system libraries will be used instead.</td><td style="text-align: left"><a href="https://bazel.build/concepts/labels">Label</a></td><td style="text-align: left">optional</td><td style="text-align: left"><code>None</code></td></tr>
239</tbody></table>
240</div>
241<p><a id="rust_bindgen_library"></a></p>
242<h2 id="rust_bindgen_library"><a class="header" href="#rust_bindgen_library">rust_bindgen_library</a></h2>
243<pre>
244rust_bindgen_library(<a href="#rust_bindgen_library-name">name</a>, <a href="#rust_bindgen_library-header">header</a>, <a href="#rust_bindgen_library-cc_lib">cc_lib</a>, <a href="#rust_bindgen_library-bindgen_flags">bindgen_flags</a>, <a href="#rust_bindgen_library-bindgen_features">bindgen_features</a>, <a href="#rust_bindgen_library-clang_flags">clang_flags</a>,
245                     <a href="#rust_bindgen_library-wrap_static_fns">wrap_static_fns</a>, <a href="#rust_bindgen_library-kwargs">kwargs</a>)
246</pre>
247<p>Generates a rust source file for <code>header</code>, and builds a rust_library.</p>
248<p>Arguments are the same as <code>rust_bindgen</code>, and <code>kwargs</code> are passed directly to rust_library.</p>
249<p><strong>PARAMETERS</strong></p>
250<div class="table-wrapper"><table><thead><tr><th style="text-align: left">Name</th><th style="text-align: left">Description</th><th style="text-align: left">Default Value</th></tr></thead><tbody>
251<tr><td style="text-align: left"><a id="rust_bindgen_library-name"></a>name</td><td style="text-align: left">A unique name for this target.</td><td style="text-align: left">none</td></tr>
252<tr><td style="text-align: left"><a id="rust_bindgen_library-header"></a>header</td><td style="text-align: left">The label of the .h file to generate bindings for.</td><td style="text-align: left">none</td></tr>
253<tr><td style="text-align: left"><a id="rust_bindgen_library-cc_lib"></a>cc_lib</td><td style="text-align: left">The label of the cc_library that contains the .h file. This is used to find the transitive includes.</td><td style="text-align: left">none</td></tr>
254<tr><td style="text-align: left"><a id="rust_bindgen_library-bindgen_flags"></a>bindgen_flags</td><td style="text-align: left">Flags to pass directly to the bindgen executable. See https://rust-lang.github.io/rust-bindgen/ for details.</td><td style="text-align: left"><code>None</code></td></tr>
255<tr><td style="text-align: left"><a id="rust_bindgen_library-bindgen_features"></a>bindgen_features</td><td style="text-align: left">The <code>features</code> attribute for the <code>rust_bindgen</code> target.</td><td style="text-align: left"><code>None</code></td></tr>
256<tr><td style="text-align: left"><a id="rust_bindgen_library-clang_flags"></a>clang_flags</td><td style="text-align: left">Flags to pass directly to the clang executable.</td><td style="text-align: left"><code>None</code></td></tr>
257<tr><td style="text-align: left"><a id="rust_bindgen_library-wrap_static_fns"></a>wrap_static_fns</td><td style="text-align: left">Whether to create a separate .c file for static fns. Requires nightly toolchain, and a header that actually needs this feature (otherwise bindgen won't generate the file and Bazel complains",</td><td style="text-align: left"><code>False</code></td></tr>
258<tr><td style="text-align: left"><a id="rust_bindgen_library-kwargs"></a>kwargs</td><td style="text-align: left">Arguments to forward to the underlying <code>rust_library</code> rule.</td><td style="text-align: left">none</td></tr>
259</tbody></table>
260</div>
261                    </main>
262
263                    <nav class="nav-wrapper" aria-label="Page navigation">
264                        <!-- Mobile navigation buttons -->
265                            <a rel="prev" href="extensions.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
266                                <i class="fa fa-angle-left"></i>
267                            </a>
268
269                            <a rel="next prefetch" href="rust_prost.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
270                                <i class="fa fa-angle-right"></i>
271                            </a>
272
273                        <div style="clear: both"></div>
274                    </nav>
275                </div>
276            </div>
277
278            <nav class="nav-wide-wrapper" aria-label="Page navigation">
279                    <a rel="prev" href="extensions.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
280                        <i class="fa fa-angle-left"></i>
281                    </a>
282
283                    <a rel="next prefetch" href="rust_prost.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
284                        <i class="fa fa-angle-right"></i>
285                    </a>
286            </nav>
287
288        </div>
289
290
291
292
293        <script>
294            window.playground_copyable = true;
295        </script>
296
297
298        <script src="elasticlunr.min.js"></script>
299        <script src="mark.min.js"></script>
300        <script src="searcher.js"></script>
301
302        <script src="clipboard.min.js"></script>
303        <script src="highlight.js"></script>
304        <script src="book.js"></script>
305
306        <!-- Custom JS scripts -->
307
308
309    </div>
310    </body>
311</html>