Crate nsis_plugin

Expand description

Write NSIS plug-ins in Rust, with all four target variants building correctly by default.

#![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(())
    }
}

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

§What the wrapper is for

A plug-in export is a single C function with five arguments and a trailing ellipsis. The two facts that make it easy to get wrong:

string_size is a runtime parameter, the calling installer’s NSIS_MAX_STRLEN. Every buffer holding installer strings is sized from it, so long-string builds (/DNSIS_MAX_STRLEN=8192) work structurally rather than as a feature.
Stack nodes are GlobalAlloc’d and the caller frees on pop. Pushing a longer string than string_size is a heap overflow. Stack::push is bounded and reports Error::Truncated.

§The error flag

Returning Err from a nsis_fn! body sets exec_flags->exec_error, which is what IfErrors reads. ? on an empty stack therefore does the NSIS-native thing with no ceremony.

§Character width

Tchar is u16 under the default unicode feature and u8 under ansi; the two are mutually exclusive. The public API traffics in String/&str and converts at the boundary. 64-bit NSIS targets are always Unicode, so the build matrix is four combinations, not eight.

Re-exports§

pub use crate::error::Error;
pub use crate::error::Result;
pub use crate::raw::ExecFlags;
pub use crate::raw::ExtraParameters;
pub use crate::raw::Hmodule;
pub use crate::raw::Hwnd;
pub use crate::raw::NSISPIAPIVER_1_0;
pub use crate::raw::NSISPIAPIVER_CURR;
pub use crate::raw::NSPIM_GUIUNLOAD;
pub use crate::raw::NSPIM_UNLOAD;
pub use crate::raw::NsisPluginCallback;
pub use crate::raw::StackNode;

Modules§

error: The failure channel.
int: NSIS integer semantics, ported line-for-line from Contrib/ExDLL/pluginapi.c.
raw: Raw FFI declarations, transcribed from the NSIS 3.12 sources.
rt: The runtime pieces a no_std plug-in DLL needs in order to link at all.

Macros§

nsis_fn: Defines one or more plug-in exports.
nsis_plugin: Declares the crate to be an NSIS plug-in DLL. Invoke exactly once.
nsis_unload: Defines an NSPIM_UNLOAD callback, to be handed to Nsis::register_callback.

Structs§

Nsis: Everything a plug-in export receives, in one place.
Stack: Handle to the installer’s stack_t **.
Variables: Handle to the installer’s variables array.

Enums§

Var: A user variable, indexed exactly as the INST_* enum indexes it.

Constants§

VAR_COUNT: Number of user variables, i.e. __INST_LAST.

Type Aliases§

Tchar: The installer’s character type: u16 under unicode, u8 under ansi.