← Back to branch summary

~jocave/checkbox/hybrid-amd-gpu-mods

« back to all changes in this revision

Viewing changes to plainbox/docs/manpages/plainbox-dev-analyze.rst

  • Committer: Zygmunt Krynicki
  • Date: 2013-05-29 07:50:30 UTC
  • mto: This revision was merged to the branch mainline in revision 2153.
  • Revision ID: zygmunt.krynicki@canonical.com-20130529075030-ngwz245hs2u3y6us
checkbox: move current checkbox code into checkbox-old

This patch cleans up the top-level directory of the project into dedicated
sub-project directories. One for checkbox-old (the current checkbox and all the
associated stuff), one for plainbox and another for checkbox-ng.

There are some associated changes, such as updating the 'source' mode of
checkbox provider in plainbox, and fixing paths in various test scripts that we
have.

Signed-off-by: Zygmunt Krynicki <zygmunt.krynicki@canonical.com>

Show diffs side-by-side

added added

removed removed

Lines of Context:
plainbox/docs/manpages/plainbox-dev-analyze.rst
1
 
========================
2
 
plainbox-dev-analyze (1)
3
 
========================
4
 
 
5
 
.. argparse::
6
 
    :ref: plainbox.impl.box.get_parser_for_sphinx
7
 
    :prog: plainbox
8
 
    :path: dev analyze
9
 
    :manpage:
10
 
    :nodefault:
11
 
 
12
 
    The ``plainbox dev analyze`` command is a direct replacement for ``plainbox
13
 
    run`` that doesn't really run most of the jobs. Instead it offers a set of
14
 
    reports that can be enabled (confusingly, by default no reports are enabled
15
 
    and the command prints nothing at all) to inspect certain aspects of the
16
 
    hypothetical session
17
 
 
18
 
    The only exception to the rule above is the ``--run-local`` option. With that
19
 
    option all local jobs and their dependencies *are* started. This is
20
 
    technically required to correctly emulate the behavior of ``plainbox run``
21
 
    that does so unconditionally. Still, local jobs can cause harm so don't run
22
 
    untrusted code this way (the author of this man page recalls one local job
23
 
    that ran ``sudo reboot`` to measure bootchart data)
24
 
 
25
 
    Report Types
26
 
    ============
27
 
 
28
 
    Plainbox ``dev analyze`` command offers a number of reports that can be
29
 
    selected with their respective command line options. By default, no reports
30
 
    are enabled which may be a little bit confusing but all options can be
31
 
    enabled at the same time.
32
 
 
33
 
    Dependency Report
34
 
    -----------------
35
 
 
36
 
    This report shows if any of the jobs have missing dependencies. It almost
37
 
    never happens but the report is here for completeness.
38
 
 
39
 
    Interactivity Report
40
 
    --------------------
41
 
 
42
 
    This report shows, for each job, if it is fully automatic or if it requires
43
 
    human interaction.
44
 
 
45
 
    Estimated Duration Report
46
 
    -------------------------
47
 
 
48
 
    This report shows if Plainbox would be able to accurately estimate the
49
 
    duration of the session. It shows details for both fully automatic and
50
 
    interactive jobs.
51
 
 
52
 
    Validation Report
53
 
    -----------------
54
 
 
55
 
    This report shows if all of the selected jobs are valid. It is of lesser
56
 
    use now that we have provider-wide validation via ``./manage.py validate``
57
 
 
58
 
    Two Kinds of Job Lists
59
 
    ======================
60
 
 
61
 
    Desired Job List
62
 
    ----------------
63
 
 
64
 
    This list is displayed with the ``-S`` option. It contains the ordered
65
 
    sequence of jobs that are "desired" by the test operator to execute.  This
66
 
    list contrasts with the so-called `run list` mentioned below.
67
 
 
68
 
    Run List
69
 
    --------
70
 
 
71
 
    This list is displayed with the ``-R`` option. It contains the ordered
72
 
    sequence of jobs that should be executed to satisfy the `desired list`
73
 
    mentioned above. It is always a superset of the desired job list and almost
74
 
    always includes additional jobs (such as resource jobs and other
75
 
    dependencies)
76
 
 
77
 
    The run list is of great importance. Most of the time the test operator will
78
 
    see tests in precisely this order. The only exception is that some test
79
 
    applications choose to pre-run local jobs. Still, if your job ordering is
80
 
    wrong in any way, inspecting the run list is the best way to debug the
81
 
    problem.
82
 
 
83
 
See Also
84
 
========
85
 
 
86
 
:doc:`plainbox-run`