Creating Installers

From MoHWiki

This is what the finished installer will look like.
This is what the finished installer will look like.
This is what the finished installer will look like.
This is what the finished installer will look like.

This tutorial will explain how to create a basic Installer / Uninstaller for a MoHAA mod or similar. On the left and right are screenshots of the finished installer & uninstaller.

To do this we are going to use NSIS (Nullsoft Scriptable Install System), which is a powerful, free, open source program used to create instilation programs. It is used to create the installers for Firefox, Winamp, OpenOffice.org and many other programs.

Before we get going I should add that this is a rather heavyweight solution for a simple one pk3 mod. It is best to reserve an installer for larger multi file mods and total conversions, or for situations where the mods target audience are not experienced enough to manually install a mod. You may want to consider offering the mod in plain archive form so that people don't have to accept/trust executables from strangers.

Contents

[edit] Installing

First you need to install NSIS, so visit their site and install the latest version: http://nsis.sourceforge.net

Screenshot of Notepad2 with syntax highlighting for NSIS scripts.
Screenshot of Notepad2 with syntax highlighting for NSIS scripts.

I also recommend getting a text editor with syntax highlighting for .nsi files(NSIS scripts). One such program is Notepad2. Now for some reason the .nsi syntax highlighting support was removed a few versions ago, but someone has modded it to add it back in. You can download it here.

[edit] Installer Artwork

You can customize your installer with a small banner (150x57 px) and a larger image shown on the left of some screens (164x314 px); as well as a custom icon for the installer.

NSIS comes with a few examples which you can find at:

  • C:\Program Files\NSIS\Contrib\Graphics

These are the ones I made. I cropped an image from the collection of images from MoH:PA directors edition.

Installer top banner
Installer top banner
Uninnstaller top banner
Uninnstaller top banner
Installer side image
Installer side image
Uninstaller side image
Uninstaller side image
Note — your images have to be bitmaps (.bmp). Other file formats are not supported.

The uninstaller images use some of the example images that come with NSIS. You can find the uninstall image .PSDs in the files archive at the end of this article. I didn't keep the PSDs of the installer images, but they are quite simple. Just cropped and resized with a 1px line down the right of the side image, and a white - transparent gradient on the banner. Feel free to re-use these images if you don't want to make your own.

I didn't bother to make an icon, I just used two of the ones included with NSIS. Icons are quite simple to make, you need a 32x32 image, and save it as an .ico. Note, in XP .ico files do not support full alpha channels, they are like gifs. The GIMP has native support for saving .ico files, for Photoshop you need a plugin.

[edit] Getting Started

You need to setup a folder to hold all the stuff needed to compile your installer. Download the zip archive included at the bottom of this article and use that. Unzip it to a folder somewhere.

NSIS (Nullsoft Scriptable Install System) installers are made by writing scripts which the compiler reads and creates a stand alone exe which contains everything someone needs to install your Mod or whatever it is you are installing. To start things off try compiling the .nsi script I made (it is based on the Modern UI WelcomeFinish.nsi example script).

Right click on "Generic MoHAA Mod.nsi" and you should see some options for NSIS. There will be an option to compile the script, or to choose a compressor. You can ignore the compressor option, at least until it is all working properly and you want to optimise the filesize of your installer. Anyway, chose compile. A window will pop up with a console showing what it is doing as it compiles. After a while (shouldn't take long as it's only a small installer in the example) it should finish, and dump an exe file in the same folder as the script.

The output in the console window should be something like this: 

MakeNSIS v2.28 - Copyright 1995-2007 Contributors
See the file COPYING for license details.
Credits can be found in the Users Manual.

Processing plugin dlls: "C:\Program Files\NSIS\Plugins\*.dll"
 - AdvSplash::show
 - Banner::destroy
 - Banner::getWindow
 - Banner::show
 - BgImage::AddImage
 - BgImage::AddText
 - BgImage::Clear
 - BgImage::Destroy
 - BgImage::Redraw
 - BgImage::SetBg
 - BgImage::SetReturn
 - BgImage::Sound
 - Dialer::AttemptConnect
 - Dialer::AutodialHangup
 - Dialer::AutodialOnline
 - Dialer::AutodialUnattended
 - Dialer::GetConnectedState
 - InstallOptions::dialog
 - InstallOptions::initDialog
 - InstallOptions::show
 - LangDLL::LangDialog
 - Math::Script
 - NSISdl::download
 - NSISdl::download_quiet
 - Splash::show
 - StartMenu::Init
 - StartMenu::Select
 - StartMenu::Show
 - System::Alloc
 - System::Call
 - System::Copy
 - System::Free
 - System::Get
 - System::Int64Op
 - System::Store
 - TypeLib::GetLibVersion
 - TypeLib::Register
 - TypeLib::UnRegister
 - UserInfo::GetAccountType
 - UserInfo::GetName
 - UserInfo::GetOriginalAccountType
 - VPatch::vpatchfile
 - nsExec::Exec
 - nsExec::ExecToLog
 - nsExec::ExecToStack

