Nsisdbg plug-in

From NSIS Wiki
Jump to navigationJump to search
Author: saivert (talk, contrib)


This plug-in is no longer maintained, if you need a Unicode and/or 64-bit version, use the Debug_plug-in.


Links

Updates:

-  16th 2005: I'm no longer distributing the installer. A simple 7-zip archive is used instead.

Zip.gif nsis-debugger.7z (218 KB)

(removed darklogic installer. file missing)

- February 23th 2008 (Alternative from Wayback machine ):

Zip.gif NSIS-Debugger.7z (218 KB)

- August 9th 2012:

Zip.gif NSIS-Debugger.zip (14.3 KB)

See source comments for changelog.

Introduction

I have created a new debug tool for NSIS. It's called NSIS Debugger and you can download it from my homepage (see above links section).

NSIS Debugger is a NSIS plugin which allows you to debug your NSIS installers. The plugin will create a dialog which will be displayed alongside the NSIS window. The first thing you will get familiar with is the tabbed pages. Use them to switch between variable list, stack view, debug log, config. and about page.

Description

Using the variable list which is on the first tab page you can change all the variables, clear them, keep (save for later use) and restore them (from a previous keep operation). To edit a variable simply use the in-place edit box by clicking a variable. The stack view gives you a list of the strings pushed on the stack. You can pop them off it, push more strings to it and clear the entire stack. You can edit a stack item simply by clicking it and use the in-place editbox. NSIS Debugger has a debug log which you can add entries to by calling a function in your installer script.

To install the plugin, simply copy it to the plugins folder under your NSIS folder.

This version of NSIS Debugger has only been tested with NSIS 2. It should work perfectly fine with older versions too.

How to use

Initialization The first thing you have to do to use the debugger is to set up a couple of lines in the .onGUIInit callback function in the script. You will also need to put a line in the .onGUIEnd callback function as well (this is covered below).

Function .onGUIInit
 
  InitPluginsDir
  ; Remember to include the "/NOUNLOAD" option.
  ; This is to keep the debugger running.
  nsisdbg::init /NOUNLOAD  
  ; To start the debugger hidden pass "hidden"
  ; to the stack like this:
  ;   nsisdbg::init /NOUNLOAD "hidden"
  ; You will be able to show it again by using the
  ; system menu of the installer. Read about this below.
 
  ; old fashion way (pre-2.0)
  ;   GetTempFileName $9 ; $9 will globally be used in the script
  ;   File /oname=$9 ${NSISDIR}\Plugins\nsisdbg.dll
  ;   CallInstDLL $9 /NOUNLOAD init
 
  ; optionally set a few option by calling setoption
  nsisdbg::setoption /NOUNLOAD "notifymsgs" "1"
  ; read more about the setoption function below
FunctionEnd

Since the .onGUIInit function is included in the MUI System.nsh file you can not create a function with the same name in your installer code To use NSIS Debugger with MUI you need to initialize it like this: Define custom function for the MUI GUIInit callback by adding a custom function define. This define must come before inserting any language macros

!define MUI_CUSTOMFUNCTION_GUIINIT myGUIInit

Once that is done you can initialize the NSIS Debugger in the same was as the .onGUIInit function shown above. The only difference is that the function should be named myGUIInit (or whatever name you put in the define statement).

Use the debug log

Now as you have the debugger up and running, let's use the debug log feature. Call sendtolog like in this example

  nsisdbg::sendtolog /NOUNLOAD "Value of $$1 is $1"
  ; Only push one string. Subsequent strings will be left on the stack.
 
  ; old fashion way (pre-2.0)
  Push "Value of $$1 is $1"
  CallInstDLL $9 /NOUNLOAD sendtolog

Notes

Plugin is not compatible with Silent setup mode ( /S switch ).

TODOs

http://code.google.com/p/delphi-code-coverage/issues/detail?id=45

http://code.google.com/p/delphi-code-coverage/issues/detail?id=37