Venkman 0.9.x Frequently Asked Questions

scarab

The Index

1. Install/Uninstall Questions

2. Getting Started

3. Customizing Venkman

4. Documentation and Resources

5. Build/Source Questions

The Questions

1. Install/Uninstall Questions

1.1 How do I install Venkman in a Mozilla build?
Venkman has been part of Mozilla builds since Mozilla 0.9.5. Download the latest Mozilla release, and select Full or Custom when installing.

If you already have Mozilla installed and simply want to add or upgrade Venkman, visit the Venkman Development Page.

On all platforms, you will need to restart your browser after installing. On all versions of Windows, you will need to exit the quick launch icon on your taskbar as well, and on some versions of Windows, you may need to restart the operating system.

If you are running Mozilla 1.0, I *strongly* recommend you give the latest development release a try. This code was too new to make it into Mozilla 1.0, but is usually stable enough to use as a daily debugger, and has more features than what comes with Mozilla 1.0. Besides, if you don't upgrade, this FAQ won't make a whole lot of sense to you :)

^Back to the top

1.2 How do I install Venkman in Netscape 7.x?
The XPIs located on the Venkman Development Page will work on Netscape 7.x. Click on the install link at the top of the revision table to install Venkman in your browser.

On all platforms, you will need to restart your browser after installing. On all versions of Windows, you will need to exit the quick launch icon on your taskbar as well, and on some versions of Windows, you may need to restart the operating system.

These will not work on Netscape 6.x.

^Back to the top

1.3 How do I install Venkman in Netscape 6.2x?
The version of Venkman that runs on Netscape 6.x is no longer being maintained. Please upgrade to Netscape 7.x or Mozilla 1.0 for the latest debugger.

Venkman 0.6.2 runs on Netscape 6.2x, and can be installed from the Venkman 0.6.2 install page. These XPIs will not work on Mozilla 1.0 or Netscape 7.x.

On all platforms, you will need to restart your browser after installing. On all versions of Windows, you will need to exit the quick launch icon on your taskbar as well, and on some versions of Windows, you may need to restart the operating system.

^Back to the top

1.4 How do I uninstall Venkman?
Mozilla does not have an uninstall feature for XPIs yet. The following manual uninstall procedure is provided with no warranty whatsoever:
  1. Shut down Mozilla
  2. Rename the files components/venkman-service.js and chrome/venkman.jar to something else.
  3. Rename the chrome/ subdirectory to something else.
  4. Run regchrome
  5. If Mozilla starts up fine, everything worked, otherwise, unrename everything and give up, or delete the installation and start from scratch.

^Back to the top

2. Getting Started

2.1 How do I start Venkman?
  1. You can start Venkman from the Tools->Web Development->JavaScript Debugger menu.
  2. You can also start the browser with the -venkman command line option. This will launch Venkman instead of a browser front end. Other programs, such as the mail client or web browser can then be started from Venkman's Window menu.
  3. You can type x-jsd:debugger in the URL bar. Currently, this is the recommended way to launch Venkman from within Mozilla Firebird or Phoenix. Note that you can bookmark this URL, and file it wherever seems to make sense to you.

^Back to the top

2.2 Why does Venkman say something like ``Recorded local startup X, global YYY.'' when it starts up?
The 0.9.x releases of Venkman have a usage counter built in so that I can get an idea of how many people are actually using it. The local startup number represents how many times you have started Venkman, and the global number represents how many times Venkman has ever been started.

At startup, Venkman loads a CGI (with XMLHTTPRequest) located on hacksrus.com. Encoded in the URL is the number of times Venkman has been started, and the Venkman version number.

Every few days the web logs cycle into /dev/null and are lost forever. Before that happens, I run a shell script that scans the hacksrus web log and summarizes the data. This is the only data that is kept for more than a few days. You can see the results at <http://www.hacksrus.com/~ginda/venkman/usage-daily.txt>.

^Back to the top

2.3 Can I disable the startup counter?
Yes, but I wish you wouldn't. Type /pref permitStartupHit false to disable the startup counter.

^Back to the top

2.4 How do I make Venkman stop at the next error?
Select Debug->Error Trigger->Stop For Errors.

