nsisunz

Introduction

nsisunz is a NSIS plugin which allows you to extract files from ZIP archives.

nsisunz is great when you use another NSIS plug-in named NSISdl to download a ZIP file from the internet. Download a small installer which lets the user choose the components he/she want to install and the installer downloads it (QuickTime Setup does this).

Note: nsisunz does not support password protected ZIP archives (encrypted).
To extract only a specific file from the archive use the "/file" option.

How to use

Setting it up

To see a great example of how to use the plug-in, check out the included example script.

You use the Unzip, UnzipToLog or the UnzipToStack function to extract files from a ZIP archive.

In my opinion the best way to describe things is by showing an example, so here is one:

InitPluginsDir
; Call plug-in. Push filename to ZIP first, and the dest. folder last.
nsisunz::UnzipToLog "$PLUGINSDIR\myzipfile.zip" "$INSTDIR"

; Always check result on stack
Pop $0
StrCmp $0 "success" ok
  DetailPrint "$0" ;print error message to log
ok:

; You can also use the "Unzip" function if you don't want to use the log.
; It is a lot quicker, and is preferred for large ZIP archives.
nsisunz::Unzip "$PLUGINSDIR\myzipfile.zip" "$INSTDIR"

The UnzipToStack function

The UnzipToStack function can be used instead of the UnzipToLog function if you want the extraction to be a lot faster when extracting from very large ZIP archives and still want to see the files extracted. This is how you use it: 

nsisunz::UnzipToStack "$PLUGINSDIR\myzipfile.zip" "$INSTDIR"
Pop $0
StrCmp $0 "success" ok
  DetailPrint "$0" ;print error message to log
  Goto skiplist
ok:

; Print out list of files extracted to log
next:
  Pop $0
  DetailPrint $0
StrCmp $0 "" 0 next ; pop strings until a blank one arrives

skiplist:

Extracting specific files

To extract only a specific file use the "/file" option like this: 

nsisunz::UnzipToLog /file "AnyPathInsideZIP/AFile.txt" "myzip.zip" "c:\myfiles"

The path is relative to the root of the ZIP archive so you don't have to prepend a slash ("/"). Furthermore the foldernames are extracted with the file so the example above creates a file named "c:\myfiles\AnyPathInsideZIP\AFile.txt". To avoid this use "/noextractpath" like this: 

nsisunz::UnzipToLog /noextractpath /file \
  "AnyPathInsideZIP/AFile.txt" "myzip.zip" "c:\myfiles"

Using nsisunz with NSISdl

To use NSISdl with nsisunz to download and extract a ZIP archive, do something like this:

InitPluginsDir
NSISdl::download http://www.domain.com/file "$PLUGINSDIR\localfile.zip"
Pop $R0 ;Get the return value
StrCmp $R0 "success" +3
  MessageBox MB_OK "Download failed: $R0"
  Quit

nsisunz::UnzipToLog "$PLUGINSDIR\localfile.zip" "$INSTDIR"
Pop $R0
StrCmp $R0 "success" +2
  DetailPrint "$R0" ;print error message to log

Options

These are the optional parameters you can specify when calling nsisunz.

/noextractpath This option makes the plug-in extract all files to the destination directory without regard to paths stored in ZIP file. Is often used in conjunction with "/file" to extract a single file from anywhere in an archive to a destination directory.
/file Extract a specific file. Filename must be specified as next parameter and must match a file in the ZIP including any subdirectories. If the file couldn't be found in the ZIP file, nsisunz pushes the string "File not found in ZIP file" on the stack.
/text Sets the format of the text used in the log to the next param. "%f" is replaced with the filename, "%c" is replaced with the compressed size and "%u" is replaced with the uncompressed size.

Return value

After you have called the DLL, nsisunz adds either "success" or a specific error message on the stack. This is the possible error messages:

  • Error opening ZIP file
  • Error opening output file(s)
  • Error writing output file(s)
  • Error extracting from ZIP file
  • File not found in ZIP file

Usually, you don't need to check this value, but you still have to remove it from the stack (have a look at the example above).

Reserve files

If you are using BZIP2 (solid) compression, it's important that files which are being extracted in init- or page functions function are located before other files in the data block, because this will make your installer faster.

If there are File commands in your sections or functions above the init- or page functions, add ReserveFile commands above your sections and functions:

ReserveFile "myzipfile.zip"
ReserveFile "${NSISDIR}\Plugins\nsisunz.dll"

Localization

Use the "/text" parameter to localize the text used by nsisunz for the log output. 

; Localized strings for use with nsisunz
; The "%f" in the string is replaced with the filename on run-time.
; "%c" and "%u" is replaced with compressed size and
; uncompressed size respectively. See example script.

LoadLanguageFile "${NSISDIR}\Contrib\Language files\english.nlf"
LoadLanguageFile "${NSISDIR}\Contrib\Language files\norwegian.nlf"

LangString nsisunz_text ${LANG_ENGLISH} "Extract: %f"
LangString nsisunz_text ${LANG_NORWEGIAN} "Pakk ut: %f"

Function .onInit
  nsisunz:: /text "" "$(nsisunz_text)"
FunctionEnd

Notes

The plug-in is compressed with UPX to make it smaller.
If you make changes to the source, re-compile and use UPX you may get this message:
upx: nsisunz.dll: CantPackException: file is possibly packed/protected (try --force)
I used the "--force" parameter as proposed, and without problems UPX reduced the size of nsisunz.dll from ~71 kb to 31,5 kb
The reason for why you get this message is that the source #include's "AggressiveOptimize.h" which makes the linker merge the code sections of the final executable. This makes UPX think it's already packed (which it kinda is). But by using the "--force" parameter, UPX may shrink it a lot more.
I hope people appreciate my struggles to keep the size of the plug-in small. If someone have any suggestions for making it even smaller I would like if someone sendt me an e-mail.

Contact

nsisunz is written by Saivert.
Homepage: http://saivert.inthegray.com/
E-mail: saivert@gmail.com

Version history

  • DLL version 1.0 (12/4/2004)
    • First public release!

Credits

Based on code in NSIS Zip2Exe
portions Copyright © 1999-2001 Miguel Garrido (mgarrido01@hotmail.com)
Uses ZLIB - Copyright © Mark Adler
ZIP format routines - Copyright © 1998 Gilles Vollant
Thanks to Tim Kosse for the LogMessage function, even though I could figure this out myself.
And thanks to Joost Verburg for the readme HTML page design.

License

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 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 distribution.