SetCompressor: /FINAL bzip2
Processing config: 
!define: "MUI_INSERT_NSISCONF"=""

Changing directory to: "E:\Documents and Settings\Hal\My Documents\NSIS\TMT tutorial"

Processing script file: "E:\Documents and Settings\Hal\My Documents\NSIS\TMT tutorial\Generic MoHAA Mod.nsi"
!include: "C:\Program Files\NSIS\Include\MUI.nsh"
!include: "C:\Program Files\NSIS\Contrib\Modern UI\System.nsh"
NSIS Modern User Interface version 1.78 - © 2002-2007 Joost Verburg (C:\Program Files\NSIS\Contrib\Modern UI\System.nsh:11)
!define: "MUI_VERBOSE"="3"
!include: closed: "C:\Program Files\NSIS\Contrib\Modern UI\System.nsh"
!include: closed: "C:\Program Files\NSIS\Include\MUI.nsh"
Name: "Generic MoH:AA Mod"
OutFile: "Generic MoHAA Mod SETUP.exe"
InstallDir: "$PROGRAMFILES\EA GAMES\MOHAA\main\"
!define: "MUI_HEADERIMAGE"=""
!define: "MUI_HEADERIMAGE_BITMAP"="moh_header.bmp"
!define: "MUI_HEADERIMAGE_UNBITMAP"="un_moh_header.bmp"
!define: "MUI_ABORTWARNING"=""
!define: "MUI_WELCOMEFINISHPAGE_BITMAP"="moh_wizard.bmp"
!define: "MUI_UNWELCOMEFINISHPAGE_BITMAP"="un_moh_wizard.bmp"
!define: "MUI_FINISHPAGE_LINK"="ModTheater.com"
!define: "MUI_FINISHPAGE_LINK_LOCATION"="http://www.modtheater.com"
!define: "MUI_FINISHPAGE_SHOWREADME"="$TEMP\Generic MoHAA Mod README.txt"
!define: "MUI_ICON"="arrow2-install.ico"
!define: "MUI_UNICON"="arrow2-uninstall.ico"
!insertmacro: MUI_PAGE_WELCOME
!insertmacro: end of MUI_PAGE_WELCOME
!insertmacro: MUI_PAGE_LICENSE
!insertmacro: end of MUI_PAGE_LICENSE
!insertmacro: MUI_PAGE_COMPONENTS
!insertmacro: end of MUI_PAGE_COMPONENTS
!insertmacro: MUI_PAGE_DIRECTORY
!insertmacro: end of MUI_PAGE_DIRECTORY
!insertmacro: MUI_PAGE_INSTFILES
!insertmacro: end of MUI_PAGE_INSTFILES
!insertmacro: MUI_PAGE_FINISH
!insertmacro: end of MUI_PAGE_FINISH
!insertmacro: MUI_UNPAGE_WELCOME
!insertmacro: end of MUI_UNPAGE_WELCOME
!insertmacro: MUI_UNPAGE_CONFIRM
!insertmacro: end of MUI_UNPAGE_CONFIRM
!insertmacro: MUI_UNPAGE_INSTFILES
!insertmacro: end of MUI_UNPAGE_INSTFILES
!insertmacro: MUI_UNPAGE_FINISH
!insertmacro: end of MUI_UNPAGE_FINISH
!insertmacro: MUI_LANGUAGE
!insertmacro: end of MUI_LANGUAGE
Section: "!Generic MoH:AA Mod" ->(mainPK3)
SetOutPath: "$INSTDIR"
File: "Generic MoHAA Mod.pk3" [compress] 22665 bytes
WriteUninstaller: "$INSTDIR\Uninstall Generic MoHAA Mod.exe"
SectionEnd
Section: "Documentation" ->(docs)
SetOutPath: "$INSTDIR\docs"
CreateDirectory: "$INSTDIR\docs"
File: "Generic MoHAA Mod README.txt" [compress] 20 bytes
SectionEnd
Section: "-Readme"
SetOutPath: "$TEMP\"
File: "Generic MoHAA Mod README.txt" [compress] 0/20 bytes
SectionEnd
LangString: "DESC_mainPK3" 1033 "PK3 files for the Generic MoH:AA Mod (required)."
LangString: "DESC_docs" 1033 "Documentation for the Generic MoH:AA Mod."
!insertmacro: MUI_FUNCTION_DESCRIPTION_BEGIN
!insertmacro: end of MUI_FUNCTION_DESCRIPTION_BEGIN
!insertmacro: MUI_DESCRIPTION_TEXT
!insertmacro: end of MUI_DESCRIPTION_TEXT
!insertmacro: MUI_DESCRIPTION_TEXT
!insertmacro: end of MUI_DESCRIPTION_TEXT
!insertmacro: MUI_FUNCTION_DESCRIPTION_END
!insertmacro: end of MUI_FUNCTION_DESCRIPTION_END
Section: "Uninstall"
Delete: "$INSTDIR\Uninstall Generic MoHAA Mod.exe"
Delete: "$INSTDIR\Generic MoHAA Mod.pk3"
Delete: "$INSTDIR\docs\Generic MoHAA Mod README.txt"
RMDir: "$INSTDIR\docs"
SectionEnd

