Beginner Step-by-Step Guide

This guide walks you through setting up and running your first dala mobile app from scratch. No prior mobile development experience required!

What is dala?

dala is a toolkit that lets you build mobile apps using Elixir and OTP (Erlang VM). You write your app logic in Elixir, and dala packages it to run natively on iOS and Android devices.

Three repositories work together:

dala - The core library (LiveView, native bridges, runtime)
dala_dev - Development tools (what this guide covers)
dala_new - Project templates and generators

Prerequisites Checklist

Before starting, ensure you have:

Required for Everyone

[ ] Elixir installed - Run elixir --version (need 1.18+)
[ ] Mix installed - Run mix --version

For iOS Development (Mac only)

[ ] macOS - iOS development requires macOS
[ ] Xcode installed - From App Store
[ ] Xcode command line tools - Run xcode-select --install
[ ] Apple Developer Account (free is fine for device testing)

For Android Development

[ ] Android SDK - Install via Android Studio or command line
[ ] Android device or emulator - Physical device recommended
[ ] ADB tools - Should come with Android SDK

Verify Your Setup

Run this to check your environment:

# Check Elixir
elixir --version

# Check if dala_dev is available (we'll install it next)
mix dala.doctor

Step 1: Create Your First dala App

Using the Project Generator

The easiest way to start is with dala_new:

# Install dala_new archive
mix archive.install hex dala_new

# Create a new dala project
mix dala.new my_first_app

# Navigate to your project
cd my_first_app

This creates a project structure like:

my_first_app/
├── lib/
│   └── my_first_app/
│       ├── application.ex      # App entry point
│       ├── live/              # LiveView modules
│       │   └── home_live.ex
│       └── screens/           # Mobile screens
│           └── home_screen.ex
├── config/
│   └── config.exs
├── dala.exs                   # dala configuration
└── mix.exs                    # Elixir project file

Understanding the Structure

LiveView modules (lib/my_first_app/live/) - Handle state and events
Screen modules (lib/my_first_app/screens/) - Define the UI
dala.exs - Configuration for mobile deployment
mix.exs - Standard Elixir project configuration

Step 2: Initial Setup with dala_dev

Now let's set up your project for mobile development:

Run the Install Command

# This sets up everything you need
mix dala.install

The installer will:

Download OTP runtime - Pre-built Erlang VM for mobile
Generate app icons - Default icons (you can customize later)
Create dala.exs - Configuration file (if not exists)
Verify toolchain - Check your development environment

What Gets Downloaded?

The installer downloads pre-built OTP (Open Telecom Platform) runtimes:

~/.dala/
└── runtimes/
    ├── ios-sim/
    │   └── otp.tar.gz
    ├── ios-device/
    │   └── otp.tar.gz
    └── android/
        └── otp.tar.gz

These are cached globally so future projects don't need to re-download.

Verify Installation

# Check everything is set up correctly
mix dala.doctor

You should see something like:

✓ Elixir installed
✓ Mix available
✓ OTP runtime for iOS sim found
✓ OTP runtime for Android found
✓ ADB available (for Android)
✓ Xcode tools available (for iOS)

Step 3: Connect a Device or Emulator

Option A: Physical Android Device

Enable Developer Options on your Android device:
- Go to Settings → About Phone
- Tap "Build Number" 7 times
- Developer Options will appear in Settings
Enable USB Debugging in Developer Options
Connect via USB to your computer
Authorize the connection on your phone (allow USB debugging)
Verify connection:
```
mix dala.devices
```
You should see your device listed under "Android Devices".

Option B: Android Emulator

# List available emulators
mix dala.emulators

# Launch an emulator
mix dala.emulators launch "Pixel_6_API_33"

Option C: iOS Simulator (Mac only)

# List available simulators
mix dala.emulators

# Launch iOS simulator
mix dala.emulators launch "iPhone 14"

Option D: Physical iOS Device

Connect your iPhone via USB
Trust the computer on your iPhone
Verify connection:
```
mix dala.devices
```

Step 4: Run Your App for the First Time

Deploy to Device

# Deploy to the first available device
mix dala.deploy

# Or specify a device
mix dala.devices  # Note the device ID
mix dala.deploy --device <device_id>

What Happens During Deploy?

Compiles your Elixir code to BEAM bytecode
Packages with the OTP runtime
Installs the app on your device
Launches the app

You should see your app launch on the device!

First App Structure

The default app shows:

A welcome message
A counter button (LiveView in action!)
Basic navigation

Tap the button - the counter updates instantly. That's LiveView working on your phone!

Step 5: Make Your First Change

Understanding Hot Push

Instead of redeploying the entire app, you can "hot push" just the changed code.

Start Watch Mode

# Start watching for file changes
mix dala.watch

# Or with specific device
mix dala.watch --device <device_id>

Make a Change

Open lib/my_first_app/live/home_live.ex in your editor and find the render function. Change some text:

# Before
def render(assigns) do
  ~H"""
  <Text>Welcome to dala!</Text>
  """
end

# After
def render(assigns) do
  ~H"""
  <Text>Hello from my first dala app!</Text>
  """
end

Save the file. Watch mode will automatically push the change to your device. Check your phone - the text should update instantly!

Stop Watch Mode

When done developing:

mix dala.watch_stop

Step 6: Customize App Icons

Generate New Icons

# Use a PNG image (1024x1024 recommended)
mix dala.icon path/to/icon.png

# Or use the default generator
mix dala.icon --default

This generates icons for:

Android (various densities)
iOS (all required sizes)
App stores

Icon Locations

After generation:

assets/
├── icon.png              # Your source icon
├── android/             # Android icons
│   ├── mipmap-hdpi/
│   ├── mipmap-mdpi/
│   └── ...
└── ios/                  # iOS icons
    ├── AppIcon60x60@2x.png
    ├── AppIcon60x60@3x.png
    └── ...

Step 7: Enable Additional Features

dala supports optional native features. Enable them as needed:

# See available features
mix dala.enable --list

# Enable camera access
mix dala.enable camera

# Enable photo library
mix dala.enable photo_library

# Enable location services
mix dala.enable location

# Enable push notifications
mix dala.enable push

Each feature:

Updates dala.exs with required permissions
Adds necessary native code
Updates app configuration

Step 8: Test on Multiple Devices

List All Devices

mix dala.devices

Output example:

Android Devices:
  - emulator-5554 (Android 13, Pixel 6) [short: a1b2]
  - R32N42ABC (Samsung Galaxy S21) [short: c3d4]

iOS Simulators:
  - A1B2C3D4-1234 (iPhone 14) [short: e5f6]

iOS Devices:
  - 00008020-0012345 (iPhone 13) [short: g7h8]

Deploy to Specific Device

# Use short ID for convenience
mix dala.deploy --device a1b2

Step 9: Debugging Basics

Connect to Running App

# Connect to device for interactive debugging
mix dala.connect --device <id>

You'll get an IEx prompt running on the device:

# Now you're in IEx on the phone!
# Inspect app state
:sys.get_status(MyFirstApp.Live.HomeLive)

# Call functions
MyFirstApp.some_function()

# Exit with Ctrl+C twice

View Logs

# Stream logs from device
mix dala.logs --device <id>

# Filter by level
mix dala.logs --level error

Step 10: Build for Release (When Ready)

When you're ready to share your app:

For Testing (Ad-hoc)

# iOS - for registered devices
mix dala.release --no-sign
mix dala.deploy --device <ios_device>

# Android - installable APK
mix dala.release.android --apk
adb install my_first_app.apk

For App Stores

# iOS - App Store / TestFlight
mix dala.release
mix dala.publish --testflight

# Android - Google Play
mix dala.release.android
mix dala.publish.android --track beta

See the Release and Packaging Guide for details.

Common Beginner Mistakes

Mistake 1: Not Enabling Features Before Using Them

# Wrong: Using camera without enabling
# Your app will crash!

# Right: Enable first
mix dala.enable camera
# Then use in code

Mistake 2: Forgetting to Stop Watch Mode

# Watch mode runs in background
# Always stop it when done
mix dala.watch_stop

Mistake 3: Device Goes to Sleep

# Keep device awake during development
# Android: Settings → Developer Options → Stay Awake
# iOS Simulator: Hardware → Keep Screen Awake

Mistake 4: Not Reading Error Messages

# If something fails, read the full output
# dala_dev provides actionable error messages

# Run doctor for diagnostics
mix dala.doctor

Quick Reference Commands

# Setup
mix dala.new my_app          # Create new app
mix dala.install             # Initial setup
mix dala.icon path/to.png    # Generate icons

# Development
mix dala.devices             # List devices
mix dala.deploy              # Deploy to device
mix dala.watch               # Auto-push changes
mix dala.connect             # Interactive debugging

# Debugging
mix dala.logs                # View logs
mix dala.doctor              # Diagnose issues

# Release
mix dala.release             # Build for iOS
mix dala.release.android     # Build for Android
mix dala.publish             # Upload to stores

Next Steps

Congratulations! You've built and deployed your first dala mobile app. Here's what to explore next:

Learn LiveView - The UI framework (see dala documentation)
Explore Native Features - Camera, GPS, notifications (mix dala.enable --list)
Read Development Workflow - development_workflow.md
Prepare for Release - release_and_packaging.md
Join the Community - Check dala project for community links

Getting Help

Run doctor: mix dala.doctor - Diagnoses common issues
Check logs: mix dala.logs - See what's happening
Read docs: mix help dala - All available commands
Project AGENTS.md: For detailed technical information

Happy coding! 🚀

← Previous Page dala_dev

Next Page → Development Workflow