^Back to the top

2.5 How do I make Venkman stop when the next exception is thrown?
Select Debug->Throw Trigger->Stop For Exceptions.

^Back to the top

2.6 How do I make Venkman stop at the next JavaScript statement?
Click on the large red "X" on the toolbar, or select Debug->Stop. If no JavaScript is currently being executed, you will see a "..." appear over the "X" in the toolbar and the menu item will be checked. When the next line of JavaScript is encountered, the debugger will stop. You can cancel this by clicking on the "X" or selecting Stop again.

^Back to the top

2.7 How do I set a breakpoint?
In the view marked Loaded Scripts, locate the file you would like to set a breakpoint in. Double click on the file to display it in the view marked Source Code. Locate the line you are interested in and click once in the left margin of the Source Code view (to the left of the line numbers.) If the line of code you selected contains executable JavaScript code, you will see a solid red stop sign, indicating that the breakpoint has been set.

If the stop sign has a white letter F in it, it means that Venkman could only set a Future Breakpoint. This happens when the line you selected has no source code, or if the line of code has already been unloaded by the JavaScript engine (top level code is sometimes unloaded shortly after it completes execution.) A Future Breakpoint means that Venkman was unable to set a hard breakpoint now, but if the file is loaded later, and it has executable code at the selected line number, Venkman will automaticaly set a hard breakpoint.

Breakpoints can also be set from the context menu of the view marked Source Code, and by using the /break and /fbreak command in the Interactive Session.

^Back to the top

2.8 How do I clear a breakpoint?
There are a number of ways to do this:
  • From the Source Code view, click once on the breakpoint icon in the left margin to clear the Hard Breakpoint but leave the Future Breakpoint set. Click again to remove the Future Breakpoint.
  • From the context menu of the Source Code or the Breakpoints view, select Clear Breakpoint to clear the Hard Breakpoint, and Clear Future Breakpoint to clear the Future Breakpoint.
  • From the context menu of the function containing the breakpoint in the Loaded Scripts view, select Clear Script Breakpoints.
  • From the Interactive Session, use the /clear command to clear hard breakpoints, and the /fclear command to clear future breakpoints.

^Back to the top

2.9 How do I clear all breakpoints?
From the context menu of the Breakpoints view, select Clear All Breakpoints to clear all Hard Breakpoints and Clear All Future Breakpoints to clear all Future Breakpoints. You can also use the /clear-all and /fclear-all commands from the Interactive Session.

^Back to the top

2.10 What is a "Hard Breakpoint"?
A Hard Breakpoint is one that is set in JavaScript code that is currently loaded by the JavaScript engine. Venkman can only stop at Hard Breakpoints. Venkman cannot set a Hard Breakpoint in script that is not currently loaded.

^Back to the top

2.11 What is a "Future Breakpoint"?
A Future Breakpoint causes Venkman to set a Hard Breakpoint any time a file with a matching url is loaded, which has executable code at the line specified by the Future Breakpoint. These are typically used to stop in top level script, or in files that are not yet loaded.

^Back to the top

2.12 What does the Profile button do/ How do I use the Code Profiling feature?
Profile can be used to measure execution times for your scripts. To enable profiling, click on the Profile button in the toolbar. While Profiling is enabled, Venkman will collect call count, maximum call duration, minimum call duration, and total call duration for every function called. Once you have Profiling enabled, execute the script you would like to profile. When you are done, click "Profile" again to stop collecting data.

When profiling is enabled you will see a green check mark on the toolbar button, and the menu item will be checked as well.

You may repeat the procedure as required to collect all of the data you are interested in. The profile data will accumulate until you select Profile->Clear Profile Data.

When all of the data has been collected, you can select Save Profile Data As... from either the Profile or the File menus. The output format depends on the file extension you select. The supported formats are HTML, XML, CSV, and plain text. If Venkman does not recognize the file extension, the output will be in plain text. Note that the CSV format can be imported into most spreadsheet applications.

If you would like to save profile data only for specific files, select those files in the Loaded Scripts view (the view supports multiple selections, exactly how to do this depends on your operating system), and choose the Save Profile Data As... option from the context menu. You can clear profile data for selected scripts by using the Clear Profile Data menu item.

