sega 500 content distribution. the nsis installer jeff “ezeikeil” giles [email protected]...

Sega 500

Content Distribution.

The NSIS Installer

Jeff “Ezeikeil” [email protected]://gamestudies.cdis.org/~jgiles

mailto:[email protected]

http://gamestudies.cdis.org/~jgiles

Intro

We’ve spent a lot of time so far developing content of UT2003 and even looked at methods to distribute them using UMods.

And we saw that the UMods installer has it’s place in the world. Great for small mods. But limited in what you can do.

Today’s Goal

Which brings us to the following question.

“What other options do we have to deliver our mods to the world?”

Have no fear there are lots of options out there.

Today’s Goal

But today, we’re only going to look at one. The NSIS installer by Nullsoft.

Simply because not only is it an incredibly powerful tool, but it’s also completely open source and free.

And Free==Good

The NSIS

You can get your download from http://www.nullsoft.com and is currently on version 2.0.

The beautiful thing is, it’s also rather well documented.

http://www.nullsoft.com/

The NSIS

PLUS there are forums!

http://forums.winamp.com/forumdisplay.php?forumid=65




The NSIS

Plus! There are some pretty good documents:

http://nsis.sourceforge.net/Docs/Contents.html



The NSIS

So what the heck is it then…Well, straight form the doc’s

“NSIS is a free scriptable win32 installer/uninstaller system that doesn't suck and isn't huge.”

Know what? They’re right. It doesn’t suck.

The NSIS

NSIS, which stands for "Nullsoft SuperPIMP Installation System" or "Nullsoft Scriptable Installation System" or whatever you want, is based on PIMP but is designed to be much more flexible.

The NSIS

NSIS creates installers that are capable of installing, uninstalling, setting system settings, extracting files, etc. Pretty much anything. All with the minimum of overhead.

They don't bother decompressing themselves three different times, telling the user to "please wait". They get to the point and get the job done.

The NSIS

Oh yeah, “PIMP” stands for : Plug-In Mini Packager” which was originally developed for distribution of WinAmp plug-ins.

Just some of what it can do! File extraction (with configurable overwrite parameters) File/directory copying, renaming, deletion DLL loading (ActiveX control registration/deregistration, extension DLL calling, etc) Executable execution (shell execute and wait options) Shortcut creation Registry key reading/setting/enumerating/deleting INI file reading/writing Generic text file reading/writing Directory scanning Powerful string and integer manipulation Window finding based on class name or title (for is-application-running detection) Window message sending. User interaction with MessageBox. Branching, comparisons, etc. Error checking. Reboot support, including delete or rename on reboot Installer behaviour commands (such as show/hide/wait/etc) User functions in script Callback functions that let you customize the way the installer behaves from script. Macros in script

The NSIS

Yeah that’s a lot

And did I mention it’s free?

So why Should we us it?

You’ve no doubt seen one before…I assume everyone has seen Winamp

There’s some big boys in the industry who use it too: http://www.nullsoft.com/free/nsis/users.html

http://www.nullsoft.com/free/nsis/users.html

http://www.nullsoft.com/free/nsis/users.html


Well, power and flexibility aside, it looks and feels really professional.

This is just one of the demo’s


In addition having a good install package makes it much easier for the “not so computer savvy” to enjoy your game.

By not forcing the user to play with file locations and config settings we are in essence providing a form idiot proofing.


Here the only caveat to it’s freeness…the License agreement:


Copyright (C) 1999-2002 Nullsoft, Inc. This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages arising from the use of this software. Permission is granted to anyone to use this software for any purpose, including commercial applications, and to alter it and redistribute it freely, subject to the following restrictions:

1. The origin of this software must not be misrepresented; you must not claim that you wrote the original software. If you use this software in a product, an acknowledgment in the product documentation would be appreciated but is not required.

2. Altered source versions must be plainly marked as such, and must not be misrepresented as being the original software.

3. This notice may not be removed or altered from any source distribution.


