From b1ba3935e6318e34db8cb09406ba1c61b5a017e0 Mon Sep 17 00:00:00 2001
From: Matthew Raymer <matthew.raymer@anomalistdesign.com>
Date: Tue, 11 Feb 2025 07:33:49 +0000
Subject: [PATCH] docs: add comprehensive build instructions for all platforms

Add detailed build instructions for web, desktop (Electron), and mobile
(Capacitor) platforms. Include prerequisites, setup steps, and platform-specific
build commands. Add sections for testing, linting, and development workflows.
Document build output directories and PWA features.
---
 BUILDING.md | 159 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 159 insertions(+)
 create mode 100644 BUILDING.md

diff --git a/BUILDING.md b/BUILDING.md
new file mode 100644
index 00000000..18ece41f
--- /dev/null
+++ b/BUILDING.md
@@ -0,0 +1,159 @@
+# Building TimeSafari
+
+This guide explains how to build TimeSafari for different platforms.
+
+## Prerequisites
+
+- Node.js (LTS version recommended)
+- npm (comes with Node.js)
+- Git
+- For iOS builds: macOS with Xcode installed
+- For Android builds: Android Studio with SDK installed
+- For desktop builds: Additional build tools based on your OS
+
+## Initial Setup
+
+1. Clone the repository:
+   ```bash
+   git clone [repository-url]
+   cd TimeSafari
+   ```
+
+2. Install dependencies:
+   ```bash
+   npm install
+   ```
+
+## Web Build
+
+To build for web deployment:
+
+1. Run the production build:
+   ```bash
+   npm run build
+   ```
+
+2. The built files will be in the `dist` directory.
+
+3. To test the production build locally:
+   ```bash
+   npm run serve
+   ```
+
+## Desktop Build (Electron)
+
+To build the desktop application:
+
+1. Run the Electron build:
+   ```bash
+   npm run build -- --mode electron
+   ```
+
+2. The built files will be in `dist-electron`.
+
+3. To create installable packages:
+   ```bash
+   npm run electron:build
+   ```
+
+This will create platform-specific installers in `dist-electron-build`:
+- Windows: `.exe` installer
+- macOS: `.dmg` file
+- Linux: `.AppImage` file
+
+## Mobile Builds (Capacitor)
+
+### iOS Build
+
+Prerequisites: macOS with Xcode installed
+
+1. Build the web assets:
+   ```bash
+   npm run build -- --mode capacitor
+   ```
+
+2. Add iOS platform if not already added:
+   ```bash
+   npx cap add ios
+   ```
+
+3. Update iOS project with latest build:
+   ```bash
+   npx cap sync ios
+   ```
+
+4. Open the project in Xcode:
+   ```bash
+   npx cap open ios
+   ```
+
+5. Use Xcode to build and run on simulator or device.
+
+### Android Build
+
+Prerequisites: Android Studio with SDK installed
+
+1. Build the web assets:
+   ```bash
+   npm run build -- --mode capacitor
+   ```
+
+2. Add Android platform if not already added:
+   ```bash
+   npx cap add android
+   ```
+
+3. Update Android project with latest build:
+   ```bash
+   npx cap sync android
+   ```
+
+4. Open the project in Android Studio:
+   ```bash
+   npx cap open android
+   ```
+
+5. Use Android Studio to build and run on emulator or device.
+
+## Development
+
+To run the application in development mode:
+
+1. Start the development server:
+   ```bash
+   npm run dev
+   ```
+
+## Testing
+
+Run local tests:
+```bash
+npm run test-local
+```
+
+Run all tests (includes building):
+```bash
+npm run test-all
+```
+
+## Linting
+
+Check code style:
+```bash
+npm run lint
+```
+
+Fix code style issues:
+```bash
+npm run lint-fix
+```
+
+## Notes
+
+- The application uses PWA (Progressive Web App) features for web builds
+- Electron builds disable PWA features automatically
+- Build output directories:
+  - Web: `dist/`
+  - Electron: `dist-electron/`
+  - Capacitor: `dist-capacitor/`
+