From 24d2b4ca87c2fe087b84d3312057215c7b513dcd Mon Sep 17 00:00:00 2001 From: snare Date: Mon, 29 Sep 2014 21:42:46 +1000 Subject: [PATCH] Stuff from readme --- Configuration.md | 65 ++++++++++++++++++++++++++++++++++++++++++++ Layout-automation.md | 27 ++++++++++++++++++ Tests.md | 17 ++++++++++++ 3 files changed, 109 insertions(+) create mode 100644 Configuration.md create mode 100644 Layout-automation.md create mode 100644 Tests.md diff --git a/Configuration.md b/Configuration.md new file mode 100644 index 0000000..7d7b1d1 --- /dev/null +++ b/Configuration.md @@ -0,0 +1,65 @@ +# Voltron configuration + +Voltron uses a JSON file for configuration, located at `~/.voltron/config`. There is a set of configuration defaults included in the package (`voltron/config/default.cfg`), and a sample config (`/voltron/config/sample.cfg`). + +The config is laid out in 5 sections: `general`, `server`, `client`, `view` and `console`. + + { + "general": { + + }, + "server": { + + }, + "client": { + + }, + "view": { + + }, + "console": { + + } + } + +Any section can be missing. The default options will be applied from `default.cfg`. + +## General configuration + +This section contains options that effect the operation of the entire package. + +### Debug logging + +`debug_logging` - if `true`, debug logging is enabled package-wide. + +XXX: more detail about debug logging + +## Server configuration + +The `server` section contains options that effect only the server component of Voltron. This applies to servers running in the context of the debugger host (ie. loaded into LLDB/GDB) or the server running in Voltron's standalone console. + +### Listeners + +Voltron supports 3 different listeners that can be used to communicate with the server back end - a UNIX domain socket, a TCP socket and an HTTP web server. + +## View configuration + +A sample configuration file is included in the repo. Copy it to `~/.voltron/config` and mess with it and you should get the idea. Header and footer positions, visbility and colours are configurable along with other view-specific items (e.g. colours for labels and values in the register view). + +In the example config at the top level, the `all_views` section sets up a base configuration to apply to all views. Each view can be configured individually overriding these settings. For example, the `stack_view` section in the example config overrides a number of these settings to reposition the title and info labels. The `register_view` section in the example config contains some settings overriding the default colours for the register view. Have a look at the source for other items in `format_defaults` that can be overridden in this section of the config. + +There is also support for named view configurations for each type. The example configuration contains a config section called `some_named_stack_view`, which is a modified version of the example stack view configuration. If you specify this name with the `-n` option, this named configuration will be added to the existing config for that view type: + + $ voltron stack -n "some_named_stack_view" + +Some options specified in the configuration file can also be overridden by command line arguments. At this stage, just the show/hide header/footer options. + +So the resulting order of precedence for view configuration is: + +1. defaults in defaults.cfg +2. "all_views" config +3. view-specific config +4. named view config +5. command line args + +Each configuration level is added to the previous level, and only the options specified in this level override the previous level. diff --git a/Layout-automation.md b/Layout-automation.md new file mode 100644 index 0000000..5152222 --- /dev/null +++ b/Layout-automation.md @@ -0,0 +1,27 @@ +Layout automation +----------------- + +### tmux + +There's a few tmux scripting tools around - [tmuxinator](https://github.com/aziz/tmuxinator) is one of them. You'll probably need to use the latest repo version (as of July 11, 2013) as the current stable version has a bug that results in narrow panes not being created properly or something. Seems to be resolved in the latest repo version. + +Here's a sample **tmuxinator** config for a layout similar to the example screencap that works well on an 11" MacBook Air in fullscreen mode: + + project_name: voltron + project_root: . + cli_args: -v -2 + tabs: + - madhax: + layout: 15a8,169x41,0,0{147x41,0,0[147x13,0,0{81x13,0,0,60,65x13,82,0,61},147x19,0,14,62,147x7,0,34{89x7,0,34,63,57x7,90,34,64}],21x41,148,0,65} + panes: + - voltron view disasm + - voltron view cmd "i b" + - gdb + - voltron view stack + - voltron view bt + - voltron view reg + +The `layout` option there configures the actual dimensions of the panes. You can generate the layout info like this: + + $ tmux list-windows + 1: madhax* (6 panes) [169x41] [layout 15a8,169x41,0,0{147x41,0,0[147x13,0,0{81x13,0,0,60,65x13,82,0,61},147x19,0,14,62,147x7,0,34{89x7,0,34,63,57x7,90,34,64}],21x41,148,0,65}] @11 (active) \ No newline at end of file diff --git a/Tests.md b/Tests.md new file mode 100644 index 0000000..f547590 --- /dev/null +++ b/Tests.md @@ -0,0 +1,17 @@ +# Tests + +Voltron has a bunch of test suites built for various parts of the codebase. To run them, you'll need to install the `nose` module. + + $ pip install nose + +Change into the repo directory and run the tests: + + $ nosetests -sv + +Some of the tests are quite dependent on timing as there's a lot of restarting of the debugger hosts and rebinding of sockets going on, so sometimes tests will fail for no apparent reason with a "Connection failed" error or similar. This usually isn't really indicative of a problem, just run them again and they'll probably work OK. That's what happens when you stick random `time.sleep()` calls in there to wait for GDB to start up. + +You can also try running just that suite on its own, e.g.: + + $ nosetests -sv tests/gdb_cli_tests.py + +That will have a much better chance of success. \ No newline at end of file