From patchwork Fri Dec 15 23:54:28 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Miguel Ojeda X-Patchwork-Id: 179665 Return-Path: Delivered-To: ouuuleilei@gmail.com Received: by 2002:a05:7300:3b04:b0:fb:cd0c:d3e with SMTP id c4csp9652779dys; Fri, 15 Dec 2023 15:55:04 -0800 (PST) X-Google-Smtp-Source: AGHT+IFAUr1eSEL5/d6sumerqGW7bcD2nzs8XUKe4BnKbt2iUiHGlVsMWNa/UyMObydEzumUEivx X-Received: by 2002:a05:6214:226b:b0:67f:10e2:78b5 with SMTP id gs11-20020a056214226b00b0067f10e278b5mr3667562qvb.2.1702684503795; Fri, 15 Dec 2023 15:55:03 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1702684503; cv=none; d=google.com; s=arc-20160816; b=UezrMVdng79pEmNZUkPAFDyzr86XT8OuUIu+wtrgK3NJ2HaQM9RBFAFGIx9Z4d9r1j CApfhdqeIwKtI8X21/+IjXIJvNkd6JUc+As3HaKJxi44k1T9sEuNlr7MJYuoy89AEWdY KdwYa5FHu15RdSWaYEe+udYbeX3EzzFcyntVjs2IkQHGer950B5+xsaZRtIwU1gzYrR6 Hg+rNMwaK6kvGtBr7PJd0Gr4yLtL+yYVhVoMNjNEQywezg4LoW+ejOZhPnAZfTq0d3cg 3InT1A8Wfkw5zZFE/HznSWh/YDwa4EY+q8wpqjR0hrBHj5dPieO2mh8cd693mLvjLUlw EO+Q== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=content-transfer-encoding:mime-version:list-unsubscribe :list-subscribe:list-id:precedence:message-id:date:subject:cc:to :from:dkim-signature; bh=SH7jxONvs90Wq2b5IJ4QmfCvjqlfau9JtlVWPRai8OU=; fh=s23i2M5G94vcWeprlECsQxpSJb+PZLHe6uXSVignfi0=; b=gdeneeoS71cS3FBHb4+63dGcMy8ATtVv61fHTtyZPDQO5QAe1x6DWQgwYpJA1mcjEc Gjh0D8/ZWtVbCGLXTbj5PBoTu5pQTs0jv8wXKTs+gRS76jFguIJ4DJYIpDDgPL4UToOT pXf3HYcYLpCOPwD/JSbf0Fe3+7C5a8mJ+1fW76yqKwTBRsDzMBMiqmPOm5VrDtxm+IZ4 gdBe3sK5cmY7mN7rXxNXNAQdgJcfsYbJNJg4fuNh4EHSsLDGP73MaoUcEwYWYt3fL4pI SOClefqbYSgJwTSV8IDwZhIiDbMIg1NSmLbnBXAC1qjqh6CQg7MgW5avrSKmSwYfKpKI +S0Q== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@kernel.org header.s=k20201202 header.b=e+H1+RoN; spf=pass (google.com: domain of linux-kernel+bounces-1839-ouuuleilei=gmail.com@vger.kernel.org designates 147.75.199.223 as permitted sender) smtp.mailfrom="linux-kernel+bounces-1839-ouuuleilei=gmail.com@vger.kernel.org"; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=kernel.org Received: from ny.mirrors.kernel.org (ny.mirrors.kernel.org. [147.75.199.223]) by mx.google.com with ESMTPS id dz14-20020a05620a2b8e00b0077dcb1ca7cdsi20265217qkb.738.2023.12.15.15.55.03 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 15 Dec 2023 15:55:03 -0800 (PST) Received-SPF: pass (google.com: domain of linux-kernel+bounces-1839-ouuuleilei=gmail.com@vger.kernel.org designates 147.75.199.223 as permitted sender) client-ip=147.75.199.223; Authentication-Results: mx.google.com; dkim=pass header.i=@kernel.org header.s=k20201202 header.b=e+H1+RoN; spf=pass (google.com: domain of linux-kernel+bounces-1839-ouuuleilei=gmail.com@vger.kernel.org designates 147.75.199.223 as permitted sender) smtp.mailfrom="linux-kernel+bounces-1839-ouuuleilei=gmail.com@vger.kernel.org"; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=kernel.org Received: from smtp.subspace.kernel.org (wormhole.subspace.kernel.org [52.25.139.140]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ny.mirrors.kernel.org (Postfix) with ESMTPS id 861F61C243AF for ; Fri, 15 Dec 2023 23:55:03 +0000 (UTC) Received: from localhost.localdomain (localhost.localdomain [127.0.0.1]) by smtp.subspace.kernel.org (Postfix) with ESMTP id 1A18247F78; Fri, 15 Dec 2023 23:54:47 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b="e+H1+RoN" X-Original-To: linux-kernel@vger.kernel.org Received: from smtp.kernel.org (aws-us-west-2-korg-mail-1.web.codeaurora.org [10.30.226.201]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 5D24818ED4; Fri, 15 Dec 2023 23:54:43 +0000 (UTC) Received: by smtp.kernel.org (Postfix) with ESMTPSA id A9F32C433C7; Fri, 15 Dec 2023 23:54:40 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1702684483; bh=5EwYYWA8F0fFdNa4JLidqy5d/b0oDQvF9+4yyxXbMQ0=; h=From:To:Cc:Subject:Date:From; b=e+H1+RoNu20ySnrW/QcRqEgNPKscVc2hnDyrfmzdHfrt8dZDVf29ewaCQtP+NbkwG yHNqfHSo1/Wyzc+8pEsszU0a2AxkI705LozazQvf04+8wVF5fkHtUbc+bSUJDMa7/6 +a/h5PauT625HrTbtxxu7ISmsmiJm7S78ElNPgqKh7dpJ7vVIXR4cLv8M6zxy4nWw7 zCs/ZamfNfbn9g4zkvFVGVOGZ4QKvY2m85f2RhW9RcuW3M7piTHb0Qt2jm4erZCjyl ht1IIfpYJ2oOLsNmY21kAju+LATYcuQKnTRfqn2xj38eo3fPb3OfifqRnEgz62f05F YYLDy7qXWdlTQ== From: Miguel Ojeda To: Miguel Ojeda , Wedson Almeida Filho , Alex Gaynor Cc: Boqun Feng , Gary Guo , =?utf-8?q?Bj=C3=B6rn_Roy_Baron?= , Benno Lossin , Andreas Hindborg , Alice Ryhl , rust-for-linux@vger.kernel.org, linux-kernel@vger.kernel.org, patches@lists.linux.dev, FUJITA Tomonori Subject: [PATCH] rust: support `srctree`-relative links Date: Sat, 16 Dec 2023 00:54:28 +0100 Message-ID: <20231215235428.243211-1-ojeda@kernel.org> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 X-getmail-retrieved-from-mailbox: INBOX X-GMAIL-THRID: 1785394106418360197 X-GMAIL-MSGID: 1785394106418360197 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 Reported-by: FUJITA Tomonori 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 Reviewed-by: Martin Rodriguez Reboredo Reviewed-by: Benno Lossin --- 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 diff --git a/Documentation/rust/coding-guidelines.rst b/Documentation/rust/coding-guidelines.rst index aa8ed082613e..05542840b16c 100644 --- a/Documentation/rust/coding-guidelines.rst +++ b/Documentation/rust/coding-guidelines.rst @@ -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 ------ 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:::g' + -e 's:::g' \ + -e 's:::g' $(Q)for f in $(rustdoc_output)/static.files/rustdoc-*.css; do \ echo ".logo-container > img { object-fit: contain; }" >> $$f; done diff --git a/rust/kernel/error.rs b/rust/kernel/error.rs index 032b64543953..abd06afb2d76 100644 --- a/rust/kernel/error.rs +++ b/rust/kernel/error.rs @@ -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; diff --git a/rust/kernel/ioctl.rs b/rust/kernel/ioctl.rs index c49e1a8d3fd0..f1d42ab69972 100644 --- a/rust/kernel/ioctl.rs +++ b/rust/kernel/ioctl.rs @@ -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)] diff --git a/rust/kernel/kunit.rs b/rust/kernel/kunit.rs index 722655b2d62d..0ba77276ae7e 100644 --- a/rust/kernel/kunit.rs +++ b/rust/kernel/kunit.rs @@ -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: diff --git a/rust/kernel/print.rs b/rust/kernel/print.rs index f48926e3e9fe..9b13aca832c2 100644 --- a/rust/kernel/print.rs +++ b/rust/kernel/print.rs @@ -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: @@ -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<'_>) { diff --git a/rust/kernel/sync/condvar.rs b/rust/kernel/sync/condvar.rs index b679b6f6dbeb..f568802d4f8a 100644 --- a/rust/kernel/sync/condvar.rs +++ b/rust/kernel/sync/condvar.rs @@ -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] diff --git a/rust/kernel/sync/lock/mutex.rs b/rust/kernel/sync/lock/mutex.rs index 09276fedc091..8c524a3ec45a 100644 --- a/rust/kernel/sync/lock/mutex.rs +++ b/rust/kernel/sync/lock/mutex.rs @@ -84,7 +84,7 @@ macro_rules! new_mutex { /// } /// ``` /// -/// [`struct mutex`]: ../../../../include/linux/mutex.h +/// [`struct mutex`]: srctree/include/linux/mutex.h pub type Mutex = super::Lock; /// A kernel `struct mutex` lock backend. diff --git a/rust/kernel/sync/lock/spinlock.rs b/rust/kernel/sync/lock/spinlock.rs index 91eb2c9e9123..068535ce1b29 100644 --- a/rust/kernel/sync/lock/spinlock.rs +++ b/rust/kernel/sync/lock/spinlock.rs @@ -82,7 +82,7 @@ macro_rules! new_spinlock { /// } /// ``` /// -/// [`spinlock_t`]: ../../../../include/linux/spinlock.h +/// [`spinlock_t`]: srctree/include/linux/spinlock.h pub type SpinLock = super::Lock; /// A kernel `spinlock_t` lock backend. diff --git a/rust/kernel/task.rs b/rust/kernel/task.rs index b2299bc7ac1f..9451932d5d86 100644 --- a/rust/kernel/task.rs +++ b/rust/kernel/task.rs @@ -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}; diff --git a/rust/kernel/workqueue.rs b/rust/kernel/workqueue.rs index b67fb1ba168e..498397877376 100644 --- a/rust/kernel/workqueue.rs +++ b/rust/kernel/workqueue.rs @@ -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; diff --git a/rust/macros/lib.rs b/rust/macros/lib.rs index c42105c2ff96..3e3cb7449e58 100644 --- a/rust/macros/lib.rs +++ b/rust/macros/lib.rs @@ -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 ///