Troubleshooting Inno Setup nLite Addons: Common Errors and Fixes

Packaging a nLite Addon with Inno Setup — Best Practices

Overview

Packaging a nLite addon with Inno Setup produces a single, reliable installer that creates the correct folder structure and addon metadata for nLite integration. This guide gives a concise, practical workflow and best practices so your addon installs cleanly, is easy to maintain, and works with nLite’s addon system.

1. Choose a clear addon structure

• Root folder: name it with a short, descriptive identifier (no spaces).
• Required files:
  • addon’s main files (drivers, registry tweaks, apps) in logical subfolders (e.g., files\bin, files\drivers).
  • addon.inf — the addon descriptor (must match nLite format).
  • images\ (optional) — small preview and icon images used by nLite.
• Keep filenames short and Windows-compatible (ASCII, avoid special chars).

2. Prepare addon.inf correctly

• Ensure addon.inf contains correct sections: [AddOn], [Files], [Files.Source], [Uninstall], etc., per nLite’s spec.
• Use relative paths referencing the addon root. Example line: Files\bin\example.exe,system32\example.exe
• Validate encoding: save addon.inf as ANSI or UTF‑8 without BOM if nLite requires ANSI.

3. Use Inno Setup to reproduce the addon layout

• Target location: install into a temporary directory matching nLite’s addon root (e.g., {tmp}\MyAddon\ ).
• Script basics:
  • Set AppName/AppVersion for your own use; do not attempt to write into nLite program files.
  • Use Source: “src*”; DestDir: “{tmp}{#MyAddonDir}” to mirror folder structure.
  • After files are installed to the temp folder, create a single ZIP or folder ready for user to copy into nLite’s addons directory.
• Example actions:
  • Files section — copy all addon files into {tmp}\MyAddon.
  • Code/Run section — optionally create an output .7z/.zip using a bundled command-line archiver (e.g., 7z.exe) included under license, or invoke Windows compression via PowerShell. Prefer creating an uncompressed folder unless the user prefers a packaged archive.

4. Keep installer minimal and user-friendly

• Provide clear prompts: destination (default to Desktop or temp), license (if needed), and a final message explaining where the addon was created and how to install it into nLite (copy folder or .zip into nLite’s addons folder).
• Do not modify system-wide nLite configuration automatically—leave copying into nLite’s directory as an explicit user step to avoid permission and versioning issues.

5. Handle permissions and environment variability

• Use PrivilegesRequired lowest necessary (typically none) if only writing into temp or user folders. If archive creation requires elevated rights, request elevation only for that step.
• Detect and include required runtimes or scripts (e.g., include a small powersehll wrapper if relying on that) or fail gracefully with instructions.

6. Versioning and metadata

• Embed a clear version (semver or date-based) into the addon folder name and addon.inf.
• Include a README.txt with changelog, author, and installation steps (copy or extract to nLite addons folder).

7. Testing checklist

• Verify folder layout is identical to a manual, working addon when installed to temp.
• Test with multiple Windows versions nLite supports.
• Test both folder and archive installation methods (copy folder vs. extract zip into addons).
• Validate addon.inf parsing by nLite (open nLite and ensure the addon appears and is selectable).

8. Error handling & troubleshooting tips

• Provide meaningful error messages if archive creation fails (missing compressor, permission denied).
• If files are blocked by Windows (SmartScreen), include instructions to unblock via file properties.
• Recommend running nLite as admin if users encounter access errors when copying into Program Files or protected locations.

9. Distribution considerations

• Digitally sign your installer to increase user trust and avoid Windows warnings.
• If distributing via the web, offer both folder (.zip) and installer (.exe) packages and clearly label checksums (SHA‑256).

10. Example Inno Setup snippet (concept)

• Copy files to temp addon folder, then run a command to create zip (replace with your chosen compressor):

[Files]Source: “dist*”; DestDir: “{tmp}\MyAddon”; Flags: recursesubdirs createallsubdirs [Run]Filename: “{cmd}”; Parameters: “/C “”{tmp}\7z.exe a -tzip “”{tmp}\MyAddon.zip”” “”{tmp}\MyAddon*”“”“”; Flags: runhidden

Final checklist (quick)

• Correct addon.inf and relative paths ✔
• Clean folder structure with README and images ✔
• Minimal, clear Inno Setup installer that places files into temp and optionally archives ✔
• Tests on target Windows versions and with nLite ✔
• Signed installer and checksums for distribution ✔

Follow these best practices to produce reliable, maintainable nLite addons packaged with Inno Setup.