diff --git a/docs/.sphinx/wordslist.txt b/docs/.sphinx/wordslist.txt index be372e81a0..0fc8a5b6e4 100644 --- a/docs/.sphinx/wordslist.txt +++ b/docs/.sphinx/wordslist.txt @@ -1,5 +1,6 @@ APIs autoconf +backend baz Baz bluetooth @@ -26,6 +27,8 @@ ESC Fi FooBar formatter +frontend +frontends github GitHub GPLv @@ -45,6 +48,7 @@ JSON keypresses libre loopback +LTS lv mis miscellanea @@ -73,7 +77,10 @@ rtc RTC runtime SIGINT +snapcraft Snapcraft +Snapcraft +SRU SRU SSID startprovider diff --git a/docs/reference/index.rst b/docs/reference/index.rst index 0619c8d140..df1589c19a 100644 --- a/docs/reference/index.rst +++ b/docs/reference/index.rst @@ -8,3 +8,4 @@ Reference stack launcher units/index + snaps diff --git a/docs/reference/snaps.rst b/docs/reference/snaps.rst new file mode 100644 index 0000000000..eebef9d685 --- /dev/null +++ b/docs/reference/snaps.rst @@ -0,0 +1,76 @@ +.. _snap_reference: + +=============== +Snap Versions +=============== + +There are several Checkbox snaps and channels to choose from. You can +get a full list via ``snap info checkbox``. You can refer to the following +to decide what you should install. + +.. _ref_which_snap: + +Picking your version +==================== + +As you may recall from the :ref:`installing_checkbox` tutorial, when installing Checkbox +you need to pick a frontend and a backend. There are several parameters that +may influence your choice of the best snap for your situation but in general +there are three distinguishing factors in Checkbox snaps: base, confinement and +stability. + +Base +---- + +The base of a snap is the underlying version of the operating system +that it uses to run. For example ``checkbox 22.04`` and ``checkbox22`` +are built on top of Ubuntu 22.04. This is not an 100% accurate +explanation of what a base is but you can use this rule of thumb in your decision. +If you want a more complete explanation of what bases are and how they are built, +refer to this +`blog post from the Snapcraft team `_. + +In general we advise to use the version of Checkbox that most closely matches the +system that is going to run it. If you are not on an LTS release of Ubuntu or +you are using a completely different operating system, try to match it to +the closest release we have. For example, if you are on Ubuntu 23.04, +``checkbox22`` is probably the one you will have to choose. + +Confinement +----------- + +As you may know, or may learn more from +`the Snapcraft documentation `_, a +snap can either use ``strict`` or ``classic`` confinement. Checkbox has a snap +for both models. The strict snaps are called ``ucXX``, the classic ones have a +standard LTS name. + +In general we advise to use ``classic`` snap. You are going to need the ``classic`` +one whenever the tests you are running need a binary that is available in your +system but not in the ``strict`` snap. + +.. note:: + + This section only applies to the Checkbox frontend, the backend snap is always + ``strictly`` confined. + +Stability +--------- + +Checkbox uses `semantic versioning `_. There are three channels +that you can install from ``edge``, ``beta`` and ``stable``. + +If you want a stable version that we are pretty sure that works, use ``stable``, this +version was tested thoroughly via continuous integration and in our lab and is the +one that we use for our `Ubuntu Certified `_ program. + +If you can trade a little bit of stability for more up-to-date features, you can use +``beta``. This version of Checkbox was tested via CI and on a subset of our lab. It +should be as good as ``stable``, but once we are sure it is we will promote it to +that channel. + +If you want the most up-to-date possible build of Checkbox you can use the +``edge`` channel. These builds are updated daily and contain the latest changes to +the framework. We do not advise to use this channel in production, it is tested +via CI and it is built from the latest commit in the ``main`` branch of the +`Checkbox Repository on github `_. diff --git a/docs/tutorial/using-checkbox/installing_checkbox.rst b/docs/tutorial/using-checkbox/installing_checkbox.rst new file mode 100644 index 0000000000..cae9e19f49 --- /dev/null +++ b/docs/tutorial/using-checkbox/installing_checkbox.rst @@ -0,0 +1,49 @@ +.. _installing_checkbox: + +=================== +Installing Checkbox +=================== + +In order to install Checkbox you are going to need two parts, a ``runtime`` +and a ``frontend``. + +First we need to install the ``runtime``, this tutorial will use the ``checkbox22`` +runtime on Ubuntu 22.04. We also offer versions for ``16``, ``18`` and ``20``. +Use the one that matches your Ubuntu version or refer to :ref:`ref_which_snap` to +understand and pick the one that fits your needs:: + + $ sudo snap install checkbox22 + [...] + checkbox22 X.Y.Z from Canonical Certification Team (ce-certification-qa) installed + +Now that we have the ``checkbox22`` runtime, we need a ``frontend``, to install it +run the following:: + + $ sudo snap install checkbox --channel 22.04/stable --classic + [...] + checkbox (22.04/stable) X.Y.Z from Canonical Certification Team (ce-certification-qa) installed + +.. note:: + There are multiple frontends as you may discover by typing ``snap info checkbox``. + If you are unsure about what ``frontend`` you should use, consider + reading this page: :ref:`ref_which_snap`, but for the scope of this tutorial the one + installed in this snipped is enough. + +Now that we have installed both we can launch Checkbox running: + +.. code-block:: none + + $ checkbox.checkbox-cli + Select test plan + ┌─────────────────────────────────────────────────────────────────────────────────────┐ + │ ( ) (Deprecated) Fully Automatic Client Certification Tests │ + │ ( ) 18.04 Server Certification Full │ + │ ( ) 18.04 Server Certification Functional │ + │ ( ) 18.04 System On Chip Certification (For SoC Testing) │ + │ ( ) 18.04 Virtual Machine Full (For Hypervisors) │ + │ ( ) 20.04 Server Certification Full │ + └─────────────────────────────────────────────────────────────────────────────────────┘ + Press to continue (H) Help + +If your screen is similar to this one, rejoice! You can start using +Checkbox! For now you can close it using ``Ctrl+C``.