Development Introduction

Debug end-user guide

Contents

Intended audience

This guide is aimed towards end-users of NR who have limited knowledge and experience in regards to the 'inner workings' of their computer systems, but more experienced users may also find it helpful. Developers will also find this to be a helpful initial resource to provide end-users when helping them with debugging.

Helping with debugging Net Responsibility

If you are experiencing problems with Net Responsibility (NR), assisting with debugging (troubleshooting the problem with the program) can help fix your problem, and at the same time improve the software. This process may involve installing NR in a different way and/or doing other things you are not familiar with, but this guide and NR's developers should be able to walk you through it. The end goal of the debugging process is to generate some text output that the developers can use for troubleshooting. Because of different computer systems, software versions, and settings, and because developers do not have access to each user's computer, they are grateful to any user who is willing to help out with the debugging process.

General elements of debugging NR

Whatever computer system you are using, you will normally need to do most, if not all, of the following things during the debugging process:

Subscribing to the NR development list

Because debugging is a part of the software development process, it is important that you subscribe to the NR development mailing list, which is where you will send whatever debug output you get and also where you will have any necessary follow-up dialogue with the developers. Once your problem is resolved, you may unsubscribe again if you want to. To subscribe, click here and follow the instructions found under "Subscribing to Responsibility-devel". Some messages others send to this mailing list may seem quite technical if you are not a software developer yourself, but you can safely ignore any emails or threads that do not apply to the debugging process you are taking part in. The easiest way to focus in on only those emails that are relevant to you is to choose (when you subscribe) NOT to receive mail from the list in a daily digest.

Using the NR development list

When replying to an email on this list, please observe the following guidelines:

If you are reporting a problem or asking a question about something, please observe the following guidelines:

Debugging NR on Ubuntu

New to Linux/Ubuntu? Read this article for some helpful info: Where's the Terminal?. Warning: Read this (post by jdong, Nov 18, 2007 - Jan 31, 2013) before copying/pasting anything into the terminal. Basic rule: Take time to make sure you have at least a basic idea of what and why you are running a certain command in the terminal.

Install other necessary software

The following packages will need to be installed (if they are not already) before you can successfully complete the next steps:

Note: You can use the search function of a package manager like Ubuntu Software Center or Synaptic Package Manager to see if the above packages are already installed. For the POCO libraries, you will want to search for the text libpoco which should bring up a number of different packages that make up the POCO libraries. You can also use a package manager to install these packages if you wish. Alternatively, you can open a terminal window and use the following command:

sudo apt-get install package-name

(Explanation of the above command: 'sudo' gives you root permission, which some programs [like 'apt-get'] require in order to run, and this normally requires you to enter your system username and password. 'apt-get' is the name of the program that you want to run, which in this case is a program that is used to download and install software on your system. 'install' just tells the 'apt-get' program what you want it to do. 'package-name' represents the place in the command where you type the name of whatever package you want to install; so if you want to install the 'build-essential' package, then that's what you type there, so that 'apt-get' knows what program you want it to install.) You may also need to follow some prompts in the terminal window in order to complete the install process.

Compile and install NR

Once you have confirmed that other necessary software is installed, the next thing you will need to do is compile and install NR. Unless you are given different instructions by a developer, here's what you need to do:

cd /home/name/nr
./configure
make
sudo make install

If the above commands ran without giving any errors, there is a good chance that NR has been successfully installed. However, before you move to the next step, you should use this guide to confirm whether NR is running correctly or not.

Run NR's debug command

Now you are to the place where you can run the command that will generate the debug text output that you will then send to the developers via the mailing list.

sudo killall net-responsibility

If you want, you can then run the 'grep' command (see above) again to confirm that NR is no longer running.

sudo net-responsibility --debug

This will generate the desired debug output, which you will then want to copy and paste into your reply to the mailing list. What this command does is manually start NR and run it in the terminal window, generating the debug output until it either stops running or finishes the process of starting and successfully running.

sudo net-responsibility --daemon

If you want, you can then test NR (see above) again to confirm that it is indeed running as it should.

Compiling and installing the POCO libraries on Ubuntu

If your system does not have a precompiled package for installing the POCO libraries, then you will need to compile and install them from the source code. Here's what you need to do:

cd /home/name/poco
./configure --shared --no-tests --no-samples
make
sudo make install

If the above commands ran without giving any errors, then you were probably successful in installing the POCO libraries, and can go on with the next steps of the debugging process as detailed above.

Debugging NR on other systems

Many of the principles of the debugging process will be the same on different systems, although some of the details will be different. If you are having trouble working out how to do it on your system, you can contact the developers via the mailing list and they may be able to help you. Once you have figured it out, please share the process with us via the mailing list, as this will help us improve our documentation and ability to help others with the same system as you.

Troubleshooting

If you run into any problems with the above process, please let us know via the mailing list. Your feedback in this way will help us know how to improve these instructions to make the debugging process as smooth as possible for everyone involved.