Skip to content

Latest commit

 

History

History
470 lines (346 loc) · 9.34 KB

BUILD.md

File metadata and controls

470 lines (346 loc) · 9.34 KB

Oracy Client App Build Guide

This guide covers building, testing, and releasing the Oracy client app for Android, Web, Linux, and Windows.

Prerequisites

Development Environment

  • Flutter SDK 3.10+
  • Dart SDK (included with Flutter)

Platform-Specific Requirements

Android

  • Android Studio with Android SDK
  • Java 17+ (included with Android Studio)

Linux Desktop

sudo apt install clang cmake ninja-build libgtk-3-dev pkg-config

Windows Desktop

  • Visual Studio 2022 with "Desktop development with C++" workload
  • Windows 10 SDK

Web

  • Chrome browser (for development and testing)

Verify Installation

flutter doctor

All checks should pass for your target platforms.

Project Setup

1. Clone and Install Dependencies

git clone https://github.com/pentaxis93/oracy.git
cd oracy/mobile

# Install Flutter dependencies
flutter pub get

# Generate Drift database code (if modified)
dart run build_runner build

2. Configuration

The app connects to https://api.oracy.app by default. To use a different server:

  1. Edit lib/services/api_client.dart
  2. Change kDefaultBaseUrl constant

For development, you can also configure in the app's Settings screen.

Development

Run in Debug Mode

# Run on auto-detected platform
flutter run

# Run on specific platform
flutter run -d chrome          # Web browser
flutter run -d linux           # Linux desktop
flutter run -d windows         # Windows desktop

# List available devices
flutter devices

# Run on specific Android device
flutter run -d <device_id>

Hot Reload vs Hot Restart

  • Hot Reload (r): Preserves state, fast
  • Hot Restart (R): Full restart, clears state

Building for Release

Android

1. Configure Signing

Create keystore (one-time):

keytool -genkey -v -keystore ~/upload-keystore.jks \
  -keyalg RSA -keysize 2048 -validity 10000 \
  -alias upload

Create android/key.properties:

storePassword=<password>
keyPassword=<password>
keyAlias=upload
storeFile=<path/to/upload-keystore.jks>

Important: Add key.properties to .gitignore (already done).

2. Build APK

# Build release APK
flutter build apk --release

# Output: build/app/outputs/flutter-apk/app-release.apk

3. Build App Bundle (for Play Store)

# Build release bundle
flutter build appbundle --release

# Output: build/app/outputs/bundle/release/app-release.aab

Web

1. Build

flutter build web --release

# Output: build/web/

2. Deploy

The build/web/ directory contains static files that can be hosted anywhere:

GitHub Pages:

# Copy build/web contents to your gh-pages branch or docs/ folder

Any static host (Netlify, Vercel, Firebase Hosting):

  • Upload the contents of build/web/
  • Configure to serve index.html for all routes (SPA mode)

Local testing:

cd build/web
python -m http.server 8080
# Open http://localhost:8080

Linux

1. Build

flutter build linux --release

# Output: build/linux/x64/release/bundle/

The bundle directory contains the executable and required libraries.

2. Distribution Options

Direct distribution (zip/tar):

cd build/linux/x64/release
tar -czvf oracy-linux-x64.tar.gz bundle/

Snap Store (recommended for wider distribution):

Create snap/snapcraft.yaml:

name: oracy
version: '1.0.0'
summary: Voice transcription made simple
description: |
  Record audio and get instant transcripts powered by AI.

grade: stable
confinement: strict
base: core22

apps:
  oracy:
    command: oracy
    extensions: [gnome]
    plugs:
      - audio-record
      - network

