Commit | Line | Data |
---|---|---|
d07479b2 MO |
1 | .. SPDX-License-Identifier: GPL-2.0 |
2 | ||
3 | General Information | |
4 | =================== | |
5 | ||
6 | This document contains useful information to know when working with | |
7 | the Rust support in the kernel. | |
8 | ||
9 | ||
10 | Code documentation | |
11 | ------------------ | |
12 | ||
13 | Rust kernel code is documented using ``rustdoc``, its built-in documentation | |
14 | generator. | |
15 | ||
16 | The generated HTML docs include integrated search, linked items (e.g. types, | |
17 | functions, constants), source code, etc. They may be read at (TODO: link when | |
18 | in mainline and generated alongside the rest of the documentation): | |
19 | ||
20 | http://kernel.org/ | |
21 | ||
22 | The docs can also be easily generated and read locally. This is quite fast | |
23 | (same order as compiling the code itself) and no special tools or environment | |
24 | are needed. This has the added advantage that they will be tailored to | |
25 | the particular kernel configuration used. To generate them, use the ``rustdoc`` | |
26 | target with the same invocation used for compilation, e.g.:: | |
27 | ||
28 | make LLVM=1 rustdoc | |
29 | ||
30 | To read the docs locally in your web browser, run e.g.:: | |
31 | ||
32 | xdg-open rust/doc/kernel/index.html | |
33 | ||
34 | To learn about how to write the documentation, please see coding-guidelines.rst. | |
35 | ||
36 | ||
37 | Extra lints | |
38 | ----------- | |
39 | ||
40 | While ``rustc`` is a very helpful compiler, some extra lints and analyses are | |
41 | available via ``clippy``, a Rust linter. To enable it, pass ``CLIPPY=1`` to | |
42 | the same invocation used for compilation, e.g.:: | |
43 | ||
44 | make LLVM=1 CLIPPY=1 | |
45 | ||
46 | Please note that Clippy may change code generation, thus it should not be | |
47 | enabled while building a production kernel. | |
48 | ||
49 | ||
50 | Abstractions vs. bindings | |
51 | ------------------------- | |
52 | ||
53 | Abstractions are Rust code wrapping kernel functionality from the C side. | |
54 | ||
55 | In order to use functions and types from the C side, bindings are created. | |
56 | Bindings are the declarations for Rust of those functions and types from | |
57 | the C side. | |
58 | ||
59 | For instance, one may write a ``Mutex`` abstraction in Rust which wraps | |
60 | a ``struct mutex`` from the C side and calls its functions through the bindings. | |
61 | ||
62 | Abstractions are not available for all the kernel internal APIs and concepts, | |
63 | but it is intended that coverage is expanded as time goes on. "Leaf" modules | |
64 | (e.g. drivers) should not use the C bindings directly. Instead, subsystems | |
65 | should provide as-safe-as-possible abstractions as needed. | |
66 | ||
67 | ||
68 | Conditional compilation | |
69 | ----------------------- | |
70 | ||
71 | Rust code has access to conditional compilation based on the kernel | |
72 | configuration: | |
73 | ||
74 | .. code-block:: rust | |
75 | ||
76 | #[cfg(CONFIG_X)] // Enabled (`y` or `m`) | |
77 | #[cfg(CONFIG_X="y")] // Enabled as a built-in (`y`) | |
78 | #[cfg(CONFIG_X="m")] // Enabled as a module (`m`) | |
79 | #[cfg(not(CONFIG_X))] // Disabled |