Case Study 1: Distributing a Lazarus App to 100 Users

Overview

Rosa's freelance design studio has grown. Ten colleagues ask for PennyWise. Then their friends ask. Soon Rosa needs to distribute PennyWise to 100 people — designers, accountants, and small-business owners — across Windows, macOS, and Linux. This case study walks through the practical decisions and workflows for reaching real users.

The Distribution Plan

Phase 1: Assess the Audience

Rosa surveys her potential users:

Phase 2: Build for Each Platform

Windows build: - Compile with -O2, strip symbols. - Include sqlite3.dll (64-bit). - Create an Inno Setup installer. - Test on a clean Windows 10 VM.

macOS build: - Compile on macOS (or in a macOS VM). - Create a .app bundle with a proper icon. - Package as a DMG. - Note: without a paid Apple Developer ID, users must right-click > Open to bypass Gatekeeper. Document this clearly.

Linux build: - Compile on Ubuntu 22.04. - Create both a .deb package and an AppImage. - Test on a clean Ubuntu VM.

Phase 3: Create a Distribution Page

Rosa creates a simple webpage with:

• Download links for each platform.
• Installation instructions (with screenshots).
• A FAQ section addressing common issues.
• A contact email for support.

Phase 4: Handle Updates

When bugs are found or features added:

1. Increment the version number.
2. Rebuild for all platforms.
3. Upload new installers.
4. Users download and install the new version over the old one.

For future versions, Rosa considers adding an auto-update check: on startup, PennyWise pings a URL for the current version number and displays "Update available" if newer.

Common Issues and Solutions

Issue: "sqlite3.dll not found" (Windows)

Symptom: Application fails to start with a DLL error. Cause: The installer did not place sqlite3.dll alongside the executable, or the user extracted only the .exe from the ZIP. Solution: Ensure the installer copies sqlite3.dll to the application directory. In the portable ZIP, include clear instructions.

Issue: "PennyWise is damaged and can't be opened" (macOS)

Symptom: macOS Gatekeeper blocks the unsigned application. Cause: The application is not code-signed with an Apple Developer ID. Solution: Document the workaround: right-click the app > Open > Open (bypass Gatekeeper). For professional distribution, invest in an Apple Developer ID ($99/year).

Issue: Decimal separator mismatch

Symptom: Amounts display as "1.234,56" on some systems or fail to parse. Cause: European locale uses comma as decimal separator. Solution: Use FormatSettings with an explicit decimal separator for all file I/O and database operations. Display values using the system locale.

var
  FS: TFormatSettings;
begin
  FS := DefaultFormatSettings;
  FS.DecimalSeparator := '.';
  SavedValue := FloatToStr(Amount, FS);  { always saves with period }
end;

Issue: High-DPI displays show tiny controls

Symptom: On 4K displays, the application looks microscopic. Solution: Ensure Application.Scaled := True is in the .lpr file. Use Font.Size rather than Font.Height for resolution-independent font sizing. Test on 150% and 200% DPI scaling.

Issue: Database file location differs by platform

Symptom: Users cannot find their data to back it up. Solution: Add a "Data Location" entry in the Help menu that shows the path to the database file:

procedure TfrmMain.miDataLocationClick(Sender: TObject);
begin
  ShowMessage('Your data is stored at:' + LineEnding +
    GetAppConfigDir(False) + 'pennywise.db');
end;

Metrics After 3 Months

The two critical bugs: a date parsing issue with non-US locales (fixed with explicit FormatSettings) and a crash when the config directory did not exist (fixed with ForceDirectories).

Lessons Learned

1. Test on clean systems. Half of all deployment issues are missing dependencies that exist on the development machine but not on the user's machine.
2. Write installation instructions. Users do not read minds. Screenshot-based instructions save support emails.
3. Handle locale differences. Never assume the decimal separator, date format, or currency symbol.
4. macOS code signing matters. Unsigned applications create friction for users and may prevent adoption.
5. Portable distribution (ZIP) is the simplest. Many users prefer copying a folder to running an installer.
6. Native compilation pays off. A 4 MB executable that starts instantly with no runtime requirements makes deployment dramatically simpler than any interpreted or framework-dependent alternative.