}sphinx.addnodesdocument)}( rawsourcechildren]( translations LanguagesNode)}(hhh](h pending_xref)}(hhh]docutils.nodesTextChinese (Simplified)}parenthsba attributes}(ids]classes]names]dupnames]backrefs] refdomainstdreftypedoc reftarget /translations/zh_CN/rust/testingmodnameN classnameN refexplicitutagnamehhh ubh)}(hhh]hChinese (Traditional)}hh2sbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget /translations/zh_TW/rust/testingmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hItalian}hhFsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget /translations/it_IT/rust/testingmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hJapanese}hhZsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget /translations/ja_JP/rust/testingmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hKorean}hhnsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget /translations/ko_KR/rust/testingmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hPortuguese (Brazilian)}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget /translations/pt_BR/rust/testingmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hSpanish}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget /translations/sp_SP/rust/testingmodnameN classnameN refexplicituh1hhh ubeh}(h]h ]h"]h$]h&]current_languageEnglishuh1h hh _documenthsourceNlineNubhcomment)}(h SPDX-License-Identifier: GPL-2.0h]h SPDX-License-Identifier: GPL-2.0}hhsbah}(h]h ]h"]h$]h&] xml:spacepreserveuh1hhhhhh:/var/lib/git/docbuild/linux/Documentation/rust/testing.rsthKubhsection)}(hhh](htitle)}(hTestingh]hTesting}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhhhKubh paragraph)}(hRThis document contains useful information how to test the Rust code in the kernel.h]hRThis document contains useful information how to test the Rust code in the kernel.}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(hThere are three sorts of tests:h]hThere are three sorts of tests:}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK hhhhubh bullet_list)}(hhh](h list_item)}(hThe KUnit tests.h]h)}(hjh]hThe KUnit tests.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK hjubah}(h]h ]h"]h$]h&]uh1jhhhhhhhNubj)}(hThe ``#[test]`` tests.h]h)}(hjh](hThe }(hjhhhNhNubhliteral)}(h ``#[test]``h]h#[test]}(hj&hhhNhNubah}(h]h ]h"]h$]h&]uh1j$hjubh tests.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK hjubah}(h]h ]h"]h$]h&]uh1jhhhhhhhNubj)}(hThe Kselftests. h]h)}(hThe Kselftests.h]hThe Kselftests.}(hjHhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK hjDubah}(h]h ]h"]h$]h&]uh1jhhhhhhhNubeh}(h]h ]h"]h$]h&]bullet-uh1hhhhK hhhhubh)}(hhh](h)}(hThe KUnit testsh]hThe KUnit tests}(hjghhhNhNubah}(h]h ]h"]h$]h&]uh1hhjdhhhhhKubh)}(hqThese are the tests that come from the examples in the Rust documentation. They get transformed into KUnit tests.h]hqThese are the tests that come from the examples in the Rust documentation. They get transformed into KUnit tests.}(hjuhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjdhhubh)}(hhh](h)}(hUsageh]hUsage}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubh)}(heThese tests can be run via KUnit. For example via ``kunit_tool`` (``kunit.py``) on the command line::h](h2These tests can be run via KUnit. For example via }(hjhhhNhNubj%)}(h``kunit_tool``h]h kunit_tool}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j$hjubh (}(hjhhhNhNubj%)}(h ``kunit.py``h]hkunit.py}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j$hjubh) on the command line:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh literal_block)}(hb./tools/testing/kunit/kunit.py run --make_options LLVM=1 --arch x86_64 --kconfig_add CONFIG_RUST=yh]hb./tools/testing/kunit/kunit.py run --make_options LLVM=1 --arch x86_64 --kconfig_add CONFIG_RUST=y}hjsbah}(h]h ]h"]h$]h&]hhuh1jhhhKhjhhubh)}(hXAlternatively, KUnit can run them as kernel built-in at boot. Refer to Documentation/dev-tools/kunit/index.rst for the general KUnit documentation and Documentation/dev-tools/kunit/architecture.rst for the details of kernel built-in vs. command line testing.h]hXAlternatively, KUnit can run them as kernel built-in at boot. Refer to Documentation/dev-tools/kunit/index.rst for the general KUnit documentation and Documentation/dev-tools/kunit/architecture.rst for the details of kernel built-in vs. command line testing.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(h Kernel Testing and Coverage -> KUnit - Enable support for unit tests CONFIG_RUST_KERNEL_DOCTESTS Kernel hacking -> Rust hacking -> Doctests for the `kernel` crateh]hCONFIG_KUNIT Kernel hacking -> Kernel Testing and Coverage -> KUnit - Enable support for unit tests CONFIG_RUST_KERNEL_DOCTESTS Kernel hacking -> Rust hacking -> Doctests for the `kernel` crate}hjsbah}(h]h ]h"]h$]h&]hhuh1jhhhK$hjhhubh)}(hin the kernel config system.h]hin the kernel config system.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK)hjhhubeh}(h]usageah ]h"]usageah$]h&]uh1hhjdhhhhhKubh)}(hhh](h)}(h#KUnit tests are documentation testsh]h#KUnit tests are documentation tests}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhK,ubh)}(hiThese documentation tests are typically examples of usage of any item (e.g. function, struct, module...).h]hiThese documentation tests are typically examples of usage of any item (e.g. function, struct, module...).}(hj'hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK.hjhhubh)}(haThey are very convenient because they are just written alongside the documentation. For instance:h]haThey are very convenient because they are just written alongside the documentation. For instance:}(hj5hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK1hjhhubj)}(h}/// Sums two numbers. /// /// ``` /// assert_eq!(mymod::f(10, 20), 30); /// ``` pub fn f(a: i32, b: i32) -> i32 { a + b }h]h}/// Sums two numbers. /// /// ``` /// assert_eq!(mymod::f(10, 20), 30); /// ``` pub fn f(a: i32, b: i32) -> i32 { a + b }}hjCsbah}(h]h ]h"]h$]h&]hhƌforcelanguagerusthighlight_args}uh1jhhhK4hjhhubh)}(hX"In userspace, the tests are collected and run via ``rustdoc``. Using the tool as-is would be useful already, since it allows verifying that examples compile (thus enforcing they are kept in sync with the code they document) and as well as running those that do not depend on in-kernel APIs.h](h2In userspace, the tests are collected and run via }(hjVhhhNhNubj%)}(h ``rustdoc``h]hrustdoc}(hj^hhhNhNubah}(h]h ]h"]h$]h&]uh1j$hjVubh. Using the tool as-is would be useful already, since it allows verifying that examples compile (thus enforcing they are kept in sync with the code they document) and as well as running those that do not depend on in-kernel APIs.}(hjVhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK?hjhhubh)}(hFor the kernel, however, these tests get transformed into KUnit test suites. This means that doctests get compiled as Rust kernel objects, allowing them to run against a built kernel.h]hFor the kernel, however, these tests get transformed into KUnit test suites. This means that doctests get compiled as Rust kernel objects, allowing them to run against a built kernel.}(hjvhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKDhjhhubh)}(hA benefit of this KUnit integration is that Rust doctests get to reuse existing testing facilities. For instance, the kernel log would look like::h]hA benefit of this KUnit integration is that Rust doctests get to reuse existing testing facilities. For instance, the kernel log would look like:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKHhjhhubj)}(hXKTAP version 1 1..1 KTAP version 1 # Subtest: rust_doctests_kernel 1..59 # rust_doctest_kernel_build_assert_rs_0.location: rust/kernel/build_assert.rs:13 ok 1 rust_doctest_kernel_build_assert_rs_0 # rust_doctest_kernel_build_assert_rs_1.location: rust/kernel/build_assert.rs:56 ok 2 rust_doctest_kernel_build_assert_rs_1 # rust_doctest_kernel_init_rs_0.location: rust/kernel/init.rs:122 ok 3 rust_doctest_kernel_init_rs_0 ... # rust_doctest_kernel_types_rs_2.location: rust/kernel/types.rs:150 ok 59 rust_doctest_kernel_types_rs_2 # rust_doctests_kernel: pass:59 fail:0 skip:0 total:59 # Totals: pass:59 fail:0 skip:0 total:59 ok 1 rust_doctests_kernelh]hXKTAP version 1 1..1 KTAP version 1 # Subtest: rust_doctests_kernel 1..59 # rust_doctest_kernel_build_assert_rs_0.location: rust/kernel/build_assert.rs:13 ok 1 rust_doctest_kernel_build_assert_rs_0 # rust_doctest_kernel_build_assert_rs_1.location: rust/kernel/build_assert.rs:56 ok 2 rust_doctest_kernel_build_assert_rs_1 # rust_doctest_kernel_init_rs_0.location: rust/kernel/init.rs:122 ok 3 rust_doctest_kernel_init_rs_0 ... # rust_doctest_kernel_types_rs_2.location: rust/kernel/types.rs:150 ok 59 rust_doctest_kernel_types_rs_2 # rust_doctests_kernel: pass:59 fail:0 skip:0 total:59 # Totals: pass:59 fail:0 skip:0 total:59 ok 1 rust_doctests_kernel}hjsbah}(h]h ]h"]h$]h&]hhuh1jhhhKKhjhhubh)}(hTests using the `? `_ operator are also supported as usual, e.g.:h](hTests using the }(hjhhhNhNubh reference)}(hd`? `_h]h?}(hjhhhNhNubah}(h]h ]h"]h$]h&]name?refuri]https://doc.rust-lang.org/reference/expressions/operator-expr.html#the-question-mark-operatoruh1jhjubhtarget)}(h` h]h}(h]id1ah ]h"]?ah$]h&]refurijuh1j referencedKhjubh, operator are also supported as usual, e.g.:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK]hjhhubj)}(h/// ``` /// # use kernel::{spawn_work_item, workqueue}; /// spawn_work_item!(workqueue::system(), || pr_info!("x\n"))?; /// # Ok::<(), Error>(()) /// ```h]h/// ``` /// # use kernel::{spawn_work_item, workqueue}; /// spawn_work_item!(workqueue::system(), || pr_info!("x\n"))?; /// # Ok::<(), Error>(()) /// ```}hjsbah}(h]h ]h"]h$]h&]hhjQjRrustjT}uh1jhhhK`hjhhubh)}(h|The tests are also compiled with Clippy under ``CLIPPY=1``, just like normal code, thus also benefitting from extra linting.h](h.The tests are also compiled with Clippy under }(hjhhhNhNubj%)}(h ``CLIPPY=1``h]hCLIPPY=1}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j$hjubhB, just like normal code, thus also benefitting from extra linting.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhhjhhubh)}(hIn order for developers to easily see which line of doctest code caused a failure, a KTAP diagnostic line is printed to the log. This contains the location (file and line) of the original test (i.e. instead of the location in the generated Rust file)::h]hIn order for developers to easily see which line of doctest code caused a failure, a KTAP diagnostic line is printed to the log. This contains the location (file and line) of the original test (i.e. instead of the location in the generated Rust file):}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKkhjhhubj)}(hC# rust_doctest_kernel_types_rs_2.location: rust/kernel/types.rs:150h]hC# rust_doctest_kernel_types_rs_2.location: rust/kernel/types.rs:150}hjsbah}(h]h ]h"]h$]h&]hhuh1jhhhKphjhhubh)}(hXRust tests appear to assert using the usual ``assert!`` and ``assert_eq!`` macros from the Rust standard library (``core``). We provide a custom version that forwards the call to KUnit instead. Importantly, these macros do not require passing context, unlike those for KUnit testing (i.e. ``struct kunit *``). This makes them easier to use, and readers of the documentation do not need to care about which testing framework is used. In addition, it may allow us to test third-party code more easily in the future.h](h,Rust tests appear to assert using the usual }(hj"hhhNhNubj%)}(h ``assert!``h]hassert!}(hj*hhhNhNubah}(h]h ]h"]h$]h&]uh1j$hj"ubh and }(hj"hhhNhNubj%)}(h``assert_eq!``h]h assert_eq!}(hj<hhhNhNubah}(h]h ]h"]h$]h&]uh1j$hj"ubh( macros from the Rust standard library (}(hj"hhhNhNubj%)}(h``core``h]hcore}(hjNhhhNhNubah}(h]h ]h"]h$]h&]uh1j$hj"ubh). We provide a custom version that forwards the call to KUnit instead. Importantly, these macros do not require passing context, unlike those for KUnit testing (i.e. }(hj"hhhNhNubj%)}(h``struct kunit *``h]hstruct kunit *}(hj`hhhNhNubah}(h]h ]h"]h$]h&]uh1j$hj"ubh). This makes them easier to use, and readers of the documentation do not need to care about which testing framework is used. In addition, it may allow us to test third-party code more easily in the future.}(hj"hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKrhjhhubh)}(hA current limitation is that KUnit does not support assertions in other tasks. Thus, we presently simply print an error to the kernel log if an assertion actually failed. Additionally, doctests are not run for nonpublic functions.h]hA current limitation is that KUnit does not support assertions in other tasks. Thus, we presently simply print an error to the kernel log if an assertion actually failed. Additionally, doctests are not run for nonpublic functions.}(hjxhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKzhjhhubh)}(hSince these tests are examples, i.e. they are part of the documentation, they should generally be written like "real code". Thus, for example, instead of using ``unwrap()`` or ``expect()``, use the ``?`` operator. For more background, please see:h](hSince these tests are examples, i.e. they are part of the documentation, they should generally be written like “real code”. Thus, for example, instead of using }(hjhhhNhNubj%)}(h ``unwrap()``h]hunwrap()}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j$hjubh or }(hjhhhNhNubj%)}(h ``expect()``h]hexpect()}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j$hjubh , use the }(hjhhhNhNubj%)}(h``?``h]h?}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j$hjubh+ operator. For more background, please see:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK~hjhhubh block_quote)}(hUhttps://rust.docs.kernel.org/kernel/error/type.Result.html#error-codes-in-c-and-rust h]h)}(hThttps://rust.docs.kernel.org/kernel/error/type.Result.html#error-codes-in-c-and-rusth]j)}(hjh]hThttps://rust.docs.kernel.org/kernel/error/type.Result.html#error-codes-in-c-and-rust}(hjhhhNhNubah}(h]h ]h"]h$]h&]refurijuh1jhjubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhhhKhjhhubeh}(h]#kunit-tests-are-documentation-testsah ]h"]#kunit tests are documentation testsah$]h&]uh1hhjdhhhhhK,ubeh}(h]the-kunit-testsah ]h"]the kunit testsah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(hThe ``#[test]`` testsh](hThe }(hjhhhNhNubj%)}(h ``#[test]``h]h#[test]}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j$hjubh tests}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhjhhhhhKubh)}(hAdditionally, there are the ``#[test]`` tests. Like for documentation tests, these are also fairly similar to what you would expect from userspace, and they are also mapped to KUnit.h](hAdditionally, there are the }(hj!hhhNhNubj%)}(h ``#[test]``h]h#[test]}(hj)hhhNhNubah}(h]h ]h"]h$]h&]uh1j$hj!ubh tests. Like for documentation tests, these are also fairly similar to what you would expect from userspace, and they are also mapped to KUnit.}(hj!hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hzThese tests are introduced by the ``kunit_tests`` procedural macro, which takes the name of the test suite as an argument.h](h"These tests are introduced by the }(hjAhhhNhNubj%)}(h``kunit_tests``h]h kunit_tests}(hjIhhhNhNubah}(h]h ]h"]h$]h&]uh1j$hjAubhI procedural macro, which takes the name of the test suite as an argument.}(hjAhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hVEach test suite should be guarded by a Kconfig option in ``rust/kernel/Kconfig.test``.h](h9Each test suite should be guarded by a Kconfig option in }(hjahhhNhNubj%)}(h``rust/kernel/Kconfig.test``h]hrust/kernel/Kconfig.test}(hjihhhNhNubah}(h]h ]h"]h$]h&]uh1j$hjaubh.}(hjahhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hFor instance, assume we want to test the function ``f`` from the documentation tests section. We could write, in the same file where we have our function:h](h2For instance, assume we want to test the function }(hjhhhNhNubj%)}(h``f``h]hf}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j$hjubhc from the documentation tests section. We could write, in the same file where we have our function:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj)}(h#[cfg(CONFIG_RUST_MYMOD_KUNIT_TEST)] #[kunit_tests(rust_kernel_mymod)] mod tests { use super::*; #[test] fn test_f() { assert_eq!(f(10, 20), 30); } }h]h#[cfg(CONFIG_RUST_MYMOD_KUNIT_TEST)] #[kunit_tests(rust_kernel_mymod)] mod tests { use super::*; #[test] fn test_f() { assert_eq!(f(10, 20), 30); } }}hjsbah}(h]h ]h"]h$]h&]hhjQjRrustjT}uh1jhhhKhjhhubh)}(h2And if we run it, the kernel log would look like::h]h1And if we run it, the kernel log would look like:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj)}(h KTAP version 1 # Subtest: rust_kernel_mymod # speed: normal 1..1 # test_f.speed: normal ok 1 test_f ok 1 rust_kernel_mymodh]h KTAP version 1 # Subtest: rust_kernel_mymod # speed: normal 1..1 # test_f.speed: normal ok 1 test_f ok 1 rust_kernel_mymod}hjsbah}(h]h ]h"]h$]h&]hhuh1jhhhKhjhhubh)}(hXLike documentation tests, the ``assert!`` and ``assert_eq!`` macros are mapped back to KUnit and do not panic. Similarly, the `? `_ operator is supported, i.e. the test functions may return either nothing (i.e. the unit type ``()``) or ``Result`` (i.e. any ``Result``). For instance:h](hLike documentation tests, the }(hjhhhNhNubj%)}(h ``assert!``h]hassert!}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j$hjubh and }(hjhhhNhNubj%)}(h``assert_eq!``h]h assert_eq!}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j$hjubhB macros are mapped back to KUnit and do not panic. Similarly, the }(hjhhhNhNubj)}(hd`? `_h]h?}(hjhhhNhNubah}(h]h ]h"]h$]h&]namejj]https://doc.rust-lang.org/reference/expressions/operator-expr.html#the-question-mark-operatoruh1jhjubj)}(h` h]h}(h]id2ah ]h"]h$]?ah&]refurijuh1jjKhjubh^ operator is supported, i.e. the test functions may return either nothing (i.e. the unit type }(hjhhhNhNubj%)}(h``()``h]h()}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j$hjubh) or }(hjhhhNhNubj%)}(h ``Result``h]hResult}(hj,hhhNhNubah}(h]h ]h"]h$]h&]uh1j$hjubh (i.e. any }(hjhhhNhNubj%)}(h``Result``h]h Result}(hj>hhhNhNubah}(h]h ]h"]h$]h&]uh1j$hjubh). For instance:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj)}(h#[cfg(CONFIG_RUST_MYMOD_KUNIT_TEST)] #[kunit_tests(rust_kernel_mymod)] mod tests { use super::*; #[test] fn test_g() -> Result { let x = g()?; assert_eq!(x, 30); Ok(()) } }h]h#[cfg(CONFIG_RUST_MYMOD_KUNIT_TEST)] #[kunit_tests(rust_kernel_mymod)] mod tests { use super::*; #[test] fn test_g() -> Result { let x = g()?; assert_eq!(x, 30); Ok(()) } }}hjVsbah}(h]h ]h"]h$]h&]hhjQjRrustjT}uh1jhhhKhjhhubh)}(hPIf we run the test and the call to ``g`` fails, then the kernel log would show::h](h#If we run the test and the call to }(hjfhhhNhNubj%)}(h``g``h]hg}(hjnhhhNhNubah}(h]h ]h"]h$]h&]uh1j$hjfubh' fails, then the kernel log would show:}(hjfhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj)}(hX KTAP version 1 # Subtest: rust_kernel_mymod # speed: normal 1..1 # test_g: ASSERTION FAILED at rust/kernel/lib.rs:335 Expected is_test_result_ok(test_g()) to be true, but is false # test_g.speed: normal not ok 1 test_g not ok 1 rust_kernel_mymodh]hX KTAP version 1 # Subtest: rust_kernel_mymod # speed: normal 1..1 # test_g: ASSERTION FAILED at rust/kernel/lib.rs:335 Expected is_test_result_ok(test_g()) to be true, but is false # test_g.speed: normal not ok 1 test_g not ok 1 rust_kernel_mymod}hjsbah}(h]h ]h"]h$]h&]hhuh1jhhhKhjhhubh)}(hIf a ``#[test]`` test could be useful as an example for the user, then please use a documentation test instead. Even edge cases of an API, e.g. error or boundary cases, can be interesting to show in examples.h](hIf a }(hjhhhNhNubj%)}(h ``#[test]``h]h#[test]}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j$hjubh test could be useful as an example for the user, then please use a documentation test instead. Even edge cases of an API, e.g. error or boundary cases, can be interesting to show in examples.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubeh}(h]the-test-testsah ]h"]the #[test] testsah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(hThe ``rusttest`` host testsh](hThe }(hjhhhNhNubj%)}(h ``rusttest``h]hrusttest}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j$hjubh host tests}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhjhhhhhKubh)}(hThese are userspace tests that can be built and run in the host (i.e. the one that performs the kernel build) using the ``rusttest`` Make target::h](hxThese are userspace tests that can be built and run in the host (i.e. the one that performs the kernel build) using the }(hjhhhNhNubj%)}(h ``rusttest``h]hrusttest}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j$hjubh Make target:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj)}(hmake LLVM=1 rusttesth]hmake LLVM=1 rusttest}hjsbah}(h]h ]h"]h$]h&]hhuh1jhhhKhjhhubh)}(h%This requires the kernel ``.config``.h](hThis requires the kernel }(hj hhhNhNubj%)}(h ``.config``h]h.config}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j$hj ubh.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hLCurrently, they are mostly used for testing the ``macros`` crate's examples.h](h0Currently, they are mostly used for testing the }(hj-hhhNhNubj%)}(h ``macros``h]hmacros}(hj5hhhNhNubah}(h]h ]h"]h$]h&]uh1j$hj-ubh crate’s examples.}(hj-hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubeh}(h]the-rusttest-host-testsah ]h"]the rusttest host testsah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(hThe Kselftestsh]hThe Kselftests}(hjXhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjUhhhhhKubh)}(hMKselftests are also available in the ``tools/testing/selftests/rust`` folder.h](h%Kselftests are also available in the }(hjfhhhNhNubj%)}(h ``tools/testing/selftests/rust``h]htools/testing/selftests/rust}(hjnhhhNhNubah}(h]h ]h"]h$]h&]uh1j$hjfubh folder.}(hjfhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjUhhubh)}(hThe kernel config options required for the tests are listed in the ``tools/testing/selftests/rust/config`` file and can be included with the aid of the ``merge_config.sh`` script::h](hCThe kernel config options required for the tests are listed in the }(hjhhhNhNubj%)}(h'``tools/testing/selftests/rust/config``h]h#tools/testing/selftests/rust/config}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j$hjubh. file and can be included with the aid of the }(hjhhhNhNubj%)}(h``merge_config.sh``h]hmerge_config.sh}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j$hjubh script:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjUhhubj)}(hM./scripts/kconfig/merge_config.sh .config tools/testing/selftests/rust/configh]hM./scripts/kconfig/merge_config.sh .config tools/testing/selftests/rust/config}hjsbah}(h]h ]h"]h$]h&]hhuh1jhhhKhjUhhubh)}(hThe kselftests are built within the kernel source tree and are intended to be executed on a system that is running the same kernel.h]hThe kselftests are built within the kernel source tree and are intended to be executed on a system that is running the same kernel.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjUhhubh)}(hOnce a kernel matching the source tree has been installed and booted, the tests can be compiled and executed using the following command::h]hOnce a kernel matching the source tree has been installed and booted, the tests can be compiled and executed using the following command:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjUhhubj)}(hmake TARGETS="rust" kselftesth]hmake TARGETS="rust" kselftest}hjsbah}(h]h ]h"]h$]h&]hhuh1jhhhKhjUhhubh)}(hWRefer to Documentation/dev-tools/kselftest.rst for the general Kselftest documentation.h]hWRefer to Documentation/dev-tools/kselftest.rst for the general Kselftest documentation.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjUhhubeh}(h]the-kselftestsah ]h"]the kselftestsah$]h&]uh1hhhhhhhhKubeh}(h]testingah ]h"]testingah$]h&]uh1hhhhhhhhKubeh}(h]h ]h"]h$]h&]sourcehuh1hcurrent_sourceN current_lineNsettingsdocutils.frontendValues)}(hN generatorN datestampN source_linkN source_urlN toc_backlinksentryfootnote_backlinksK sectnum_xformKstrip_commentsNstrip_elements_with_classesN strip_classesN report_levelK halt_levelKexit_status_levelKdebugNwarning_streamN tracebackinput_encoding utf-8-siginput_encoding_error_handlerstrictoutput_encodingutf-8output_encoding_error_handlerj1error_encodingutf-8error_encoding_error_handlerbackslashreplace language_codeenrecord_dependenciesNconfigN id_prefixhauto_id_prefixid dump_settingsNdump_internalsNdump_transformsNdump_pseudo_xmlNexpose_internalsNstrict_visitorN_disable_configN_sourcehnj _destinationN _config_files]7/var/lib/git/docbuild/linux/Documentation/docutils.confafile_insertion_enabled raw_enabledKline_length_limitM'pep_referencesN pep_base_urlhttps://peps.python.org/pep_file_url_templatepep-%04drfc_referencesN rfc_base_url&https://datatracker.ietf.org/doc/html/ tab_widthKtrim_footnote_reference_spacesyntax_highlightlong smart_quotessmartquotes_locales]character_level_inline_markupdoctitle_xform docinfo_xformKsectsubtitle_xform image_loadinglinkembed_stylesheetcloak_email_addressessection_self_linkenvNubreporterNindirect_targets]substitution_defs}substitution_names}refnames}refids}nameids}(j jjjjjjjjjjjjRjOjju nametypes}(j jjjjjjRjuh}(jhjjdjjjjjjjjjj jOjjjUu footnote_refs} citation_refs} autofootnotes]autofootnote_refs]symbol_footnotes]symbol_footnote_refs] footnotes] citations]autofootnote_startKsymbol_footnote_startK id_counter collectionsCounter}j?KsRparse_messages]hsystem_message)}(hhh]h)}(h$Duplicate explicit target name: "?".h]h(Duplicate explicit target name: “?”.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubah}(h]h ]h"]h$]h&]jalevelKtypeINFOsourcehnjlineKuh1jhjhhhhhKubatransform_messages] transformerN include_log] decorationNhhub.