Documentation/dev-tools/kunit/start.rst

Source file repositories/reference/linux-study-clean/Documentation/dev-tools/kunit/start.rst

File Facts

System: Linux kernel
Corpus path: Documentation/dev-tools/kunit/start.rst
Extension: .rst
Size: 10005 bytes
Lines: 310
Domain: Support Tooling And Documentation
Bucket: Documentation
Inferred role: Support Tooling And Documentation: documentation
Status: atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.
Defines or uses C structs; map object ownership, embedded links, reference counts, and lock ownership.

Dependency Surface

linux/errno.h
example.h
kunit/test.h

Detected Declarations

function misc_example_add
function misc_example_add_test_basic
function misc_example_test_failure

Annotated Snippet

.. SPDX-License-Identifier: GPL-2.0

===============
Getting Started
===============

This page contains an overview of the kunit_tool and KUnit framework,
teaching how to run existing tests and then how to write a simple test case,
and covers common problems users face when using KUnit for the first time.

Installing Dependencies
=======================
KUnit has the same dependencies as the Linux kernel. As long as you can
build the kernel, you can run KUnit.

Running tests with kunit_tool
=============================
kunit_tool is a Python script, which configures and builds a kernel, runs
tests, and formats the test results. From the kernel repository, you
can run kunit_tool:

.. code-block:: bash

	./tools/testing/kunit/kunit.py run

.. note ::
	You may see the following error:
	"The source tree is not clean, please run 'make ARCH=um mrproper'"

	This happens because internally kunit.py specifies ``.kunit``
	(default option) as the build directory in the command ``make O=output/dir``
	through the argument ``--build_dir``.  Hence, before starting an
	out-of-tree build, the source tree must be clean.

	There is also the same caveat mentioned in the "Build directory for
	the kernel" section of the :doc:`admin-guide </admin-guide/README>`,
	that is, its use, it must be used for all invocations of ``make``.
	The good news is that it can indeed be solved by running
	``make ARCH=um mrproper``, just be aware that this will delete the
	current configuration and all generated files.

If everything worked correctly, you should see the following:

.. code-block::

	Configuring KUnit Kernel ...
	Building KUnit Kernel ...
	Starting KUnit Kernel ...

The tests will pass or fail.

.. note ::
   Because it is building a lot of sources for the first time,
   the ``Building KUnit Kernel`` step may take a while.

For detailed information on this wrapper, see:
Documentation/dev-tools/kunit/run_wrapper.rst.

Selecting which tests to run
----------------------------

By default, kunit_tool runs all tests reachable with minimal configuration,
that is, using default values for most of the kconfig options.  However,
you can select which tests to run by:

- `Customizing Kconfig`_ used to compile the kernel, or
- `Filtering tests by name`_ to select specifically which compiled tests to run.

Customizing Kconfig
~~~~~~~~~~~~~~~~~~~

Annotation

Immediate include surface: `linux/errno.h`, `example.h`, `kunit/test.h`.
Detected declarations: `function misc_example_add`, `function misc_example_add_test_basic`, `function misc_example_test_failure`.
Atlas domain: Support Tooling And Documentation / Documentation.
Implementation status: atlas-only.

Implementation Notes

This generated page is the file-by-file coverage layer; curated subsystem chapters should link here when they synthesize a multi-file control flow.
Core OS pages should be promoted from atlas-only to deep-reviewed when they explain data structures, invariants, locking, lifecycle, and C implementation snippets.
Driver-family pages are intentionally pattern-oriented unless they are part of the selected PCIe/NVMe representative device path.