Yes that’s all of it!

It’s not even in legalize. Gota like that!

So, ‘nuff talk, lets install stuff.

The Uber Simple Installer

As always, starting simple, we’re going to script an installer that installs a copy of notepad to the desktop.

Nothing fancy… Start by creating a text file and renaming it to *.nsi and make sure you’ve installed the NSIS package.


What are the bits we need?

For scripting tools…well…notepad.

And knowledge of 6 items: InstallDir, Section, SectionEnd, the “#”and “;”,

Outfile and it’s name.


InstallDir Sets the default installation directory is. Functionally, this is just a string.

Outfile Specifies the output file that the MakeNSIS

should write the installer to. This is just the file that MakeNSIS writes, it

doesn't affect the contents of the installer.


Name Sets the name of the installer. The name is

usually simply the product name such as 'MyApp' or 'CrapSoft MyApp'

Section Each NSIS installer contains one or more

Sections. Each These sections are created, modified, and ended with the following commands.


Each section contains zero or more instructions.

Sections are executed in order by the resulting installer, and if ComponentText is set, the user will have the option of disabling/enabling each section.

If a section's name is 'Uninstall', then it is a special Uninstall Section.


The Section Keyword begins and opens a new section. If section_name is empty, omitted, or begins with a -, then it is a required section and the user will not see it, nor have the option of disabling it.

If the section name begins with a !, the section will be displayed as bold. If /e is present, the sub sections of the section will be expanded by default.


SectionEnd This command closes the current open

section.

; and # operators Function as comments in script. Functionally

the same as // in C++


Right, so here’s the script

Name "A Simple Installer by Eze"OutFile "SimpleInstall.exe"

InstallDir "$DESKTOP"

Section "INSTALLING STUFF"

SetOutPath $INSTDIRFile "c:\Windows\notepad.exe"

SectionEnd

What appears in the Dialogue boxes title bar

The outputed installer file name






SectionEnd

The windows desktop directory.This is dependant on which user is logged in

The Section declaration and it name. The name is actually ignored. More for our benefit.






SectionEnd

Where to put our file when the installer is run.

What file and where to get it when the installer is compiled

Close the section


That’s it…No Fuss, no muss.

Give it a run, here’s what we get.

But…erm…how do we compile it?


Well, NullSoft was really clever about this and provided us with 2 options once the NSIS is installed on your box.

The option is to run the first is to MakeNSIS.exe file and drag you shiny new *.nsi file onto it.


Or you can right click option your *.nsi file and select Compile NSI from the list.


Now when you run your installer.exe or test it via the MakeNSIS, this is what our script yields.


Note: I’ve hit the show details button

Notepad to my desktop

Another Simple Installer

Well, that was pretty straight forward, So lets add some functionality.

The ability to define the install path and include a licensing agreement.


Surprisingly, this is really simple to do.

All that’s required is the addition of 3 lines and a text file (the licence agreement).


We’re just going to expand on the previous script by inserting the new lines here.





SectionEnd


LicenceText Specifies a string that is above the license

text. If this is omitted the license text will not be

displayed. If button_text is specified, it will override the default button text of "I Agree".


LicenceData Specifies a text file or a RTF file to use for the

license that the user can read. Omit this to not have a license displayed. Note that the file must be in the evil DOS text format (\r\n, yeah!)

If you make your license file a RTF file it is recommended you edit it with WordPad and not MS Word. Using WordPad will result in a much smaller file.


DirText Specifies a string that is above the directory

selection area. If this command is not specified, or no parameter is specified, then the directory page is never visible to the user (even if DirShow show is specified).

This is required to display the browse window.


The added script

LicenseText "I Own your soul!!!"LicenseData "Ownage.txt"DirText "This will install the very simple example1 on your \

computer. Choose a directory"

To extend a command over multiple lines use the “\”. Functions like an end of line.


What we get

And we can now install anywhere we want.

Simple Installer

