Revision as of 23:56, 20 January 2011

This tutorial provides step-by-step instructions that will show you how to start a Crossfire client and server in two separate Firefox processes on the same host and connect them. This may not seem very useful at first, but the main goal of this is to enable development and debugging of the Firebug/Crossfire client in Firefox.

Step 1: Setting up Firefox profiles

Create two (2) new Firefox profiles. You might want to name them something like "crossfire-client" and "crossfire-server" or "crossfire1" and "crossfire2". Install the Firebug and Crossfire extensions into both profiles.

Start up both profiles in separate Firefox processes using the -no-remote switch and any one of the -P, -ProfileManager, or -profile switches. This is explained in greater detail in many other places so I won't get into it here.

You should now have 2 instances of Firefox with Firebug and Crossfire. If the install was successful the Firebug and Crossfire icons (gray as they are initially disabled) should appear in the status bar at the bottom of the screen.

Step 2a: Connecting from the GUI

You should now have 2 copies of Firefox open with separate profiles containing identical versions of Firebug and Crossfire.

Open Firebug in the first profile, the Firebug icon will change color to . Also open FBTrace ( Tools > Firebug > Open Firebug Tracing ) if you have it. In the FBTrace options panel you will probably at least want to enable CROSSFIRE and CROSSFIRE_TRANSPORT.

Click on the Crossfire icon in the status bar. A small menu with two (2) options will appear. The first option is "Start Server" and the second is "Connect as client". Select "Start Server". A dialog will appear that looks like:

There are two (2) fields in the dialog, "Host:" and "Port:", and two (2) buttons, "Cancel" and "OK". You should not need to change either of the values at this time, so click OK to start the Crossfire server. The crossfire icon will change color to . The tooltip text for the icon should read "waiting for connection on port 5000".

Now go to the second Firefox profile, and again click the Crossfire status bar icon (which should still be in the disabled state ). This time select "Connect as client". A dialog similar to the server dialog will appear. You still should not need to change either value. Click OK.

The Crossfire status icon in both profiles will change to indicating they have successfully connected and exchanged handshakes.

Step 2b: Connecting from the command-line

If you're the kind of person who likes to read ahead, your reward is that you can skip step 2a. But, you might want to check out the Crossfire Command-line Options while you're at it.

Since I assume most people will be using the command-line to launch both Firefox profiles, it's probably easier to use to command-line options rather than the GUI, but I guess some people just like to click on stuff. Either way should work. Note that although to start Crossfire in client mode requires the -crossfire-host option, connecting to any host other than localhost will not work by default without changing the value of the extensions.crossfire.loopbackOnly preference to false.

Verifying a successful connection

In addition to the icon state changing, there will be output from FBTrace, if you have the CROSSFIRE option enabled, you should see the "CROSSFIRE onConnectionStatusChanged" message in both client and server processes. If you have also enabled CROSSFIRE_TRANSPORT you will see "_waitHandshake" and "_sendHandshake" log messages.

If you are using Chromebug you should be able to set a breakpoint in crossfire.js in CrossfireModule's onConnectionStatusChanged() method, which will be hit upon connecting. Once you are connected, performing actions in Firebug such as setting a breakpoint, hitting a breakpoint, or stepping through code in Firebug in the Crossfire server process should cause CrossfireModule's fireEvent() method to be called with the Crossfire packet corresponding to the event.

Using FBTrace

Crossfire adds several additional FBTrace options.

CROSSFIRE - general tracing messages, mostly from CrossfireModule in chrome/content/crossfire.js.

CROSSFIRE_FRAMES - is used for tracing of stack frame serialization code called in CrossfireModule's onStartDebugging() hook.

CROSSFIRE_TRANSPORT - is for tracing of transport layer, in resources/SocketTransport.js.

CROSSFIRE_TOOLS - is tracing related to loading and registering 'tools' as part of the Crossfire Tools API.

Using Chromebug

Debugging Crossfire code with Chromebug usually works, to some extent, but your mileage may vary.