Debug and fine tune apps with the open sourced XAppDbg tool [tool]

App developers, have you ever wished that you wouldn’t have to rebuild and run your application to try out every small change you’re making? Sony’s XAppDbg tool (eXtra Application Debugging tool) lets you try out different parameters without the need to rebuild the code for every change. And it’s open source! Read on as Pál Szász, who developed the tool, explains more!

Pal Szasz, software developer at Sony.

Hi! My name is Pál Szász, I’m a software developer at Sony. Perhaps you remember ChkBugReport, an open source tool I developed a while ago. Now I would like to present a new project of mine, the XAppDbg tool.

I came up with the idea for this tool based on a real problem I had myself – as an app developer, you often face the situation when you need to rebuild and rerun your application very often, in order to fine tune some parameters of it. For example, this could be padding and colours in different user interface (UI) components or parameters in a physics engine. Therefore I created the XAppDbg tool.

With XAppDbg, you can try out different settings and see the effects immediately in your running app, without having to rebuild the code after each new change. This way, the work to fine tune the UI is made a lot more efficient.

To show you how it works, I’ve created a simple particle effect visualisation, which could be used for a game or as a decoration in a music player. It consists of a number of coloured particles that move from one end of the screen to another. Let me show you how I use XAppDbg to fine tune the graphics.

Screenshot showing the particle effect with default settings.

In the screen shot above, you can see how my particle effect looks with default settings. As you can see, this does not look very impressive – the particles reach only one third of the screen before they die, and there are too few of them.

When dealing with a particle engine, there are many parameters which affect the output. For example:

• The position where particles are born.
• The initial speed of the particles.
• The gravity.
• The colour of the particles.
• The birth rate.

Normally you would declare these parameters as constants, run the application, adjust the constants, rebuild and run the application and repeat these steps until you have the effect you want. With XAppDbg there is much simpler alternative, and you can get started by performing some simple steps.

How does it work?The XAppDbg tool consists of two main parts, a server running on the phone and a client running on the computer.

The server part uses Java™ reflection to scan the code for fields and methods. It exposes the public fields, the getter and setter methods as properties and the methods taking no arguments as commands. It then creates a server socket and waits for the client to connect.

When the connection is made, the server sends the list of exposed fields, properties and commands to the client. During runtime, the client sends the new values to the server, which stores them using Java reflection.

Note that XAppDbg is written in Java (J2SE), which means that it can be used in desktop Java applications as well, not only Android™ applications. Also, it can be used on Linux®, Microsoft® Windows® and Mac OS X®.

How to download and setup XAppDbg for your project

1. Download XAppDbg from the Sony GitHub.

2. Remove the final keyword from the constants in your code, so the parameters can be changed during runtime. It can be good to also move all the constants inside an inner class, so they are isolated. In my example, it looks like this:

static class Consts {
        public static int RATE = 10;
        public static float LIFE = 1.0f;
        public static int MIN_COLOR = 0x804020;
        public static int MAX_COLOR = 0xc08060;
        public static float G = 9.6f;
        public static float MIN_X = 0.0f;
        public static float MAX_X = 1.0f;
        public static float MIN_Y = 1.0f;
        public static float MAX_Y = 1.0f;
        public static float MIN_VX = -0.1f;
        public static float MAX_VX = +0.1f;
        public static float MIN_VY = -0.2f;
        public static float MAX_VY = -0.3f;
}

3. Include the XAppDbgServer library in your project, by adding the XAppDbgServer.jar to the Java build path. For example, in Eclipse: Project Properties -> Java Build Path -> Libraries -> Add jar…

4. In the code, setup an instance of the server.

In my example, I added the following code to start the server:

// Create and start the debug server

mServer = new XAppDbgServer();

mServer.addModule(new XAppDbgPropertiesModule(Consts.class));

mServer.start();

The first line just creates a server instance. The XAppDbgPropertiesModule scans the fields of an object or class, and exposes all the public fields it finds. The third line starts the server, and it will be listening on port 55011. In order for this to work, the application must have the INTERNET permission.

5. Run the application you’re developing on your phone.

6. Use a USB cable to connect the phone to the computer. In order for the client application on the computer to be able to connect to the phone using TCP/IP, you need Android Debug Bridge (ADB) to forward the port. This means that the following command needs to be executed in a shell every time your device is connected to the computer via the USB cable:

$ adb forward tcp:55011 tcp:55011

7. Now when you start the client application, you just need to click on “Connect localhost”, and you’re ready:

Screenshot of the connection dialogue of the XAppDbg client.

Now you can change any of your parameters during runtime on the computer and see the effect of the change immediately on your phone, without rebuilding the application.

Screenshot showing the XAppDbg client for the computer.

When you are satisfied with the result, just copy the values from the client back into your source code and rebuild it.

XAppDbg used in practiceTo teach you some more on how to use XAppDbg, I thought we could look at some examples of what can be done with my particle engine, just by changing the parameters from the client.

Screenshot from the phone (left) and from the client on the computer (right), where several parameters have been changed compared to default settings.

As a first example, I increased the birth rate, lifetime and initial maximum vertical speed of the particles, as well as the gravity, compared to the default settings shown above. As a result, there are more particles and they fill the entire screen. Note how the client marks the changed values with a red background, to make it easier for you to know which values needs to be copied back to the source code when you’re done.

Screenshot from the phone (left) and client on the computer (right), where the particles are born in the bottom-centre of the screen at a higher speed and birth rate compared to previous examples.

In a second example, which I call the “fire fountain”, I changed the colours so only red and orange are used. The particles are born only in the bottom-centre of the screen, and have a higher initial speed and birth rate.

Screenshot from the phone (left) and client on the computer (right), where the particles are born at the top of the screen and has changed colour to blue.

In a final example, I thought we should have a little bit of snow. By changing the colour to blue, moving the birth position to the top and having a different direction of the initial speed, the particles will now fall downwards on the screen. The gravity is disabled, so they will have a constant speed.

Try it out and let us know what you think!
So now you’ve seen how the XAppDbg tool can make your life as a developer easier. Go ahead and try it out, and let us know what you think. And don’t forget that you are more than welcome to contribute to the project. And if you have any questions, feel free to drop us a comment below or at the XDA developers forum thread!