Nullsoft Sfx Installer Unpack

1. Nullsoft Scriptable Install System Written In
2. Nullsoft Install System V2.46
3. Nullsoft Installer Wizard

The Current State of MAXScript Installation

Using a generic sfx that does nothing but extract its files. And that uses gzip. Nullsoft Install System v1.98. Virtlink 30th March 2003 14:03 UTC. Cabextract will unpack anything that contains Microsoft cabinet files, but typically InstallShield does not, despite having files called 'data1.cab'. Instead, to unpack InstallShield 'cab' files, use the unshield program that's part of the SynCE project. – Stuart Caie Mar 23 '15 at 9:50. NSIS = Nullsoft Scriptable Install System is a free installer with sources (available at sourceforge.net). Install (or uninstall) exe files made with NSIS have the stub that's shown by PEID - Nullsoft PiMP Stub Nullsoft PiMP SFX.

By: Jeff Hanna

What’s Wrong With .MZP Files?

Having managed tool rollouts at both small (four artists)and large (50+ artists) companies I’ve become increasingly frustrated with MAXScriptinstallation options. MZP files do ake the process less painful, but they havesome inherent problems and limitations:

• They don’t provide any feedback to the user.
  The mzp.run script that controls an .MZP file’s installation can’ttrigger MAXScript dialogs natively. Unless the script author creates apost-installation script and codes a run line into the mzp.run file therewon’t be any feedback to the user. I tried such a method for a while but eventuallygave up on it. It’s cumbersome and can leave unused MAXScripts on theuser’s hard drive.
• They require Max to be running.
  This may not seem like a problem, but it goes against the way mostusers interact with their Windows based computers. Unless a programauto-updates itself a user isn’t conditioned to start a program beforethey update it. The Windows user experience is usually exactly theopposite of that. A user starts an installer to update a program. If theprogram being updated is currently running then the installer will ask theuser to close it before the update process can continue. The majority ofsupport requests I’ve received regarding script installations stem fromthe fact that the user is treating the .MZP files as if it were aninstaller.
• .MZP files are .zip files, just renamed.
  This can be seen as a benefit and a problem. The problem happens when auser doesn’t know how to properly install an .MZP file but figures outthat they can be opened in a zip compression program. Invariably the userputs all of the extracted files someplace incorrect, like the root of c:3dsmax,or worse, and then either can’t get the script to work in Max or, in thecase of scripts with extensions, gets errors when Max starts.
• Due to a limitation in Max installed icons for toolbarswill not show up until Max is restarted.
  This issue has been around for about as long as MacroScripts have been inMax. It’s not possible to force Max to refresh its icon cache. This meansthat any toolbar bitmap that is added after Max is started will not bevisible until the user exits Max and restarts it. This negates whateverbenefit Discreet might have seen in having users install scripts fromwithin a running instance of Max. Since an mzp.run file can not display adialog (as mentioned above) there isn’t an easy way to tell the user thatthey’re going to have to close and re-launch Max to truly finish theinstallation.
• MZP files are poorly documented in the user’s manual.
  The index for the User Reference help file doesn’t contain any entriesfor “.mzp”. Doing a search in the help file for “installing a MAXScript”lists eleven topics. The first one is “Particle Flow FAQ”. The first entrythat is specifically MAXScript related is #5, “Running Scripts from theCommand Line”. There is no entry for installing MAXScripts. The help fileentry for the MAXScript “Run Script” menu entry doesn’t even mention thatyou should use that menu command to install .MZP files. If a user goes tothe help file to find information on how to install .MZP files they won’tgain any useful knowledge.
• MZP files aren’t universally accepted.
  Since the use of MZP files isn’t enforced you can find many scripts thatdon’t use them. ZIP files with (assumed) proper directory structures areused, ZIP files with no directory structure and a file on how to do amanual installation are used, self extracting ZIP files are used, etc…While using true application installers may be seen as just adding to theproblem, they provide a lot of benefits and an easier and more powerfulway of doing script installations.

