=============
Getting KUnit
=============

In order to use KUnit, you must first determine which branch you would like to
use. What do we mean by that? We are in the process of upstreaming KUnit into
the Linux kernel, so that means we have code under development that is not in
the upstream repository or otherwise doesn't match what is currently upstream.

For more information on why there are multiple versions of KUnit, see
:ref:`why-multiple-versions`.

For information on deciding which version you should use see
:ref:`which-version`.

For the actual URL you need, see
:ref:`download-links`

.. _why-multiple-versions:

Why are there multiple versions?
================================

Ideally, upstreaming code to the Linux kernel would be fast, we would be able to
develop features entirely on LKML, no one would use code that had not yet been
accepted upstream, and everything would have been done this way from the start.
Unfortunately, we do not live in a perfect world, and consequently none of these
are true.

This means that there are some features that we've developed which aren't yet
going upstream. We've developed these in an *experimental* branch. This is
basically a staging branch for features we're still actively experimenting with,
or which depend on code which isn't yet upstream.


But wait, I see more than two branches!
---------------------------------------

For the upstream version, just use torvalds/master. Our *experimental* branch is
hosted at https://kunit.googlesource.com/linux/+/kunit/alpha/master.

We will be periodically replacing the *experimental* branch with one based on
newer upstream kernels, in order to minimise the divergence between
*experimental* and upstream. For more details on how this will work, see:
https://lore.kernel.org/linux-kselftest/20190924000503.GA97201@google.com/T/#e73eab088e4791c234bf13156cc276ad15c8376de

.. _which-version:

Which version should I use?
===========================

As for which branch you should use, upstream should be generally preferred (just
as upstreaming your own code should be generally preferred); nevertheless, there
are a lot of features that are not upstream yet, and will not be upstream for
some time (possibly more than a year), if you need these features for your tests
then you have no choice other than to use the *experimental* branch.

What features are available upstream?
-------------------------------------

- Basic test structure for defining test cases and test suites
- Basic expectations and assertions
- KUnit managed resources
- Error reporting

What features are not upstream yet?
-----------------------------------

- Class mocking
- Function mocking
- Hardware/platform faking
- Error recovery

.. _download-links:

Where are these versions?
=========================

Upstream
--------

KUnit can be found in Linux 5.5 and newer.

- Code: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/
- `Usage <../third_party/kernel/docs/usage.html>`__ - for a more detailed explanation of KUnit features
- `API <../third_party/kernel/docs/api>`__ - for the list of KUnit APIs used for testing
- kunitconfig file: https://kunit.googlesource.com/kunitconfig/+/refs/heads/master/kunitconfig

The KUnit code itself is primarily found in the `lib/kunit <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/lib/kunit>`__
directory.

Experimental
------------

The *experimental* branch is stored in a Google-hosted gerrit instance. Going
forward, there will be a set of versioned *experimental* branches, of which only
the latest will be actively supported. Until this is available, however, there
is a historic *kunit/alpha/master* branch containing our experimental code.

- Code: https://kunit.googlesource.com/linux/+/kunit/alpha/master.
- `Usage <../third_party/stable_kernel/docs/usage.html>`__ - for a more detailed explanation of KUnit features
- `API <../third_party/stable_kernel/docs/api>`__ - for the list of KUnit APIs used for testing
- kunitconfig file: https://kunit.googlesource.com/kunitconfig/+/refs/heads/kunit/alpha/master/kunitconfig