Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Doc improvements #35

Merged
merged 2 commits into from
Nov 28, 2020
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 41 additions & 0 deletions Documentation/rust/coding.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
.. _rust_coding:

Coding
======

This document describes how to write Rust code in the kernel.


Coding style
------------

For the moment, we are following the idiomatic Rust style. For instance,
we use 4 spaces for indentation rather than tabs.


Abstractions vs. bindings
-------------------------

We don't have abstractions for all the kernel internal APIs and concepts,
but we would like to expand coverage as time goes on. Unless there is
a good reason not to, always use the abstractions instead of calling
the C bindings directly.

If you are writing some code that requires a call to an internal kernel API
or concept that isn't abstracted yet, consider providing an (ideally safe)
abstraction for everyone to use.


Conditional compilation
-----------------------

Rust code has access to conditional compilation based on the kernel
configuration:

.. code-block:: rust

#[cfg(CONFIG_X)] // `CONFIG_X` is enabled (`y` or `m`)
#[cfg(CONFIG_X="y")] // `CONFIG_X` is enabled as a built-in (`y`)
#[cfg(CONFIG_X="m")] // `CONFIG_X` is enabled as a module (`m`)
#[cfg(not(CONFIG_X))] // `CONFIG_X` is disabled

4 changes: 3 additions & 1 deletion Documentation/rust/index.rst
Original file line number Diff line number Diff line change
@@ -1,12 +1,14 @@
Rust
====

Documentation related to Rust within the kernel. If you are starting out, read the :ref:`Documentation/rust/quick-start.rst <rust_quick_start>` guide.
Documentation related to Rust within the kernel. If you are starting out,
read the :ref:`Documentation/rust/quick-start.rst <rust_quick_start>` guide.

.. toctree::
:maxdepth: 1

quick-start
coding

.. only:: subproject and html

Expand Down
25 changes: 19 additions & 6 deletions Documentation/rust/quick-start.rst
Original file line number Diff line number Diff line change
Expand Up @@ -5,43 +5,56 @@ Quick Start

This document describes how to get started with Rust kernel development.


Requirements
------------

A recent nightly Rust toolchain (at least ``rustc``, ``cargo`` and ``rustfmt``) is required, e.g. `nightly-2020-08-27`. In the future, this restriction will be lifted. If you are using ``rustup``, run::
A recent nightly Rust toolchain (at least ``rustc``, ``cargo`` and ``rustfmt``)
is required, e.g. ``nightly-2020-08-27``. In the future, this restriction
will be lifted. If you are using ``rustup``, run::

rustup toolchain install nightly

Otherwise, fetch a standalone installer from:

https://www.rust-lang.org

The sources for the compiler are required to be available. If you are using ``rustup``, run::
The sources for the compiler are required to be available. If you are using
``rustup``, run::

rustup component add rust-src

Otherwise, if you used a standalone installer, you can clone the Rust compiler sources and create a symlink to them in the installation folder of your nightly toolchain::
Otherwise, if you used a standalone installer, you can clone the Rust compiler
sources and create a symlink to them in the installation folder of
your nightly toolchain::

git clone https://github.com/rust-lang/rust
ln -s rust .../rust-nightly/lib/rustlib/src


Testing a simple driver
-----------------------

If the kernel configuration system is able to find ``rustc`` and ``cargo``, it will enable Rust support (``CONFIG_HAS_RUST``). In turn, this will make visible the rest of options that depend on Rust.
If the kernel configuration system is able to find ``rustc`` and ``cargo``,
it will enable Rust support (``CONFIG_HAS_RUST``). In turn, this will make
visible the rest of options that depend on Rust.

A simple driver you can compile to test things out is at ``drivers/char/rust_example`` (``CONFIG_RUST_EXAMPLE``). Enable it and compile the kernel with:
A simple driver you can compile to test things out is at
``drivers/char/rust_example`` (``CONFIG_RUST_EXAMPLE``). Enable it and compile
the kernel with:

make LLVM=1

TODO: drop LLVM=1, allowing to mix GCC with LLVM


Avoiding the network
--------------------

You can prefetch the dependencies that ``cargo`` will download by running::

cargo fetch

in the kernel sources root. After this step, a network connection is not needed anymore.
in the kernel sources root. After this step, a network connection is
not needed anymore.