^Back to the top

2.13 What does the Pretty Print button do?
This button toggles Pretty Print mode. While in Pretty Print mode, the contents of the Source Code view will contain the decompiled source text for the selected function. This is the same text you would get from the toSource method of the Function prototype. If the source text you are debugging is poorly formatted, Pretty Print can help make it easier to read by inserting line breaks and whitespace in appropriate places.

When Pretty Print is enabled you will see a green check mark on the toolbar button, and the menu item will be checked as well.

You can set breakpoints and single step through Pretty Printed source just as you can with the original source text.

You can save the Pretty Printed source to disk with the Save Source View As... option from either the File menu or the Source View context menu.

If Pretty Print is not working for a particular function, the function may have been unloaded by the JavaScript engine, or you may not have the function selected. To select the function, double click on it in the Loaded Scripts view.

^Back to the top

2.14 How do I add a watch?
Type /watch-expr someExpression in the Interactive Session. The expression will be re-evaluated when execution stops again, when the /eval command is used, and when the /watch-expr command is used.

Alternatively, you can select ``Add Watch Expression...'' from the context menu of the Local Variables view to add a watch for a specific variable.

^Back to the top

2.15 The label for my watch is dark grey and bold, what does that mean?
That indicates that the property in question comes from the prototype of the object you are inspecting, and not from the object itself.

^Back to the top

2.16 The label for my watch is red, and the value is an object of type Error, what does that mean?
When Venkman encounters an uncaught exception while evaluating a watch expression, the label turns red, and the value of the watch will be the exception that was caught by Venkman.

^Back to the top

2.17 How do I remove a watch?
Select one or more watches to remove, and choose the "Remove Watch" menu from the context menu. You can also remove a watch from the Interactive Session with the /remove-watch command.

^Back to the top

2.18 Why do some of my function names show up in square brackets? 

 // this is a function named foo.
 function foo () {}

 // this is an anonymous function!
 var foo = function () {}

 var o = {
     // this is an anonymous function, too!
     foo: function () {},

     // but this is a function named bar_func 
     bar: function bar_func () {}
 };
guess.js
Venkman will guess the intended names
for anonymous functions.

JavaScript allows programmers to declare functions without names. Keep in mind that simply assigning a function to a named variable does not name the function (see guess.js at right.) While there is nothing particularly wrong with anonymous functions, they of course, provide no name for the debugger to display. This can make debugging difficult (imagine having to keep track of more than two stack frames named "anonymous".) Venkman will make an attempt to guess the intended function names for anonymous functions. The situations illustrated in guess.js lead to easily guessed function names, but anything that deviates too much from that example is likely to confuse Venkman.

When Venkman can make a guess, the function name will appear in square brackets. When Venkman can't guess, the function name will be anonymous. You'll likely see these square bracketed function names pop up in various places while using Venkman.

See Also: Can I change the regular expression used when guessing function names?

^Back to the top

2.19 How come I don't see any files from chrome: urls?
When the Debug->Exclude Browser Files menu item is checked, all files from chrome: urls will be removed from the Loaded Scripts view, and Venkman will not debug them. If you want to debug them, uncheck this menu item.

^Back to the top

2.20 How come I see all these files that look like they are part of the browser?
When the Debug->Exclude Browser Files menu item is unchecked, Venkman will display files from chrome: urls in the Loaded Scripts view. If you don't want to see these files, check this menu item.

^Back to the top

2.21 How can I set the character set for a JavaScript file?
At this point, Venkman does not have a way to set a character set on the fly, however, you can use a meta comment in your JavaScript file instead. Add a comment like...
//meta http-equiv content-type charset=Shift_JIS
...to your JavaScript file, and Venkman will use the correct character set.

^Back to the top

2.22 Can I give focus to the Interactive Session with the keyboard?
Yes. Just like in vi, press ESC to give focus to the input box located below the Interactive Session.

^Back to the top

3. Customizing Venkman