Ok, that’s handy, turning it up a notch. Lets give the user the power to influence some of the install options and start changing how it looks.

Once again, by expanding on the above script.

Simple Installer

Starting with changing the icon. Once again this is really simple.

Icon Sets the icon of the installer. Every icon in the

icon file will be included in the installer. The path to the Icon to be used is defined

here.

Simple Installer

We’re also going to have it always show the install details.

ShowInstDetails Sets whether or not the details of the install are

shown. Can be 'hide' to hide the details by default, allowing the user to view them, or 'show' to show them by default, or 'nevershow', to prevent the user from ever seeing them. Note that sections can override this using SetDetailsView.

Simple Installer

These are going to be added to the top of the file, here.

Name "A Simple Installer by Eze"OutFile "Note.exe"Icon "C:\UT2003\Help\Unreal.ico"ShowInstDetails "show"


LicenseText "I Own your soul”

Simple Installer

Now, this is where we get a bit hairy. We’re going to give the use the option of installing a shortcut to the new file on the desktop.

We’re also going to force the installer to create a folder to put our notepad in.

Simple Installer

Although not required by the installer, I find it easier to manage my NSI script if I break it up into sections that perform specific actions.

To that effect, lets create a “Create Shortcuts” section.

Simple Installer

Just create a new section immediately below the old one.Section "INSTALLING STUFF"


SectionEnd ;

Section "Shortcuts"SetOutPath $DESKTOP ;where to install

CreateShortCut "$DESKTOP\GOON.lnk“ \ "$INSTDIR\Goober\notepad.exe" SectionEnd ;

Simple Installer

CreateShortCut Creates a shortcut 'link.lnk' that links to

'target.file', with optional parameters 'parameters'. The icon used for the shortcut is 'icon.file,icon_index_number'; for default icon settings use empty strings for both icon.file and icon_index_number. start_options should be one of: SW_SHOWNORMAL, SW_SHOWMAXIMIZED, SW_SHOWMINIMIZED, or an empty string.

Simple Installer

There’s lots of additional stuff that the CreateShortCut command will do, such as hot keys and what not. But I leave that to you to explore.

Simple Installer

Section "Shortcuts"SetOutPath $DESKTOP ;where to install

CreateShortCut "$DESKTOP\GOON.lnk“ \ "$INSTDIR\Goober\notepad.exe" SectionEnd ;

The Shortcut itself

What it’s linked to

Where to put it

Simple Installer

So how the heck to we provide the user the option of installing the shortcut.

The method I’m about to show you is one possible way, not the best. This method is intended to introduce to the dialogue boxes in NSIS.

Simple Installer

That’s right, the NSIS system gives us popup dialogue boxes which we can use to gather information.

Here, I’m going to create a simple Yes/No dialogue.

Simple Installer

MessageBox MB_YESNO "Create shortcuts?" IDNO NOShort CreateShortCut "$DESKTOP\GOON.lnk“ \

"$INSTDIR\Goober\notepad.exe" NOShort:

Message box textWhat kind of message box

The condition

The goto

Simple Installer

Functionally, this works exactly like a goto statement.

If IDNO is pressed, jump to NOShort. Otherwise continue.

Simple Installer

What we get is:

A new Icon for our exe…

Which also appear in our installer…

Simple Installer

And a functional option for the user to have the shortcuts installed on the desktop at their discretion.

More Installer Power

And yeah, another example since we’re not even scratching the surface of what the NSIS can do.

This time around, we’re going to add multi file support, run a file from the installer and create a simple function.


What’s that? A Function? Bully you say!

No really, Functions are similar to Sections in that

they contain zero or more instructions. Functions are not called by the installer directly, instead they are called from Sections using the Call instruction (Note: there are some special Callback Functions that can be called by the installer directly).


Functions must be declared outside of Sections or other Functions.

Function names beginning with "." (e.g. ".Whatever") are generally reserved for callback functions.