Why Use An Installer?

Because of those problems with MZP files I have moved awayfrom using .MZP files for script delivery of our in-house tools. I now buildapplication installers. True application installers get around all of theproblems I listed above:

• A good installer system will allow for the display ofdialogs so that the user can receive information and/or make choicespertaining to the installation process.
• They follow the accepted Windows actions for installing orupdating applications.
• The files can’t easily be extracted from the archive andmanually placed on the hard drive.
• Max doesn’t have to be running so its icon cache will beupdated the first time a user runs the program after installing a new tool.If Max is running during the installation the user can be alerted to thefact that they need to close and re-launch the application.
• Installer usage is something most people understand so theredoesn’t need to be support documentation on how to perform theinstallation.

There are other benefits to using an application installer:

• The process can easily add or remove data from theregistry and .INI files.
  It has become standard practice for me to add entries into Max’s plugin.inifile for every in-house script I create. Specifically I add new key valuesinto the [help] section that point to documentation for the script. Thisway the user only has to go to Max’s HelpAdditional Help menu to findinformation on any script they have installed.
• The installer can be branded with corporate logos.
  This might not seem like much, but if you are releasing your scriptseither professionally or for free any branding will help people rememberyou and the work you’ve done.
• The installer logic allows for user input.
  You can put many different scripts into one installer package and thenpresent the user with an options dialog that lets them choose whichscripts they would like to install. Every quarter I take all of thescripts I’ve released internally over the previous three months and add thoseto our base art tool install package. The process is very quick and theresulting code is easy to maintain. By doing this new artists and ITpersonnel outfitting new machines don’t have to hunt around for all of thenecessary art tools. One installer contains all of the scripts, tools,plug-ins, etc… they will need to accomplish their job.

NSIS and HM NIS Edit

Application installer development packages used to be verycomplex and expensive. That changed when NullSoft (the makers of WinAMP)released the NullSoft Installer System(NSIS) a few years ago. NSIS, now at version 2.04, is free to use andmodify for any purpose. The license insures that the source code is availableand can be changed by anyone. While this code freedom might not be important tomost MAXScripters it does guarantee that NSIS will always be around, even ifNullSoft goes away or decides to stop development on it.

The documentation to NSIS is very robust and the usercommunity is very active, much like MAXScript.

NSIS installers are compiled from source code. The languageis of a lower-level than MAXScript. There are no loops and code branching ishandled by comparing values stored in variables on a stack. To ease NSIS codecreation there are dedicated NSIS editors that provide easy access to NSISfunctions and wizards to help you create installers. One of the most widelyused NSIS editors is HM NIS Edit,now at version 2.0.1. Like NSIS, HM NIS Edit is free to use and modify.

About the only thing that HM NIS Edit doesn’t do isintegrate with an existing version control system. If you are going to keepyour installer files under source control, as you should, you’ll have to use adedicated front end to your source control system for your changes and commits.

Tutorial

Creating an installer for a MAXScript using the HM NIS Editwizard is easy. This tutorial will create an installer for a MAXScriptblackjack game, MaxJack.ms, which I’m currently developing in my spare time.

The first thing you’ll need to do is to find the location ofthe script and any supporting files (.mcr files, icon files, configurationfiles, etc…) on your hard drive. NSIS will pull these files from thoselocations when it is compiling the final executable.

Load HM NIS Edit and pick the “FileNew Script from Wizard…”command (Ctrl+W). This will start the new installer wizard.

Click the “Next” button and on the Application Informationpage enter the name of your application, its version number, theauthor/publisher, and a support website. This information will be displayed onthe opening dialog of the compiled installer.

None of the fields on this page are required. You can leavethem blank if you don’t have entries for them. When you have the dialog filledout click the “Next” button to move on.