3.1 How do I rearrange the views?
You can move any view to a new location by pressing and holding the (left) mouse button, and dragging it over a different view. You should notice a black line in the position where the view will be placed. As you drag the view to different sides, the black line will follow. Let go when the black line is where you want it.

^Back to the top

3.2 How do I stack views into a tab list?
Drag any view over the box icon () of another view. When the icon turns to a star, let go of the mouse button.

You can rearrange the tab order by dragging tabs, or drag a tab directly to another location.

^Back to the top

3.3 How do I put a view in a new window?
Click on the icon in the top left corner of the view.

^Back to the top

3.4 How do I put a view back into the main window?
Drag the view back to the position you want it in the main window.

^Back to the top

3.5 Can I put more than one view in the same new window?
Yes. You can drag any view from any window into any other window.

^Back to the top

3.6 I've removed all the views from the Venkman main window, and now I can't get them back in!
This is a bug. To work around it, show the Interactive Session view via View->Show/Hide>Interactive Session and type /restore-layout factory. See bug 151785 for more information.

^Back to the top

3.7 Can I save my view layout?
Yes. Use the /save-layout command to give your current view arrangement a name. You can recall the layout later with the /restore-layout command. For example, you might save a minimal layout with just the Source Code, Interactive Session, and Loaded Scripts views open as ``minimal'', and a more elaborate view including the Watches, Local Variables, and Call Stack views as ``stopped''. You may use the command /restore-layout stopped while stopped at a breakpoint and want to examine some variables, and /restore-layout minimal when you are done.

Venkman restores the layout named ``default'' at startup. By default, Venkman will save your current layout as ``default'' before exiting. You can turn this off by unchecking View->Save Default Layout On Exit. You can save the current layout as ``default'' with View->Save Default Layout Now.

The special layout ``factory'' is hard coded into Venkman and cannot be saved over.

^Back to the top

3.8 Can I change the color scheme in the Interactive Session?
Yes. From the context menu of the Interactive Session, or from the View menu, select one of the options in the Interactive Session Colors submenu. Default Colors uses your browser defaults for foreground, background an link colors. Dark Colors is a dark background with light text, and Light Colors is a light background with dark text.

^Back to the top

3.9 Can I change the default tab width?
Yes. Type /pref tabWidth n in the Interactive Session, where n is the number of spaces you would like to see for a hard tab character.

^Back to the top

3.10 Will Venkman respect the tab width in my emacs mode line?
Yes. If you have a comment in the form
/* -*- tab-width: 4 -*- */
in your script, then the tab width will be set to four spaces regardless of the setting of your tabWidth pref.

^Back to the top

3.11 Can I change the regular expression used when guessing function names?
Yes, It is stored in the guessPattern pref, and defaults to (\w+)\s*[:=]\s*$. When guessing function names, Venkman matches all of the text preceeding the last instance of the word function on the starting line of the function. The results of the first capture (the (\w+) part in the default expression) will be used as the function's name. The maximum number of previous lines to include is set to 5 by defaut, and can be changed with the guessContext preference.

^Back to the top

3.12 Can I write my own script to extend Venkman?
Yes! It's not too hard to add new commands to Venkman. Once you have a custom command, it's even easier to add it to the UI. And of course, Venkman uses JavaScript as its scripting language (well, Venkman itself is written in JavaScript.)

There is no formal documentation written up on this yet, but there have been a few posts on the newsgroup about the subject. Check here, here, and here. There are also some notes from a "Techtalk" presented at the Netscape campus, which covers some of the basics of how Venkman works.

If you have a specific plug-in you'd like to write and don't know where to start, or get stuck somewhere, please ask in the newsgroup. The more questions I answer, the more content I'll have for some documentation.

^Back to the top

3.13 How do I change a Venkman preference?
See the next question.

^Back to the top

3.14 Where can I find a list of preferences that Venkman uses?
Use the /pref command in the Interactive Session. /pref all by itself will display all preferences, along with their current values. /pref somePattern will list all prefs with names that start with somePattern, and /pref somePref myValue will change the pref named somePref to the value myValue.

^Back to the top

3.15 How do I revert a preference to its default value?
Prefix the pref name with a minus ('-') character, as in /pref -somePref.

^Back to the top

4. Documentation and Resources

