| =============== |
| Getting Started |
| =============== |
| |
| 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`. |
| |
| .. _why-multiple-versions: |
| |
| Why are there multiple versions? |
| ================================ |
| |
| Ideally, upstreaming code to the Linux kernel would be fast, we would be able to |
| develope 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. |
| |
| In short, we wrote a bunch of stuff to experiment with before we started sending |
| things upstream, people started using that stuff, and upstream diverged. We made |
| the decision that it is better to have 2 versions of KUnit rather than ``n`` |
| versions where ``n > 2``, so we decided to maintain a non-upstream branch called |
| *stable* which has all the features not yet upstreamed, and would be maintained |
| under the assumption that people are actually using it (hence, we don't make API |
| breaking changes, or anything like that); this is why it's called *stable*. Our |
| other branch is just upstream Linux. |
| |
| But wait, I see more than two branches! |
| --------------------------------------- |
| |
| For the upstream version, just use torvalds/master. Our *stable* branch is |
| hosted at https://kunit.googlesource.com/linux/+/kunit/alpha/master. |
| |
| Nevertheless, you may notice that there are other branches hosted at |
| https://kunit.googlesource.com/linux. All these branches are either based on |
| upstream (and should not be used since they are not upstream yet), or are based |
| on stable. |
| |
| .. _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 stable 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 |
| |
| Where to go |
| =========== |
| |
| Hopefully you now have a good idea whether you want to use the stable version, |
| or the upstream version. As for where to go, see the following sections: |
| |
| Upstream Getting Started |
| ------------------------ |
| |
| - Code: https://git.kernel.org/pub/scm/linux/kernel/git/shuah/linux-kselftest.git/log/?h=next |
| - Documentation: :doc:`../third_party/kernel/index` |
| |
| Stable Getting Started |
| ---------------------- |
| |
| - Code: https://kunit.googlesource.com/linux/+/kunit/alpha/master |
| - Documentation: :doc:`../third_party/stable_kernel/index` |
