docs: Add Contribution Guide

Give pointers on how to contribute to the project. Links
to Mailing lists, pointers to the IRC channel and a brief
explanation of the development model.

Signed-off-by: Lucas Meneghel Rodrigues <lmr@redhat.com>
Merge pull request #197 from lmr/contribution-guide

docs: Add Contribution Guide
multiplex: Be deterministic when reading nodes and variables.

When reading nodes and variables, it's important
to keep the order of the structure defined in original
multiplex file, to facilitate debug (with the multiplex plugin)
and to maintain the order of going into node parents.

So we're removing dicts and sets and using OrderedDict.

Signed-off-by: Ruda Moura <rmoura@redhat.com>
avocado.plugins.multiplexer: Display path of nodes by default.

By default, it will now display the paths of the nodes, so
we're not going to show all that structure as it was before.

If you want to see the variables, just pass the option `--contents`
to the plugin.

Here's an example output:

Variants generated:
Variant 1:    /root/hw/cpu/intel, /root/hw/disk/scsi, /root/os/linux/fedora, /root/os/win/winxp, /root/env/debug
Variant 2:    /root/hw/cpu/intel, /root/hw/disk/scsi, /root/os/linux/fedora, /root/os/win/winxp, /root/env/prod
Variant 3:    /root/hw/cpu/intel, /root/hw/disk/scsi, /root/os/linux/fedora, /root/os/win/win7, /root/env/debug

Signed-off-by: Ruda Moura <rmoura@redhat.com>
Merge pull request #189 from ruda/multiplex_ordered_dict

Multiplex:  reading node parents and variables in determinisc way + simple (with paths) output for multiplex plugin
GDB: introduce external libraries

This instroduces external libraries that are used by the avocado GDB
handling library. The two libraries are:

1) the spark parser, used as part of cPython builds, but not available
   a pip'able package or distro level packages;
2) the GDB MI parser from the pygdb project. Project seems to be be dead
   but the parser is really useful and fits well with avocado's needs.
   Also not pip'able or available from a distro package.

Signed-off-by: Cleber Rosa <crosa@redhat.com>
GDB: add GNU Debugger handling library

This library is supposed to be useful both to test writers and to avocado itself.

Test writers may want to explicitly interact with the GNU debugger, run their
applications both in out outside it, generate core dumps, etc.

Avocado itself uses that library to implement the GDB plugin, that allows test
runners to run binaries inside the debugger transparently.

Signed-off-by: Cleber Rosa <crosa@redhat.com>
gdbtest: introduce new test

This test fires a GDB instance, sends both valid and invalid commands,
runs a couple of binaries, setting breakpoints, catching signals and
generating core dumps.

Signed-off-by: Cleber Rosa <crosa@redhat.com>
avocado/runtime.py: add runtime configuration module

Simple namespace for storing configurations that will affect
the avocado runtime, including the test runner and standard
API behavior.

Signed-off-by: Cleber Rosa <crosa@redhat.com>
GDB plugin: enables GNU Debugger features

Such as the ability to run any number of applications inside the
debugger transparently.

Signed-off-by: Cleber Rosa <crosa@redhat.com>
job runtime: set the currently running test

So that other parts of the framework may act upon it if necessary.

Signed-off-by: Cleber Rosa <crosa@redhat.com>
GDB: add transparent support to avocado/utils/process.py

So that any code using our process API can be run through a debugger.

Signed-off-by: Cleber Rosa <crosa@redhat.com>
GDB: add paused and paused_msg to the test state and job main loop

paused is a boolean that indicates if the test is paused, and paused_msg
may contain a message to give to the user running the test.

Signed-off-by: Cleber Rosa <crosa@redhat.com>
GDB: add documentation about the feature, caveats and workarounds

Signed-off-by: Cleber Rosa <crosa@redhat.com>
GDB: be more explicit about the current big caveat

There is actually *no way* to perform I/O with the inferior process
STDIN/STDOUT/STDERR, so let's be clear about it.

Signed-off-by: Cleber Rosa <crosa@redhat.com>
avocado/utils/process.py: raise an exception instead of returning possible failure as success

Signed-off-by: Cleber Rosa <crosa@redhat.com>