Processed 1 file, 1 command line command, writing output:
Adding plug-ins initializing function... Done!
Processing pages... Done!
Removing unused resources... Done!
Generating language tables... Done!
Generating uninstaller... Done!

Output: "E:\Documents and Settings\Hal\My Documents\NSIS\TMT tutorial\Generic MoHAA Mod SETUP.exe"
Install: 7 pages (448 bytes), 3 sections (1 required) (3144 bytes), 296 instructions (8288 bytes), 165 strings (23844 bytes), 1 language table (366 bytes).
Uninstall: 5 pages (320 bytes), 
1 section (1048 bytes), 219 instructions (6132 bytes), 131 strings (2229 bytes), 1 language table (290 bytes).
Datablock optimizer saved 8475 bytes (~2.5%).

Using bzip2 compression.

EXE header size:               39424 / 34304 bytes
Install code:                   9416 / 36490 bytes
Install data:                 146768 / 231992 bytes
Uninstall code+data:          138516 / 141825 bytes
CRC (0x7CF26634):                  4 / 4 bytes

Total size:                   334128 / 444615 bytes (75.1%)

You can then try running the installer. It will put the uninstaller exe in the mohaa\main folder to avoid loosing it in the start menu or something unnecessary like that.

Then run the uninstaller to get rid of the useless pk3 file and readme the installer creates.

[edit] Modifying the Script

Imo, the best way to learn this kind of thing is to start off my altering a script that already works, and see what changes. This avoids frustration trying to get something working before you fully understand it all.

Open up the "Generic MoHAA Mod.nsi" file in your text editor, preferably one with syntax highlighting for NSIS scripts as noted above.

Have a look through the file, it is relatively easy to see what is going on.

Ignore the "Include Modern UI" section, it just makes the installer use the nicer modern UI instead of the default basic one.

Next is the "General" section. Name is the name of the mod/program etc as it shows up in the menus of the installer. Outfile is the name of the installer exe the compiler creates. InstallDir is the default path that the installer will install to if another is not chosen.

$PROGRAMFILES is a variable for the program files folder, default is C:\Program Files\. Variables for system folders are used in many cases to maintain compatibility when the default paths are changed in Windows, and for username specific paths.

Next up is the "Interface Settings" section. These are all giving the compiler options to change the default settings. First there are some paths to the custom bitmap images to be used in the installer. The UNBITMAP ones are for the Uninstaller. MUI_FINISHPAGE_LINK is for the link on the final page of the installer. Set it to your website.

MUI_FINISHPAGE_SHOWREADME is a path to a readme text file. With this set there will be an option on the final page to view the readme file you provide. Finaly there is the path to the icons for the exe files. Note that the paths can be absolute or relative, but I have used relative paths throughout this script for portability.

Next is the "Pages" section. Each of the lines makes a certain page apear in the installer. EG: 

!insertmacro MUI_PAGE_WELCOME
adds a welcome page to the installer. MUI stands for Modern UI.

Then there is the "Languages" section. There is only English in this script, but there is good support for loads of languages, which can be chosen by the user at the start of the install process.

Next is the "Installer Sections" section. This is a very important part. Each of these named sections is an installable component that the user can turn on or off before the install.

You can use this to have optional stuff like documentation that the user may not want to bother installing. A ! at the start of the name makes the name Bold in the installer. A - at the start of the name makes the section hidden in the installer, and the user can't turn it off.

SetOutPath is used to set the path that the files listed in the section are installed to. $INSTDIR is the base install path defined at the top of the script.

"File" adds a file to the section to be installed. With my limited testing it seems you can use wildcards or just define folders and everything in the folder will be included. However you have to name all the files individually in the uninstall section, unless you use some kind of consistent naming system allowing you to use wildcards to delete the files.

The "Descriptions" section is for defining descriptions for the installable sections to tell users what they are. They see the descriptions when hovering over the sections in the installer.

"Uninstall Sections" is just like the "Installer sections" section, but it defines what is removed when running the uninstall program.

I beleve $INSTDIR is taken as the current location of the uninstall exe unless you save the install path in the registry and retrieve it (which I have not done). This means if you move the uninstall exe out of the default folder it won't find the files to remove. It should be somewhat obvious while unisntallilng, as the folder it is uninstalling from is shown before comencing the uninstall.

Delete deletes the named file. RMDir deletes the named folder, but only if it is empty.

That concludes this tutorial. For further reading and more complex stuff check out the example scripts in

  • C:\Program Files\NSIS\Examples\Modern UI

&

  • C:\Program Files\NSIS\Examples\

Note that the example scripts in the Examples folder are for the basic UI, not the nicer modern one.

[edit] External Links

[edit] Attached Files

Retrieved from "http://mohwiki.com/Creating_Installers"
Personal tools
Online Users
Report bugs