On the Setup Options page you can specify an icon file touse for the final executable, the name of the executable, and what language(s)should be available to the end user.

All of the fields on this dialog are required. If you don’thave an icon file leave the default entry in that field. The GUI and Compressoptions control how the executable’s dialogs will appear and what compressionalgorithm NSIS will use to compact the data. These are advanced options andgenerally shouldn’t be changed from their defaults of “Modern” and “zlib”.

The Application Directory and License page controls wherethe default installation directory will be, whether or not the user can changethis, and what license (EULA) should be displayed during installation.

If you don’t have a license file then leave that fieldblank. The default Max installation folder location (c:3dsmax<5, 6, 7>) willserve as a good default directory. Later in this document I will show you atechnique for putting a variable name in this field and then scanning theuser’s registry to find the exact Max installation folder and having theinstaller executable use that location. The latter method makes the installermore fault tolerant as many users won’t have Max installed in the same locationon their machines.

Now on to the Application Files dialog where you can set upcomponents, pick the files to include in your installer, and pick where theywill be installed.

Components allow you to group your files into differentcategories. In this example I have two components, “Game Files” and“Documentation”. I’ve also enabled the option to let users pick whichcomponents to install. This way, during installation, the user can decide ifthey want the blackjack rules installed on their machine or not. If you disablethe options checkbox then the user can not make a choice and all files will beinstalled.

When you click the “add new” or “edit” buttons located abovethe file list on the right you are presented with a file entry propertiesdialog.

The first field in this dialog contains the path to the fileon your machine. The second field contains the destination directory where thefile will be put during installation. INSTDIR is a NSIS constant. The value of INSTDIRis the application default directory that was entered on the Application Directoryand License dialog. Macro_MaxJack.mcr is a MacroScript so it must go into3dsmax7uimacroscripts. Since INSTDIR points to the root Max directory I’ve addedthe two sub directories onto the destination path for this file.

Making sure destination file paths are correct is crucial.At the core all an installer does is unpack files and move them to the correctlocations. If you have those locations wrong then files will not be put wherethey need to be.

The last field controls what the installer should do if itfinds an existing file of the same name in the destination directory. In thiscase it will do a date comparison of the two files and only make a change ifthe file in the installer package is newer than the one on the disk. Otherchoices include: always overwrite, never overwrite, and try to overwrite.

Once you have your files added and their destination pathscorrect click “Next”.

Application shortcuts aren’t pertinent to MAXScripts since scriptscan’t be launched from the desktop or the Start Menu. If you were making aninstaller for stand alone tools this is where you’d name the Start Menu folderand add the shortcut targets.

For now clear out all of the fields on this dialog and moveon.

Likewise the “Execute after setup” dialog doesn’t containany options that would be used for most MAXScript installations.

Unless you have a readme file or a program you need to runafter the script is installed leave these fields blank and click “Next”.

Adding an uninstaller for a script is a personal choice. Idon’t normally include one. They’re simple to enough implement with the wizard,though.

If you have the “Use uninstaller” checkbox enabled NSIS willcreate an uninstaller application and add it to the user’s AddRemove Programscontrol panel. The uninstaller will remove any installed files, delete anyfolders made during installation, remove all of the installed shortcuts, andremove any registry keys created during installation. The variable [NAME] onthis dialog references the value entered into the “Application Name” field backon the 2^nd wizard dialog, “Application information”.

You’re just about done. The final dialog has options forsaving the script, changing any absolute file paths to relative paths, andperforming an automatic compile of the code.

It should go without saying but save your script. You’llsave yourself a lot of data entry time if something unforeseen happensimmediately after you exit the wizard.

Path conversion can be both good and bad. If you are goingto store your installer script (*.nsi) in the same location as your developmentMAXScript files then I’d say yes, convert the paths to relative names. That wayyou can move the folder around on your hard drive and not have to worry aboutupdating the code. If your development scripts are always in the same location(e.g. in your 3dsmaxscripts folder) and your *.nsi file will be locatedelsewhere then leave the paths as absolute.