Function names beginning with "un." are functions that will be generated in the Uninstaller. Hence, normal install Sections and functions cannot call uninstall functions, and the Uninstall Section and uninstall functions cannot call normal functions.


The NSIS also supports Callback functions which have special names, that will be called by the installer at certain points in the install.

But these are a story for another day.


The function we’re going to add is simple going to change the color of the text.

Declare a function just like you would a section.


Function SwapColor

GetDlgItem $R0 $HWNDPARENT 1028 SetStaticBkColor $R0 0xFFFFFFFF

FunctionEnd

Name

Color in Hex

the ID of the brandingtext control

Variable


Variables User variables (set via StrCpy, ReadRegStr,

ReadINIStr, etc, and use like any other variable).

It is recommended (but not required) that you use $R1-$R9 as local registers, and $0-$9 as global values.

Note that any function that lets you specify one of these variables as an output, can use $INSTDIR or $OUTDIR as well (but has different implications).


SetStaticBkColor Sets a background color for a static control.

Use GetDlgItem to get the handle (HWND) of the static control.

GetDlgItem Retrieves the handle of a control identified by

item_id in the specified dialog box dialog and stores it in a register. In this case $r0


And to call this function I simply add it to the shortcut section

Section "Shortcuts"

Call SwapColor


And to get it to run our txt file in note pad, we work a little bit more magic.

But there are a few Items to know about first…


GetTempFileName Assign to the user variable $x, the name of a

temporary file. The file will have been created, so you can then overwrite it with whatever you please.

The name of the temporary file is guaranteed to be unique. Delete the file when done with it.


File /oname The file command adds file(s) to be extracted

to the current output path ($OUTDIR) and has lots of other functionality.

But for oname, If the /oname=X switch is used, the output name becomes $OUTDIR\X. When using the /oname= switch, only one file can be specified, and the file name can contain variables (or a fully qualified path, e.g. $SYSDIR\whatever.dll).


ExecWait Execute the specified program and wait for the

executed process to quit. If no output variable is specified ExecWait sets the

error flag if the program executed returns a nonzero error code, or if there is an error.

If an output variable is specified, ExecWait sets the variable with the exit code (and only sets the error flag if an error occurs; if an error occurs the contents of the user variable are undefined).


Delete Delete file (which can be a file or wildcard, but

should be specified with a full path) from the target system.


And here’s how we put it all together in the shortcuts section

GetTempFileName $R0File /oname=$R0 "C:\Documents and Settings\Ezeikel…<SNIP>…sson 44\ownage.txt" ExecWait '"$INSTDIR\Goober\notepad.exe" "$R0"'Delete $R0


GetTempFileName $R0File /oname=$R0 "C:\Documents and Settings\Ezeikeil…<SNIP>…sson 44\ownage.txt" ExecWait '"$INSTDIR\Goober\notepad.exe" "$R0"'Delete $R0

Get our unique file to work with The text to open and Stuff into $R0

Run notepad on $R0

Clean it up when done


Putting it all together into one sectionSection "Shortcuts"

Call SwapColor

SetOutPath $DESKTOP ;where to install MessageBox MB_YESNO "Create shortcuts?" IDNO NOShortCreateShortCut "$DESKTOP\GOON.lnk“\ "$INSTDIR\Goober\notepad.exe" NOShort:

GetTempFileName $R0File /oname=$R0 "C:\Documents and Settings\....Ez<SNIP>…44\ownage.txt" ExecWait '"$INSTDIR\Goober\notepad.exe" "$R0"'Delete $R0

SectionEnd ;


An when run…we get:

A function which changes thetext properties when run.

Note: for this demo there is a windows redraw issue. Just grab the “create shortcuts” window and move it over the text to see the colour change.


And the last thing the installer does before exiting is open our ownage.txt file.

End of the Road.

That’s a pretty good introduction to the wonderful world of NSIS install systems.

Tomorrow we’ll unlock more of its power by playing with the registry, editing ini files and uninstall options.