HACKING.txt

Path: HACKING.txt
Last Update: Mon Mar 26 03:38:32 CEST 2007

HACKING

Some instructions on how to hack on R-Bus.

Getting debug info

Set the log level to DEBUG for some extra messages:

  $ RBUS_LOG_LEVEL=DEBUG ruby your_script
  $ RBUS_LOG_LEVEL=DEBUG spec your_spec

Or, in your script:

  require 'rbus'
  RBus::Log.level = :DEBUG

See RBus::Log for more info, basically it’s a variation of the Logger module.

Adding examples

A good way to test the library as well as providing documentation is to add working examples, like the ones that already exist in the /examples directory. Add your own scripts that perform some possibly useful task, or translate examples from other languages.

Implementing new mechanisms

Check out the files in lib/rbus/auth for examples. Authorization is implemented with a statemachine as described in the D-Bus specification.

A mechanism must implement one method, called ‘auth’ that should return a 3-element array containing the name of the mechanism, data to be sent along, and the state expected afterwards (OK, REJECTED or DATA).

The mechanism, if expecting DATA, must also implement a method ‘data’, that takes one argument, which is the data sent from the server, and return a 2-element array containing it’s response and expected state afterwards. This method could be called multiple times, and it’s the responsibility of the mechanism to keep track of what has happened before. The DBUS_COOKIE_SHA1 mechanism implements a ‘data’ method.

Any new mechanisms should be added to RBus::Auth::MECHANISMS in lib/rbus/auth/auth.rb.

Adding new Mainloops

Currently there’s a threaded mainloop that’s the default, and a glib mainloop that can be used by requiring ‘rbus/glib’ instead of just ‘rbus’. It should be possible to add more of these by looking at the existing code in /lib/rbus/mainloop/.

There could also be a bit more work done on abstracting and separating the functionality betweem the loops.

It could be a good thing to replace the default with something non-threaded, however it seems to work well and the Java implementation also uses threads, so it may be worth it to not dismiss threads just because they can be troublesome outside of Ruby. :)

Writing and running tests

RSpec

RBus uses RSpec (rspec.rubyforge.org) for its test suite. You will need to install RSpec to run the test suite. It’s available via rubygems, ‘gem install rspec’.

Please add more tests or help update the ones that do exist.

You can find the tests (or "specifications" in the spec directory. Run ‘rake spec’ to run the test suite. It takes a few seconds to run, mostly because it tests some threads with sleeps. You can also run ‘spec spec_name.rb’ to run a specific specification.

RCov

If you have RCov installed, also available as a gem, you can generate a test coverage report with rake rcov. The report will be HTML files in spec/coverage/index.html.

Debugging the protocol

Running a custom debug Bus

See dbus.freedesktop.org/doc/dbus-daemon.1.html#lbAH

Using strace

Apart from printing debug info, one can use strace to check what the process is sending and what the bus is recieveing.

To monitor the program, simply do

  strace -s 1024 ruby test_program.rb

To monitor a running Bus, find the process id and then:

  strace -s 1024 -o log.txt -p PID

-s 1024 is to get complete strings (which is what we are sending) and -o log.txt sends it to a file instead of console, which can be nice for searches. :)

For more fine-grained control, look at the -e switch in the strace man page.

[Validate]