If you elect to compile the script HM NIS Edit will triggerthe NSIS compiler after it’s saved the installer script file.

When you click “Finish” HM NIS Edit will ask you for alocation and name for the script file, assuming you checked “save script”, andwill then optionally compile the script and put the executable in the samelocation as the saved .nsi file.

To install the MAXScript double click the icon of the newlycompiled installer.

Advanced Tips - EditingNSIS Code Directly

While the installer wizard is a great starting point it islimited. The most you are going to do with it is create an installer that putsfiles in a certain destination location, include an uninstaller, and possibly displaya EULA or a readme file. For most MAXScript installations that is probablyenough. But, if you want to add some intelligence to your installer to, forexample, find any and all versions of 3ds max installed on the user’s harddrive and configure the UI accordingly, or to add entries to the systemregistry or an existing INI file, you’ll need to get into the actual sourcecode of your installer.

NSIS code is ASCII text so it can be edited in any texteditor. I like to edit my NSIS files in HM NIS Edit since it has a nice IDEwith a forms designer and can compile the code directly. If you use a texteditor to edit your files you will have to run the command line NSIS editor tomake your executables.

Covering all of the features of the NSIS language is beyondthe scope of this document. Please refer to the NSIS help file or the websiteand community forums for information about the structure of the NSIS language.The following sections will give you some useful tips and tricks that relatedirectly to MAXScript installations so you can make your installers morepowerful and useful.

Locating the Max installation directory

I would like to thank the engineers at Numeric Data Labs for helping me with this tip. Thefigured out how to locate Max even though it doesn’t have a path key in thesystem registry.

Locating the installation directory of 3ds Max is trickierthan it would seem. To find it you need to get the registry key that tells youthe location of the default icon for the version of Max you are using. Thedefault icon is the icon that will be applied to any new .max files, so it hasto be registered with the system. The location in the registry for this isHKEY_CLASSES_ROOT3dsmax#DefaultIcon, where # is the revision of Max in whichyou are interested. The value in the key is a string that is a full path to the3dsmax.exe executable and the icon file stored in the executable that should beused. For example, ”c:program files3dsmax73dsmax.exe,1”

NSIS has a command to pull string information out of theregistry. The command is:
ReadRegStr $var <root_key> <sub_key> <name>

Var is a user variable defined at the top of the NSIS codeto hold the retrieved string. Remember that INSTDIR is a constant that refersto the destination directory for the installation. While it would be nice to putthe registry value directly into INSTDIR there would be too much information. Theregistry string has to be read into a variable so that it can be massaged intoa properly formed path before it is copied into INSTDIR

The NSIS command to get the path to Max 7 from the registryis:
ReadRegStr$TempPathHKCR'3dsmax6DefaultIcon''

The Max icon entry in the registry doesn’t contain a namevalue so the last function parameter is entered as a null string.

TempPath now contains the value “C:3dsmax73dsmax.exe,1”.That’s close to what we want, but the application name and icon offset aren’tpart of the path. They need to be removed. NSIS doesn’t have a trim functionbut it does have a string copy function, StrCpy(). That command can copy eitherentire strings or just part of a string. We can use it to copy the part of thestring we want into the INSTDIR constant and have our destination path point tothe root of the 3ds max folder.

StrCpy$INSTDIR $TempDir-13

The “-13” parameter tells StrCpy to not copy the lastthirteen characters of the source string (3dsmax.exe,1) to the destinationstring. INSTDIR now contains the string “C:3dsmax7” which is the full path tothe root folder.

As was mentioned in the tutorial section you can add on tothe $INSTDIR path as needed:

“$INSTDIRscripts” would point to c:3dsmax6scripts
“$INSTDIRuiicons” would point to c:3dsmax6uiicons
etc…

