← Back to branch summary

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

« back to all changes in this revision

Viewing changes to plainbox/docs/dev/intro.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/dev/intro.rst
1
1
Getting started with development
2
2
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
3
3
 
4
 
Plainbox uses python3 for development. The core is really system independent
 
4
PlainBox uses python3 for development. The core is really system independent
5
5
but you will need Ubuntu to really make the best of it and experience it as we
6
6
do. We encourage everyone to use the most recent Ubuntu release for
7
7
development. Usually this brings the best, most recent tools without having to
8
8
search for software on the Internet.
9
9
 
10
 
Plainbox has almost no dependencies itself, almost, because we depend on the
11
 
mighty :term:`Checkbox` project to provide us with a lot of existing
12
 
infrastructure. Testing Plainbox requires additional packages and some
 
10
PlainBox has almost no dependencies itself, almost, because we depend on the
 
11
mighty :term:`CheckBox` project to provide us with a lot of existing
 
12
infrastructure. Testing PlainBox requires additional packages and some
13
13
non-packaged software. You will typically want to install it and take advantage
14
14
of the integration we provide.
15
15
 
16
16
.. note::
17
17
 
18
 
    If you are working with the source please be aware that Plainbox requires
19
 
    an installed copy of Checkbox. Checkbox in turns is has many scripts that
 
18
    If you are working with the source please be aware that PlainBox requires
 
19
    an installed copy of CheckBox. CheckBox in turns is has many scripts that
20
20
    depend on various system packages, including python packages that cannot be
21
21
    installed from pypi. If you were planning on using :command:`virtualenv`
22
22
    then please make sure to create it with the ``--system-site-packages``
25
25
Get the source
26
26
--------------
27
27
 
28
 
Source code for Plainbox is kept along with several other related projects in
 
28
Source code for PlainBox is kept along with several other related projects in
29
29
the `checkbox` project on launchpad. You will need to use bzr to get a local
30
30
copy.
31
31
 
41
41
Get the dependencies
42
42
--------------------
43
43
 
44
 
You will need some tools to work on Checkbox. Scripted installation of almost
 
44
You will need some tools to work on CheckBox. Scripted installation of almost
45
45
everything required is available (except for VirtualBox and Vagrant, those are
46
46
still manual).
47
47
 
51
51
Getting Vagrant
52
52
---------------
53
53
 
54
 
While developing Plainbox you will often need to run potentially dangerous
 
54
While developing PlainBox you will often need to run potentially dangerous
55
55
commands on your system, such as asking it to suspend and wake up
56
56
automatically. We also need to support a range of Ubuntu releases, going all
57
57
the way back to Ubuntu 12.04. This may cause compatibility issues that are
58
 
unnoticed all until they hit our CI system. To minimize this Plainbox uses
 
58
unnoticed all until they hit our CI system. To minimize this PlainBox uses
59
59
:term:`Vagrant` to create lightweight execution environments that transparently
60
60
share your source tree and allow you to quickly create and share testing
61
61
environment that can be deployed by any developer in minutes. Vagrant uses
84
84
Initialize virtualenv
85
85
---------------------
86
86
 
87
 
Plainbox will use a few unpackaged and bleeding-edge releases from :term:`pypi`
 
87
PlainBox will use a few unpackaged and bleeding-edge releases from :term:`pypi`
88
88
those are installed by additional script. By default the script assumes you
89
89
have a `/ramdisk` directory but you can pass any path as an argument for an
90
90
alternate location.
112
112
the development and testing environment. This file tells :command:`vagrant` how
113
113
to prepare a virtual machine for testing. If you never used it before you may
114
114
want to keep a tab open on `vagrant getting started guide
115
 
<http://docs.vagrantup.com/v1/docs/getting-started/index.html>`_
 
115
<http:`http://docs.vagrantup.com/v1/docs/getting-started/index.html>`_
116
116
 
117
117
We did all the hard work so that you don't have to, to get everything ready
118
118
just run one command:
146
146
      -v, --version         show program's version number and exit
147
147
    $ exit
148
148
 
149
 
Getting and setting up LXC
150
 
--------------------------
151
 
 
152
 
An alternative to run tests in isolated environments for various Ubuntu
153
 
releases is to use `LXC <https://linuxcontainers.org/>`_. LXC is lighter on
154
 
resources and doesn't require hardware virtualization support, but since it
155
 
doesn't do real, full virtualization, it may be inadequate for some kinds of
156
 
tests. It's up to you to decide whether you want to use it.
157
 
 
158
 
If you want to use LXC, the easiest way is to use Ubuntu 14.04, and just
159
 
install the lxc package:
160
 
 
161
 
.. code-block:: bash
162
 
 
163
 
    $ sudo apt-get install lxc
164
 
 
165
 
Setting LXC up for plainbox testing is easy, simply configure your system so
166
 
that the user that will run the tests can use `sudo` to execute lxc subcommands
167
 
without requiring a password. For example if your user is called `peter`, run
168
 
`sudo visudo` and paste this configuration at the very end of that file, this
169
 
will allow running lxc tests as that user:
170
 
 
171
 
.. code-block:: bash
172
 
 
173
 
    Cmnd_Alias LXC_COMMANDS = /usr/bin/lxc-create, /usr/bin/lxc-start, \
174
 
    /usr/bin/lxc-destroy, /usr/bin/lxc-attach, /usr/bin/lxc-start-ephemeral, \
175
 
    /usr/bin/lxc-stop, /usr/bin/lxc-ls
176
 
    peter ALL=NOPASSWD: LXC_COMMANDS
177
 
 
178
 
 
179
 
The first time you use lxc, it will download the base files for each release
180
 
you test, which will be slow; afterwards, it will use a locally cached copy to
181
 
speed things up.
182
 
 
183
 
Running Plainbox tests
 
149
Running PlainBox tests
184
150
^^^^^^^^^^^^^^^^^^^^^^
185
151
 
186
 
Plainbox is designed to be testable so it would be silly if it was hard to run
 
152
PlainBox is designed to be testable so it would be silly if it was hard to run
187
153
tests. Actually, there are many different ways to run tests. They all run the
188
154
same code so don't worry.
189
155
 
191
157
 
192
158
- Run the :command:`./test-in-vagrant.sh` from the top-level directory. This
193
159
  will take the longer but will go over *all* the tests on *all* the supported
194
 
  versions of Ubuntu. It will run Checkbox unit-tests, Plainbox unit-tests and
195
 
  it will even run integration tests that actually execute jobs.
196
 
 
197
 
- Run the :command:`./test-in-lxc.sh` from the top-level directory. This also
198
 
  executes *all* the tests on *all* the supported versions of Ubuntu, however
199
 
  it uses LXC containers instead of a Virtualbox virtual machine. 
 
160
  versions of Ubuntu. It will run CheckBox unit-tests, PlainBox unit-tests and
 
161
  it will even run integration tests that actually execute jobs. 
200
162
 
201
163
- Run :command:`plainbox self-test --unit-tests` or 
202
164
  :command:`plainbox self-test --integration-tests`. This will execute all the