Troubleshooting QSetup: Common Issues and Fixes

Quick Start Guide to QSetup: Install & Configure in 5 MinutesQSetup is a lightweight installer framework designed to make packaging, installing, and configuring desktop applications fast and simple. This guide walks you through a complete quick-start workflow: downloading QSetup, creating a basic installer package, configuring installation options, and performing a test install — all in about five minutes. It’s written for developers and sysadmins who want a practical, no-fluff path from zero to a working installer.

---

What you’ll need

• A development machine (Windows or macOS recommended for packaging target desktop apps).
• The application files you want to package (binary/executable, resources, config files).
• Basic familiarity with the command line and editing text files.

Estimated time: 5 minutes (fast path) — more if you customize behavior, scripts, or digital signing.

---

Step 1 — Download and install QSetup

1. Visit the QSetup download page or your package manager.
2. Choose the appropriate package for your OS and install it. On Windows this may be an MSI or EXE; on macOS a DMG or Homebrew package.
3. Confirm installation by opening a terminal and running:

   
   qsetup --version 

   You should see QSetup’s version output. If so, you’re ready.

---

Step 2 — Create a project folder

Create a new directory to hold your installer project and copy your application files into it.

mkdir myapp-installer cd myapp-installer cp -r /path/to/myapp/* . 

Keep a clear structure:

• bin/ — executables
• resources/ — images, docs
• config/ — default configuration files
• scripts/ — pre/post install scripts

---

Step 3 — Create the QSetup configuration file

QSetup uses a simple declarative config (YAML or JSON) to define installer contents and behavior. Create a file named qsetup.yml (or qsetup.json). Minimal example (YAML):

name: MyApp version: 1.0.0 publisher: Example Corp license: LICENSE.txt files:   - src: bin/myapp.exe     dest: $PROGRAMFILES/MyApp   - src: resources/*     dest: $PROGRAMFILES/MyApp/resources shortcuts:   - name: MyApp     path: $DESKTOP     target: $PROGRAMFILES/MyApp/bin/myapp.exe actions:   postinstall:     - scripts/create-config.sh 

Key fields:

• name, version, publisher: installer metadata.
• files: source and destination mappings. Wildcards allowed.
• shortcuts: create desktop/start menu shortcuts.
• actions: scripts to run pre/post install.

---

Step 4 — Add install scripts (optional)

If you need to initialize configuration files, register services, or set permissions, add small scripts in scripts/. Example post-install bash script:

#!/bin/bash echo "Creating default config..." mkdir -p "$PROGRAMFILES/MyApp/config" cp config/default.json "$PROGRAMFILES/MyApp/config/" 

Make scripts executable:

chmod +x scripts/create-config.sh 

---

Step 5 — Build the installer

Run QSetup’s build command from the project root:

qsetup build qsetup.yml -o MyAppInstaller.exe 

Options:

• -o: output installer filename.
• –platform: target platform (if cross-building).
• –sign: path to code-signing certificate (if available).

QSetup bundles your files and embeds the configuration and scripts into a single installer.

---

Step 6 — Test the installer

1. Run the generated installer on a clean test machine or VM:

   
   ./MyAppInstaller.exe 

2. Follow prompts, choose install location, and complete installation.
3. Verify:

• Application files exist in the chosen install folder.
• Desktop/start menu shortcuts were created.
• Post-install scripts ran and config files are present.
• Application launches successfully.

---

Troubleshooting quick checklist

• Q: Installer fails to run on target machine. A: Check platform compatibility and permissions; run as administrator.
• Q: Files missing after install. A: Verify paths in qsetup.yml and that files were present in the project folder before build.
• Q: Scripts didn’t execute. A: Ensure scripts are executable and referenced correctly in actions.postinstall.

---

Next steps & customization ideas

• Add an uninstaller section to remove files and shortcuts cleanly.
• Digitally sign the installer for trusted distribution.
• Localize installer text for multiple languages.
• Configure silent/automated installations for enterprise deployment: add a –silent flag support and provide default answers in the config.
• Integrate QSetup build into CI pipelines to automatically produce installers on release.

---

This quick guide covers the essentials to get a basic QSetup installer up and running in roughly five minutes. For advanced features (digital signing, MSI transforms, complex service registration, or OS-specific packaging nuances), consult QSetup’s full documentation.