rust: support `srctree`-relative links
Commit Message
Some of our links use relative paths in order to point to files in the
source tree, e.g.:
//! C header: [`include/linux/printk.h`](../../../../include/linux/printk.h)
/// [`struct mutex`]: ../../../../include/linux/mutex.h
These are problematic because they are hard to maintain and do not support
`O=` builds.
Instead, provide support for `srctree`-relative links, e.g.:
//! C header: [`include/linux/printk.h`](srctree/include/linux/printk.h)
/// [`struct mutex`]: srctree/include/linux/mutex.h
The links are fixed after `rustdoc` generation to be based on the absolute
path to the source tree.
Essentially, this is the automatic version of Tomonori's fix [1],
suggested by Gary [2].
Suggested-by: Gary Guo <gary@garyguo.net>
Reported-by: FUJITA Tomonori <fujita.tomonori@gmail.com>
Closes: https://lore.kernel.org/r/20231026.204058.2167744626131849993.fujita.tomonori@gmail.com [1]
Fixes: 48fadf440075 ("docs: Move rustdoc output, cross-reference it")
Link: https://lore.kernel.org/rust-for-linux/20231026154525.6d14b495@eugeo/ [2]
Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
---
Documentation/rust/coding-guidelines.rst | 13 +++++++++++++
rust/Makefile | 3 ++-
rust/kernel/error.rs | 2 +-
rust/kernel/ioctl.rs | 2 +-
rust/kernel/kunit.rs | 2 +-
rust/kernel/print.rs | 8 ++++----
rust/kernel/sync/condvar.rs | 2 +-
rust/kernel/sync/lock/mutex.rs | 2 +-
rust/kernel/sync/lock/spinlock.rs | 2 +-
rust/kernel/task.rs | 2 +-
rust/kernel/workqueue.rs | 2 +-
rust/macros/lib.rs | 2 +-
12 files changed, 28 insertions(+), 14 deletions(-)
base-commit: a39b6ac3781d46ba18193c9dbb2110f31e9bffe9
Comments
On Sat, Dec 16, 2023 at 12:54 AM Miguel Ojeda <ojeda@kernel.org> wrote:
>
> Instead, provide support for `srctree`-relative links, e.g.:
If we decide to go this way, then I plan to send this to stable later on.
Cheers,
Miguel
On 12/15/23 20:54, Miguel Ojeda wrote:
> Some of our links use relative paths in order to point to files in the
> source tree, e.g.:
>
> //! C header: [`include/linux/printk.h`](../../../../include/linux/printk.h)
> /// [`struct mutex`]: ../../../../include/linux/mutex.h
>
> These are problematic because they are hard to maintain and do not support
> `O=` builds.
>
> Instead, provide support for `srctree`-relative links, e.g.:
>
> //! C header: [`include/linux/printk.h`](srctree/include/linux/printk.h)
> /// [`struct mutex`]: srctree/include/linux/mutex.h
>
> The links are fixed after `rustdoc` generation to be based on the absolute
> path to the source tree.
>
> Essentially, this is the automatic version of Tomonori's fix [1],
> suggested by Gary [2].
>
> Suggested-by: Gary Guo <gary@garyguo.net>
> Reported-by: FUJITA Tomonori <fujita.tomonori@gmail.com>
> Closes: https://lore.kernel.org/r/20231026.204058.2167744626131849993.fujita.tomonori@gmail.com [1]
> Fixes: 48fadf440075 ("docs: Move rustdoc output, cross-reference it")
> Link: https://lore.kernel.org/rust-for-linux/20231026154525.6d14b495@eugeo/ [2]
> Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
> ---
> Documentation/rust/coding-guidelines.rst | 13 +++++++++++++
> rust/Makefile | 3 ++-
> rust/kernel/error.rs | 2 +-
> rust/kernel/ioctl.rs | 2 +-
> rust/kernel/kunit.rs | 2 +-
> rust/kernel/print.rs | 8 ++++----
> rust/kernel/sync/condvar.rs | 2 +-
> rust/kernel/sync/lock/mutex.rs | 2 +-
> rust/kernel/sync/lock/spinlock.rs | 2 +-
> rust/kernel/task.rs | 2 +-
> rust/kernel/workqueue.rs | 2 +-
> rust/macros/lib.rs | 2 +-
> 12 files changed, 28 insertions(+), 14 deletions(-)
>
> diff --git a/Documentation/rust/coding-guidelines.rst b/Documentation/rust/coding-guidelines.rst
> index aa8ed082613e..05542840b16c 100644
> [...]
> diff --git a/rust/Makefile b/rust/Makefile
> index 543b37f6c77f..73ea24117f07 100644
> --- a/rust/Makefile
> +++ b/rust/Makefile
> @@ -98,7 +98,8 @@ rustdoc: rustdoc-core rustdoc-macros rustdoc-compiler_builtins \
> $(Q)find $(rustdoc_output) -name '*.html' -type f -print0 | xargs -0 sed -Ei \
> -e 's:rust-logo-[0-9a-f]+\.svg:logo.svg:g' \
> -e 's:favicon-[0-9a-f]+\.svg:logo.svg:g' \
> - -e 's:<link rel="alternate icon" type="image/png" href="[/.]+/static\.files/favicon-(16x16|32x32)-[0-9a-f]+\.png">::g'
> + -e 's:<link rel="alternate icon" type="image/png" href="[/.]+/static\.files/favicon-(16x16|32x32)-[0-9a-f]+\.png">::g' \
> + -e 's:<a href="srctree/([^"]+)">:<a href="$(abs_srctree)/\1">:g'
Another way would be to not put `srctree` in the link and add
`abs_srctree` here to directories that are in `srctree`. But that might
be too wonky to rely on so this will be the way to go.
> $(Q)for f in $(rustdoc_output)/static.files/rustdoc-*.css; do \
> echo ".logo-container > img { object-fit: contain; }" >> $$f; done
>
> [...]
Reviewed-by: Martin Rodriguez Reboredo <yakoyoku@gmail.com>
On 12/16/23 00:54, Miguel Ojeda wrote:
> Some of our links use relative paths in order to point to files in the
> source tree, e.g.:
>
> //! C header: [`include/linux/printk.h`](../../../../include/linux/printk.h)
> /// [`struct mutex`]: ../../../../include/linux/mutex.h
>
> These are problematic because they are hard to maintain and do not support
> `O=` builds.
>
> Instead, provide support for `srctree`-relative links, e.g.:
>
> //! C header: [`include/linux/printk.h`](srctree/include/linux/printk.h)
> /// [`struct mutex`]: srctree/include/linux/mutex.h
>
> The links are fixed after `rustdoc` generation to be based on the absolute
> path to the source tree.
>
> Essentially, this is the automatic version of Tomonori's fix [1],
> suggested by Gary [2].
>
> Suggested-by: Gary Guo <gary@garyguo.net>
> Reported-by: FUJITA Tomonori <fujita.tomonori@gmail.com>
> Closes: https://lore.kernel.org/r/20231026.204058.2167744626131849993.fujita.tomonori@gmail.com [1]
> Fixes: 48fadf440075 ("docs: Move rustdoc output, cross-reference it")
> Link: https://lore.kernel.org/rust-for-linux/20231026154525.6d14b495@eugeo/ [2]
> Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
This is nice.
Reviewed-by: Benno Lossin <benno.lossin@proton.me>
On Sat, Dec 16, 2023 at 12:54 AM Miguel Ojeda <ojeda@kernel.org> wrote:
>
> Some of our links use relative paths in order to point to files in the
> source tree, e.g.:
>
> //! C header: [`include/linux/printk.h`](../../../../include/linux/printk.h)
> /// [`struct mutex`]: ../../../../include/linux/mutex.h
>
> These are problematic because they are hard to maintain and do not support
> `O=` builds.
>
> Instead, provide support for `srctree`-relative links, e.g.:
>
> //! C header: [`include/linux/printk.h`](srctree/include/linux/printk.h)
> /// [`struct mutex`]: srctree/include/linux/mutex.h
>
> The links are fixed after `rustdoc` generation to be based on the absolute
> path to the source tree.
>
> Essentially, this is the automatic version of Tomonori's fix [1],
> suggested by Gary [2].
>
> Suggested-by: Gary Guo <gary@garyguo.net>
> Reported-by: FUJITA Tomonori <fujita.tomonori@gmail.com>
> Closes: https://lore.kernel.org/r/20231026.204058.2167744626131849993.fujita.tomonori@gmail.com [1]
> Fixes: 48fadf440075 ("docs: Move rustdoc output, cross-reference it")
> Link: https://lore.kernel.org/rust-for-linux/20231026154525.6d14b495@eugeo/ [2]
> Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
Applied to `rust-next` -- thanks everyone!
By the way, since I didn't mention it: this obviously requires the
source tree to be available at its path, so we may want to improve on
that later (e.g. exporting the needed files in the output folder), but
it is a strict improvement since it fixes the immediate issue, it
cleans the paths already reducing the maintenance burden (i.e. we can
keep the syntax even if we change the rest) and is a smaller change if
we decide to send it to stable later.
Cheers,
Miguel
@@ -177,6 +177,19 @@ please take a look at the ``rustdoc`` book at:
https://doc.rust-lang.org/rustdoc/how-to-write-documentation.html
+In addition, the kernel supports creating links relative to the source tree by
+prefixing the link destination with ``srctree/``. For instance:
+
+.. code-block:: rust
+
+ //! C header: [`include/linux/printk.h`](srctree/include/linux/printk.h)
+
+or:
+
+.. code-block:: rust
+
+ /// [`struct mutex`]: srctree/include/linux/mutex.h
+
Naming
------
@@ -98,7 +98,8 @@ rustdoc: rustdoc-core rustdoc-macros rustdoc-compiler_builtins \
$(Q)find $(rustdoc_output) -name '*.html' -type f -print0 | xargs -0 sed -Ei \
-e 's:rust-logo-[0-9a-f]+\.svg:logo.svg:g' \
-e 's:favicon-[0-9a-f]+\.svg:logo.svg:g' \
- -e 's:<link rel="alternate icon" type="image/png" href="[/.]+/static\.files/favicon-(16x16|32x32)-[0-9a-f]+\.png">::g'
+ -e 's:<link rel="alternate icon" type="image/png" href="[/.]+/static\.files/favicon-(16x16|32x32)-[0-9a-f]+\.png">::g' \
+ -e 's:<a href="srctree/([^"]+)">:<a href="$(abs_srctree)/\1">:g'
$(Q)for f in $(rustdoc_output)/static.files/rustdoc-*.css; do \
echo ".logo-container > img { object-fit: contain; }" >> $$f; done
@@ -2,7 +2,7 @@
//! Kernel errors.
//!
-//! C header: [`include/uapi/asm-generic/errno-base.h`](../../../include/uapi/asm-generic/errno-base.h)
+//! C header: [`include/uapi/asm-generic/errno-base.h`](srctree/include/uapi/asm-generic/errno-base.h)
use crate::str::CStr;
@@ -2,7 +2,7 @@
//! ioctl() number definitions
//!
-//! C header: [`include/asm-generic/ioctl.h`](../../../../include/asm-generic/ioctl.h)
+//! C header: [`include/asm-generic/ioctl.h`](srctree/include/asm-generic/ioctl.h)
#![allow(non_snake_case)]
@@ -2,7 +2,7 @@
//! KUnit-based macros for Rust unit tests.
//!
-//! C header: [`include/kunit/test.h`](../../../../../include/kunit/test.h)
+//! C header: [`include/kunit/test.h`](srctree/include/kunit/test.h)
//!
//! Reference: <https://docs.kernel.org/dev-tools/kunit/index.html>
@@ -2,7 +2,7 @@
//! Printing facilities.
//!
-//! C header: [`include/linux/printk.h`](../../../../include/linux/printk.h)
+//! C header: [`include/linux/printk.h`](srctree/include/linux/printk.h)
//!
//! Reference: <https://www.kernel.org/doc/html/latest/core-api/printk-basics.html>
@@ -48,7 +48,7 @@ pub mod format_strings {
/// The format string is always the same for a given level, i.e. for a
/// given `prefix`, which are the kernel's `KERN_*` constants.
///
- /// [`_printk`]: ../../../../include/linux/printk.h
+ /// [`_printk`]: srctree/include/linux/printk.h
const fn generate(is_cont: bool, prefix: &[u8; 3]) -> [u8; LENGTH] {
// Ensure the `KERN_*` macros are what we expect.
assert!(prefix[0] == b'\x01');
@@ -97,7 +97,7 @@ pub mod format_strings {
/// The format string must be one of the ones in [`format_strings`], and
/// the module name must be null-terminated.
///
-/// [`_printk`]: ../../../../include/linux/_printk.h
+/// [`_printk`]: srctree/include/linux/_printk.h
#[doc(hidden)]
#[cfg_attr(not(CONFIG_PRINTK), allow(unused_variables))]
pub unsafe fn call_printk(
@@ -120,7 +120,7 @@ pub unsafe fn call_printk(
///
/// Public but hidden since it should only be used from public macros.
///
-/// [`_printk`]: ../../../../include/linux/printk.h
+/// [`_printk`]: srctree/include/linux/printk.h
#[doc(hidden)]
#[cfg_attr(not(CONFIG_PRINTK), allow(unused_variables))]
pub fn call_printk_cont(args: fmt::Arguments<'_>) {
@@ -69,7 +69,7 @@ macro_rules! new_condvar {
/// }
/// ```
///
-/// [`struct wait_queue_head`]: ../../../include/linux/wait.h
+/// [`struct wait_queue_head`]: srctree/include/linux/wait.h
#[pin_data]
pub struct CondVar {
#[pin]
@@ -84,7 +84,7 @@ macro_rules! new_mutex {
/// }
/// ```
///
-/// [`struct mutex`]: ../../../../include/linux/mutex.h
+/// [`struct mutex`]: srctree/include/linux/mutex.h
pub type Mutex<T> = super::Lock<T, MutexBackend>;
/// A kernel `struct mutex` lock backend.
@@ -82,7 +82,7 @@ macro_rules! new_spinlock {
/// }
/// ```
///
-/// [`spinlock_t`]: ../../../../include/linux/spinlock.h
+/// [`spinlock_t`]: srctree/include/linux/spinlock.h
pub type SpinLock<T> = super::Lock<T, SpinLockBackend>;
/// A kernel `spinlock_t` lock backend.
@@ -2,7 +2,7 @@
//! Tasks (threads and processes).
//!
-//! C header: [`include/linux/sched.h`](../../../../include/linux/sched.h).
+//! C header: [`include/linux/sched.h`](srctree/include/linux/sched.h).
use crate::{bindings, types::Opaque};
use core::{marker::PhantomData, ops::Deref, ptr};
@@ -132,7 +132,7 @@
//! }
//! ```
//!
-//! C header: [`include/linux/workqueue.h`](../../../../include/linux/workqueue.h)
+//! C header: [`include/linux/workqueue.h`](srctree/include/linux/workqueue.h)
use crate::{bindings, prelude::*, sync::Arc, sync::LockClassKey, types::Opaque};
use alloc::alloc::AllocError;
@@ -20,7 +20,7 @@
/// The `type` argument should be a type which implements the [`Module`]
/// trait. Also accepts various forms of kernel metadata.
///
-/// C header: [`include/linux/moduleparam.h`](../../../include/linux/moduleparam.h)
+/// C header: [`include/linux/moduleparam.h`](srctree/include/linux/moduleparam.h)
///
/// [`Module`]: ../kernel/trait.Module.html
///