nsis-plugin

Write NSIS plug-ins in Rust.

Description

Build NSIS plug-ins without writing C. The crate takes care of the details that usually go wrong:

• Long strings: buffers are sized at runtime, so one DLL works with both stock and long-string NSIS builds.
• Safe copies: writes into the installer are bounded. Truncation is reported as an error.
• Errors: returning Err sets the NSIS error flag, which IfErrors can check.
• NSIS integers: 0x2a, 052 and garbage input are parsed the way NSIS parses them.
• Testable: test your plug-in on macOS and Linux with a fake installer.

#![cfg_attr(target_os = "windows", no_std)]
extern crate alloc;

use nsis_plugin::{Nsis, Result, nsis_fn, nsis_plugin};

nsis_plugin!();

nsis_fn! {
	fn Add(nsis: &mut Nsis) -> Result<()> {
		let b = nsis.stack.pop_int()?;
		let a = nsis.stack.pop_int()?;
		nsis.stack.push_int(a + b)?;
		Ok(())
	}
}

The function is called through the DLL's name. If your crate is example, it builds example.dll:

Push 2
Push 40
example::Add
Pop $0   ; 42

Installation

Generate a new plug-in from the template:

cargo generate --git https://github.com/idleberg/nsis-plugin template

The template asks for an SPDX license identifier. Apache-2.0 is the default; other texts are downloaded when you generate.

To add the crate to an existing project instead:

cargo add nsis-plugin

Usage

Building

Tooling is managed with mise.

mise install
mise run dist   # build all DLLs into dist/Plugins/
mise run size   # check DLL sizes against their budgets

NSIS needs one DLL per installer type:

The two opt-in variants are not built unless you ask for them:

cargo xtask dist --variant x86-ansi
cargo xtask dist --variant arm64-unicode --toolchain msvc

To build them every time, add them to variants in dist.toml.

[!NOTE] NSIS 3 defaults to Unicode, so you only need x86-ansi for installers that set Unicode false. ARM64 has no NSIS release to test against yet and needs the MSVC toolchain.

Building on macOS and Linux

Cross-compile with MinGW and test with Wine, no Windows machine required.

brew install mingw-w64 makensis
mise run dist

MSVC is what you should ship with. It runs natively on Windows, or via cargo-xwin elsewhere.

Testing

Unit tests run on your host and call the exported function like an installer would.

#[test]
fn adds_numbers() {
	let mut inst = TestInstaller::stock();
	inst.push("052");   // octal 42
	inst.push("0x2a");  // hex 42
	inst.call(Add);
	assert_eq!(inst.pop().as_deref(), Some("84"));
}

Run mise run smoke to compile a real installer and run it under Wine. To test with long strings (8192 characters), build a matching makensis first:

mise run nsis:longstring
mise run smoke:long

Windows versions

The MSVC builds only import KERNEL32, so they add no minimum Windows version of their own. The 32-bit MinGW builds also need the Universal C Runtime (Windows 10, or the redistributable on older systems).

DLL size

The template is configured for small DLLs. The hello example is 12 KB for amd64-unicode and about 50 KB for x86-unicode with MinGW. cargo xtask dist fails when a DLL exceeds its budget in dist.toml.

Non-goals

This crate does not wrap Win32 (use windows-sys), custom pages or .nsh wrappers.

License

This work is licensed under either of MIT or Apache-2.0, at your option.