Descend

Descend is a proof of concept, showing the possibilities of creating an open source debugger UI with Mozilla XULRunner. Descend is distributed under the MPL/GPL/LGPL tri-license.

Getting Started

The Descend source code is available in a Mercurial repository. Mercurial can be downloaded from Selenic. Windows users may find TortoiseHG useful.

Descend currently does not contain a local copy of XULRunner (and may never have one; It would be best to use a globally available XULRunner). You can use the XULRunner bundled with Firefox 3.x to run Descend.

Setup Your Mercurial Client

At the minimum, you should configure your Mercurial client with a "username". For hg, add the following to your ~/.hgrc file (or create a new one)

[ui]
username = Real Name <[email protected]>

Development

Clone the Source Repository

Create a local repository with the following command:

$ hg clone http://hg.kodewerx.org/descend

This will create a new subdirectory called "descend" containing all of the source code and repository history.

Push Changesets to hgkw

If you have developer access to push changesets to the hgkw repository, use the following command: (Don't forget to commit to your local repository, first!)

$ hg push ssh://[email protected]/repos/descend

Running Descend

On Linux, run the included descend_linux shell script. (Tested on Ubuntu 8.10)

On Mac OS X, run the included descend_osx shell script.

On Windows, go to Start -> Run, and type:

"C:\Program Files\Mozilla Firefox\firefox.exe" --app "path/to/descend"

Be sure to verify the path the your Firefox installation is correct. You can also create a batch script to do the same thing.

Developer Notes

In its current form, Descend is just a "syntax highlighter" that can process simple 6502 assembly source code. It will spit out an XHTML-ized copy of the source, with some pretty CSS.

Style Contexts

The concept of a "Style Context" is greatly inspired by GeSHi, which uses "Language Files" to define to the highlighter engine how text should be styled. Descend uses files similar to GeSHi's Language Files (called Syntax Contexts) to define syntax.

Writing new syntax highlighters should be very simple. See descend/chrome/content/styles/6502.js for the 6502 style context.

The Style Context is a JavaScript object which tells highlight.js how to interpret the input text. It is technically an array of simple objects, where each object contains (at a minimum) a rule and a class.

The rule tells highlight.js what to search for. It can be either a regular expression (do use the /g flag if you want to find all occurrences) or an array of strings.

The class is simply which CSS class to give the text which matches rule. The CSS used is template.css.

Example Style Context

var style = [
    {
        rule: /hello,?\s*world!/g,
        class: 'hello-world'
    },
    {
        rule: [ 'hello', 'world' ],
        class: 'hello-world'
    }
];

Style Context Reference

Each object contains two mandatory members; rule and class:

rule

Specifies a matching rule as either a single RegExp or as an Array of Strings which will later each be searched for as exact matches. Notes for using RegExps: Always include the 'g' flag; Only use the 'm' and 'i' flags if you truly need them (eg. using ^ or $ to match the beginning/end of lines, or if your RegExp includes strings that must match case-insensitively!) There is currently no need for the 'y' flag. Use remembering-parentheses sparingly (and only with the id member).

class

Specifies which CSS class[es] should be used to style the matches. Multiple classes should be separated by spaces.

In addition, each object may have zero or more optional members:

anchor	A String which specifies that these matches should be generated as HTML anchors. The String given is used as a prefix for the anchor's 'name' attribute.
delim	An Array containing 1 or 2 Strings that specifies which characters are allowed to appear before [0] and after [1] the rule. An empty String designates that any character is allowed (default). If only one String is specified, it is used for both before and after delimiters. Only has effect with String rules.
icase	A Boolean value identifying the rule as case-insensitive (true) or case-sensitive (false, default). Only has effect with String rules.
id	A Number representing which remembered match to use for the anchor or link name. Defaults to 0. Only has effect with anchor or link, and RegExp rules.
link	A String which specifies that these matches should be generated as HTML links. The String given is used as a prefix for the target anchor.
sub	A sub-context: an Array of Objects containing rules, classes, etc. The text matching rule will be recursively styled with this sub-context.

The highlighter will match text in Object-order. For example, you should match single line comments (beginning with //) before matching division operators (a single /) by writing your comment-matching rule first. If they are specified in opposite order, you will be given two consecutive division operators and the comment will not be styled.