With this information you can code your installer to alwayspopulate the “Destination Folder” field on the options dialog with the exactlocation of 3ds max. This reduces the possibility of user error in picking theright installation location.

Many of the artists where I work have the latest revision ofMax plus at least one (sometimes more) prior versions installed. Since thepaths in the registry only differ by the revision number it’s possible to puteach path into a different variable and then pass those variables into afunction that handles the script/tool installation. That way one function caninstall the script into all versions of Max on the user’s hard drive. Some ofthe MAXScript extensions we use are specific to certain versions of Max. Theinstaller function takes a parameter to instruct it to only install certainplug-ins in certain versions of Max

To support multiple versions of Max with MZP files theartist would have to load each version of Max and execute the installer script,possibly having to use different installers for different versions of Max.

Adding an Entry to Max’s Plugin.ini File

With NSIS it is just as easy to manipulate INI files as it isto deal with the registry. Max has a menu under the Help menu called“Additional Help” that is a great, but under used, resource. It is there toallow script and plug-in developers the ability to add the documentation fortheir tools to the Max user interface. Easy access to documentation for userswill lessen support issues, so this menu is a worthwhile feature.

Entries in the “Additional Help” menu are stored in the3dsmaxplugin.ini file under the [Help] section. Each entry consists of the nameto display in the menu and a path to the documentation. In NSIS it is one lineof code to add a new string to an INI file.

WriteINIStr ini_file section key value

WriteINIStr“$INSTDIRplugin.ini” “Help” “MaxJack Rules” “$INSTDIRHelpMaxJack.chm”
will add an entry to the “Additional Help” menu named “MaxJack Rules” and willload “c:3dsmax7helpMaxJack.chm” when the user selects it.

Notice that I used $INSTDIRfor both the path to the plugin.ini file and as part of the string that will bewritten. NSIS knows that an entry of “$INSTDIR...” in an INI file would beuseless so it expands any variable or constant used in a string to the value itholds.

Determine if Max is Running

Scripts can be installed while Max is running. ButMacroScript icons and any plug-ins that get installed will not be availableuntil Max is restarted. Because of those issues you might want to detect if Maxis running at the start of the installation process and inform the user that itneeds to be closed.

This tip is more complex than the previous ones. It involvesusing the NSIS stack, confirmation dialogs, and subroutines. The process can beoutlined as:

• Push a suppliedvariable to the stack. You can’t push user named variables to the stack soyou must use one of the stack capable variables that NSIS supplies.
• Start aloop
• In theloop try to find a window named “3dsmax”. If it exists put its handle intothe variable on the stack. If not, put a 0 into the variable.
• If thevariable holds a 0 then assume Max isn’t running. Exit the loop and go tothe subroutine that contains the file installation code.
• If the variable holds a handle then Max is running. Put upa dialog asking the user if they would like to close Max. If the useranswers yes then exit the loop and jump to the subroutine that closes theapplication. If the user answers no then exit the loop and jump to thesubroutine that skips any Max file installation.

The commands that will get used are Push(),FindWindow(), IntCmp(),MessageBox(), Sleep(),Goto(), and SendMessage().The code snippet below shows the logic and contains comments that explain eachstep.

Putting the value on the stack, comparing against that, andjumping to subroutines acts like an If/Then/Else block. NSIS doesn’t haveIf/Then branching so you have to build the logic yourself. While this formatisn’t as high-level as MAXScript constructs it still offers more flexibilitythan mzp.run files.

There aren’t Do/While loops in NSIS, either. There aresubroutines you can jump to. Keep in mind, though, that the code is executedsequentially. When execution gets to the end of one subroutine it willimmediately fall through to the code beneath it unless it is told to goelsewhere. In the example below the “Goto loop”command will always keep execution within the “loop” subroutine until the userclicks either “Yes” or “No”. If the Gotostatement wasn’t there then the installer would put up the message box andimmediately try to close Max.

;Put a newvariable on the top of the stack.

