makensis

makensis

A TypeScript wrapper for makensis, the compiler for NSIS installers.

Prerequisites

Make sure that NSIS 3.06 (or later) is installed. If makensis isn't exposed to your PATH environment variable, you need to set pathToMakensis.

Windows

Install NSIS using the Windows Package Manager or Scoop:

# Windows Package Manager
$ winget install NSIS.NSIS

# Scoop
$ scoop install nsis/nsis

Alternatively, you can download the NSIS installer from SourceForge.

Linux

Install NSIS from your distribution's default package manager, for example:

# Debian
$ sudo apt-get install nsis

# Red Hat
$ sudo dnf install nsis

# Arch Linux
$ pacman -S nsis

macOS

Install NSIS using Homebrew or MacPorts:

# Homebrew
$ brew install nsis

# MacPorts
$ port install nsis

Nix

Open a Nix shell with NSIS installed:

$ nix-shell -p nsis

Installation

# NodeJS
npm install makensis

# Deno
deno add jsr:@idleberg/makensis

[!WARNING]
If you need to support a version of NSIS older than 3.06, you can use makensis@2 as it employs some useful workarounds.

Usage

Example usage in script:

import * as NSIS from "makensis";

const options = {
    verbose: 2,
    define: {
        SPECIAL_BUILD: true,
    },
};

try {
    const output = await NSIS.compile("path/to/installer.nsi", options);
    console.log("Compiler output:", output);
} catch (error) {
    console.error(error);
}

API

commandHelp

Usage: commandHelp(command?, options?, spawnOptions?)

Returns usage information for a specific command, or a list of all commands. Equivalent of the -CMDHELP switch.

compile

Usage: compile(script, options?, spawnOptions?)

Compiles specified script with MakeNSIS. The script can be omitted in favor of the preExecute / postExecute options.

headerInfo

Usage: headerInfo(options?, spawnOptions?)

Returns information about which options were used to compile MakeNSIS. Equivalent of the -HDRINFO switch.

license

Usage: license(options?, spawnOptions?)

Returns MakeNSIS software license. Equivalent of the -LICENSE switch.

nsisDir

Usage: nsisDir(options?, spawnOptions?)

Returns the path of ${NSISDIR}.

version

Usage: version(options?, spawnOptions?)

Returns version of MakeNSIS. Equivalent of the -VERSION switch.

Options

[!NOTE]
Some of these options are limited to NSIS v3 (see the changelog for details).

define

Type: Object

Defines symbols for the script [to value]. Equivalent of the -D switch.

Example

define: {
	SPECIAL_BUILD: true,
	LANGUAGE: "English"
}

env

Type: boolean

Enables support for special environment variables, that will be passed on to the script as definitions.

Example

# .env
NSIS_APP_ENVIRONMENT=development

# installer.nsi
!if ${NSIS_APP_ENVIRONMENT} == "development"
	DetailPrint "Valuable Debug Information"
!endif

inputCharset

Type: string

Specifies the codepage for files without a BOM (ACP|OEM|CP#|UTF8|UTF16<LE|BE>). Equivalent of the -INPUTCHARSET switch.

outputCharset

[!WARNING]
This option is only available on Windows.

Type: string

Specifies the codepage used by stdout when the output is redirected (ACP|OEM|CP#|UTF8[SIG]|UTF16<LE|BE>[BOM]). Equivalent of the -OUTPUTCHARSET switch.

json

Type: boolean

Returns output from makensis as an object

noCD

Type: boolean

Disables the current directory change to that of the .nsi file. Equivalent of the -NOCD switch.

noConfig

Type: boolean

Disables inclusion of <path to makensis.exe>/nsisconf.nsh. Equivalent of the -NOCONFIG switch.

pathToMakensis

Type: string

Specifies a custom path to makensis

pause

Type: boolean

Pauses after execution. Equivalent of the -PAUSE switch.

priority

[!WARNING]
This option is only available on Windows.

Type: integer

Sets the compiler process priority, where the value 5=realtime, 4=high, 3=above normal, 2=normal, 1=below normal, 0=idle. Equivalent of the -P switch.

strict

Type: boolean

Treat warnings as errors. Equivalent of the -WX switch.

ppo / safePPO

Type: boolean

Will only run the preprocessor and print the result to stdout. The safe version will not execute instructions like !appendfile or !system. !packhdr and !finalize are never executed. Equivalent of the -PPO / SAFEPPO switches.

preExecute

Type: string | string[]

Prepends script-commands to the script, can be passed as array or multiline-string. Equivalent of the -X switch when used before passing a script.

Example

preExecute: ["SetCompressor lzma", "SetCompressorDictSize 16"];

postExecute

Type: string | string[]

Appends commands to the script, can be passed as array or multiline-script. Equivalent of the -X switch when used after passing a script.

Example

postExecute: [`!echo "That's all Folks!"`];

rawArguments

Type: string[]

Specifies raw arguments for makensis.

[!IMPORTANT]
These will be added to the compiler arguments last and will hence overwrite any of the NSIS options above!

verbose

Type: integer

Verbosity where the value 4=all, 3=no script,2=no info, 1=no warnings, 0=none. Equivalent of the -V switch.

Callbacks

onData

Gives access to an object containing the current line, and whether it contains a warning of the path of the outfile.

onError

Gives access to an object containing the current line.

onExit

Gives access to an object containing the exit code, the full stdout and stderr, and the number of warnings.

Related

• atom-language-nsis - NSIS package for Atom/Pulsar
• vscode-nsis - NSIS package for Visual Studio Code

License

This work is licensed under The MIT License.