parts:
  oracy:
    plugin: nil
    source: build/linux/x64/release/bundle
    override-build: |
      cp -r $SNAPCRAFT_PART_SRC/* $SNAPCRAFT_PART_INSTALL/

Build and publish:

snapcraft
snapcraft upload oracy_1.0.0_amd64.snap --release=stable

Windows

1. Build

flutter build windows --release

# Output: build/windows/x64/runner/Release/

2. Distribution Options

Direct distribution (zip):

cd build/windows/x64/runner
# Zip the Release/ folder

MSIX Package (for Microsoft Store):

Install the msix package:

flutter pub add --dev msix

Add to pubspec.yaml:

msix_config:
  display_name: Oracy
  publisher_display_name: Your Name
  identity_name: com.yourcompany.oracy
  msix_version: 1.0.0.0
  capabilities: microphone, internetClient

Build MSIX:

dart run msix:create
# Output: build/windows/x64/runner/Release/oracy.msix

Version Management

Update Version

Edit pubspec.yaml:

version: 1.0.0+1   # format: <version>+<build_number>
  • version: User-visible version (1.0.0)
  • build_number: Internal build number, increment for each release

Version Strategy

  • Major (1.x.x -> 2.x.x): Breaking changes
  • Minor (1.0.x -> 1.1.x): New features
  • Patch (1.0.0 -> 1.0.1): Bug fixes

Testing

Unit Tests

flutter test

Integration Tests

flutter test integration_test/

Analyze Code

flutter analyze
dart format --set-exit-if-changed .

Release Checklist

Pre-Release

  • Update version in pubspec.yaml
  • Run flutter analyze - no issues
  • Run flutter test - all pass
  • Test on target platforms
  • Verify API connectivity to production server
  • Update changelog

Android Release

  • Build signed APK/AAB
  • Test APK on device before upload
  • Upload to Play Console
  • Fill release notes
  • Submit for review

Web Release

  • Build with flutter build web --release
  • Test locally with a web server
  • Deploy to hosting (GitHub Pages, Netlify, etc.)
  • Verify production URL works

Linux Release

  • Build with flutter build linux --release
  • Test on clean Linux system
  • Package as tar.gz or Snap
  • Upload to Snap Store or GitHub Releases

Windows Release

  • Build with flutter build windows --release
  • Test on clean Windows system
  • Package as zip or MSIX
  • Upload to Microsoft Store or GitHub Releases

Troubleshooting

Build Errors

# Clean and rebuild
flutter clean
flutter pub get
flutter build <platform> --release

Linux GTK Issues

# Ensure all dependencies are installed
sudo apt install clang cmake ninja-build libgtk-3-dev pkg-config

Windows Build Issues

  • Ensure Visual Studio 2022 is installed with C++ workload
  • Run from "Developer Command Prompt for VS 2022" if PATH issues occur

Code Generation Issues

# Regenerate Drift database code
dart run build_runner clean
dart run build_runner build --delete-conflicting-outputs

CI/CD Integration

GitHub Actions Example

name: Build

on:
  push:
    tags:
      - 'v*'

jobs:
  build-android:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: subosito/flutter-action@v2
        with:
          flutter-version: '3.10.0'
      - run: flutter pub get
        working-directory: client/flutter
      - run: flutter build apk --release
        working-directory: client/flutter
      - uses: actions/upload-artifact@v4
        with:
          name: android-release
          path: client/flutter/build/app/outputs/flutter-apk/app-release.apk

  build-web:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: subosito/flutter-action@v2
        with:
          flutter-version: '3.10.0'
      - run: flutter pub get
        working-directory: client/flutter
      - run: flutter build web --release
        working-directory: client/flutter
      - uses: actions/upload-artifact@v4
        with:
          name: web-release
          path: client/flutter/build/web

  build-linux:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: sudo apt-get update && sudo apt-get install -y clang cmake ninja-build libgtk-3-dev
      - uses: subosito/flutter-action@v2
        with:
          flutter-version: '3.10.0'
      - run: flutter pub get
        working-directory: client/flutter
      - run: flutter build linux --release
        working-directory: client/flutter
      - uses: actions/upload-artifact@v4
        with:
          name: linux-release
          path: client/flutter/build/linux/x64/release/bundle

  build-windows:
    runs-on: windows-latest
    steps:
      - uses: actions/checkout@v4
      - uses: subosito/flutter-action@v2
        with:
          flutter-version: '3.10.0'
      - run: flutter pub get
        working-directory: client/flutter
      - run: flutter build windows --release
        working-directory: client/flutter
      - uses: actions/upload-artifact@v4
        with:
          name: windows-release
          path: client/flutter/build/windows/x64/runner/Release

App Store Metadata

App Name

Oracy

Short Description

Voice transcription made simple.

Full Description

Oracy turns your voice into text instantly. Record audio memos and get accurate transcripts powered by AI.

Features:

  • One-tap recording
  • Fast, accurate transcription
  • Offline queue for unreliable connections
  • Transcript history and search
  • Android home screen widget for quick access

Keywords

voice, transcription, speech-to-text, memo, recording, audio, notes

Categories

  • Android: Productivity
  • Windows: Productivity