Push$9

;A subroutinethat will be used as a loop

loop:

;Check for awindow named “3dsmax” Put the window handle on the stack if found

FindWindow$9 '3dsmax'

;Compare the value on the top of the stack to 0

;If true then Max isn’t running. Jump tothe subroutine
;that will install the files.

IntCmp$90installMaxFiles

;If the compare isn’t true then Max isrunning.

;Put up a Yes/No message box asking ifthe user would like to close it.

;MessageBox() parameters differdepending on what the first

;parameter is. In this case it is aYes/No messagebox so it has to

;have subroutine names to jump to foreither choice.

;If the user picks “Yes” then jump tothe “closeMax” subroutine.

;If they pick “No” then we’re done.Jump to the “done” subroutine.

MessageBoxMB_YESNO‘Max is running. Close it?’IDYES closeMax IDNOdone

;wait one second before moving on.

;If there is no sleep statement theprogram will actas if it is locked up

;since it is redrawing the messageboxfaster than the user can click on

;a button.

Sleep1000

;Jump back tothe top of this subroutine so the installer doesn’t

;do anythinguntil the user has made a choice

Gotoloop

closeMax:

;SendMessagesends a command to a HWND handle. In this instance the message

;is “close”. The final two parameterscan optionally hold a return value and

;a timeout value. Pass 0’s into thoseparameters if not using the options.

SendMessage$9${WM_CLOSE} 0 0

;It is recommended to sleep a bit after a SendMessage() to let Windows

;cleaneverything up.

Sleep 1000

;Ifsomething went wrong NSIS will have thrown an exception.

;IfErrors()checks for an exception and branches the code execution base

;on theresult. In thiscase if there was an error then take the

Nullsoft Scriptable Install System Written In

;window handlevariable off of the stack and be done.

;If there noerrors the files will be installed.

IfErrorsdone installMaxFiles

installMaxFiles:

<File installationlines go here>

;This subroutineis put last so that, no matter what, the stack will be ;cleaned up beforeexecution moves on to the rest of the installer.

Done:

Pop$9

In this example the installation is skipped if Max isn’tclosed. Alternatively you could just inform the user that Max will have to bere-started after installation and proceed to install the files. Anothervariation would be to have the Yes/No dialog be a “Yes/No/I’ll close it myself”dialog and let the user have the option of an automatic closure or a manualone, so they can save their work.

Conclusion

The transition from mzp.run files to a NSIS installer executableisn’t impossibly hard but it is a different way of doing things. With HM NISEdit and the excellent NSIS documentation you should be able to pick up NSIS ina matter of hours. The NSIS documentation, website,and codearchive all provide excellent information and instruction on how toproperly use NSIS.

While I am not advocating or pushing for the wholesalerejection of .MZP files I am aware of the limitations of them. In talking withother members of the MAXScript community I know that I am not the only one whohas wanted a more robust installer system. NSIS, while not perfect, providesmuch better installation tools for MAXScripters.

Remarks

NSIS (Nullsoft Scriptable Install System) is a professional open source system to create Windows installers. It is designed to be as small and flexible as possible and is therefore very suitable for internet distribution.

Being a user's first experience with your product, a stable and reliable installer is an important component of succesful software. With NSIS you can create such installers that are capable of doing everything that is needed to setup your software.

NSIS is script-based and allows you to create the logic to handle even the most complex installation tasks. Many plug-ins and scripts are already available: you can create web installers, communicate with Windows and other software components, install or update shared components and more.

--> Taken from: https://sourceforge.net/projects/nsis/

Versions

Hello World!

Code, to be saved in „helloworld.nsi“:

Compile it with:

Nullsoft Install System V2.46

Installation or Setup

Nullsoft Installer Wizard

NSIS installer can be downloaded from http://nsis.sourceforge.net/Download. An exe of 1.6 MB will be downloaded. You can install it using the wizard. While installing there are options to install