4.1 Does Venkman have any online help?
The Interactive Session has interactive help for console commands. Type /commands to get a list of console commands, and /help commandName for help on the command named commandName. You don't need to type the whole command name, /help b will show help for all commands starting with the letter "b".

Type /help with no arguments to view a searchable command reference in a browser window.

^Back to the top

4.2 Where is the rest of the documentation?

^Back to the top

4.3 Does Venkman have a newsgroup or mailing alias?
Yes. The newsgroup is netscape.public.mozilla.jsdebugger and can be found on the public news server news.mozilla.org. It is mirrored on the mailing alias mozilla-jsdebugger@mozilla.org. To subscribe, send an email to mozilla-jsdebugger-request@mozilla.org with the subject "subscribe". To unsubscribe, send a mail to the request address with the subject unsubscribe

Google groups doesn't carry the group, for some reason, but GMANE does. They call it gmane.comp.mozilla.devel.jsdebugger.

^Back to the top

4.4 Is there an IRC channel for Venkman?
Yes. The channel is #venkman on irc.mozilla.org.

If you are running Mozilla and have ChatZilla installed, you can join the channel by clicking on the #venkman link above. ChatZilla is available at http://www.hacksrus.com/~ginda/chatzilla/.

If you are new to IRC, please read over irchelp.org.

Please be patient if you join #venkman looking to ask a question. Often, I'm logged on to IRC but not looking at the window, or even sitting in front of the computer. If I see your question before you leave the channel, chances are I'll answer it. If you include the word ``venkman'' in your question, it'll ring a bell on my machine which may make me respond sooner. Please don't abuse that :)

^Back to the top

4.5 Are there any screenshots of Venkman doing stuff?
Yes, <http://www.hacksrus.com/~ginda/venkman/screenshots/>

^Back to the top

4.6 How do I suggest a question for the FAQ?
Please mention it on the netscape.public.mozilla.jsdebugger newsgroup.

^Back to the top

4.7 Can I get Venkman in another language?
Yes. Currently, dynamis maintains a Japanese localization of Venkman, as as well as most (if not all) of the Venkman documentation. See http://skillup.jp/venkman/ for more information.

There are probably other localizations out there that I don't know about. If you maintain a Venkman localization please let me know.

^Back to the top

5. Build/Source Questions

5.1 How do I build Venkman?
Venkman is built by default on all platforms.

^Back to the top

5.2 How do I not build Venkman?
Venkman is built in two parts.
  1. The platform specific XPCOM component, compiled, is about 75k. It is referred to as the jsd library, and is required if you ever want to install one of the XPIs from the Development Page. Other than a small amount of disk space, there is no overhead in including this library in your distribution, it lies dormant until Venkman (or some other component) makes use of it. If you maintain a port of Mozilla for others, and those users may want to install Venkman at some later point, you should not exclude the jsd library. If the build is just for you, and you never want to install Venkman, then add --disable-jsd to your configure options.
  2. The cross platform front end, compressed into a .jar file, is about 240k. This is Venkman proper, and is what is included in the XPIs distributed from the Development Page. You can exclude this from your custom build and still be able to install Venkman at a later date via XPI. If you want to disable the this, add --enable-extensions=default,-venkman to your configure options.
Because the Venkman front end cannot function without the jsd library, the --disable-jsd option automatically disables the front end. There is no need to specify both.

^Back to the top

5.3 Where is the Venkman source code located?
Venkman consists of two components. The User Interface component is written entirely in JavaScript and XUL and lives in mozilla/extensions/venkman/. Most of the actual JavaScript code is in the resources/content/ subdirectory.

The Debugger Service component is an XPCOM component written in C++ that exposes a debugger api used to control the JavaScript engine. This code lives in mozilla/js/jsd. The XPCOM interface is in idl/jsdIDebuggerService.idl, and the implementation is jsd_xpc.cpp.

^Back to the top

5.4 What do I do if I find a bug in Venkman?
  1. Search for duplicates. You can scan the entire Venkman bug list or search for a particular bug on the list.
  2. If you can't find a duplicate, then please file a bug.

^Back to the top

Valid HTML 4.01!