Development Setup - EnvaSistema

Prerequisites

Before you begin, ensure you have the following installed:

Android Studio

Hedgehog (2023.1.1) or newer

JDK

Java Development Kit 11 or higher

Kotlin

Kotlin 2.2.10 (handled by Gradle)

Android SDK

API Level 33+ (Android 13)

Initial Setup

1. Clone the Repository

git clone <repository-url>
cd EnvaSistema

2. Open in Android Studio

Launch Android Studio
Select Open an Existing Project
Navigate to the cloned EnvaSistema directory
Click OK

Android Studio will automatically detect the Gradle configuration and begin syncing dependencies. This may take several minutes on the first run.

3. Configure SDK

Ensure the required SDK components are installed:

Open SDK Manager

Go to Tools → SDK Manager in Android Studio

Install SDK Platform

Under SDK Platforms, check Android 14.0 (API 35) and Android 13.0 (API 33)

Install Build Tools

Under SDK Tools, ensure Android SDK Build-Tools 35.0.0 is installed

Apply Changes

Click Apply and wait for the installation to complete

Project Configuration

Gradle Version Catalog

EnvaSistema uses Gradle’s version catalog for dependency management. All versions are centralized in:

gradle/libs.versions.toml

[versions]
agp = "9.1.0"
coreKtx = "1.10.1"
junit = "4.13.2"
junitVersion = "1.1.5"
espressoCore = "3.5.1"
lifecycleRuntimeKtx = "2.6.1"
activityCompose = "1.8.0"
kotlin = "2.2.10"
composeBom = "2024.09.00"
navigationCompose = "2.8.5"

[libraries]
androidx-core-ktx = { group = "androidx.core", name = "core-ktx", version.ref = "coreKtx" }
androidx-compose-bom = { group = "androidx.compose", name = "compose-bom", version.ref = "composeBom" }
androidx-compose-material3 = { group = "androidx.compose.material3", name = "material3" }
androidx-navigation-compose = { group = "androidx.navigation", name = "navigation-compose", version.ref = "navigationCompose" }
# ... additional dependencies

[plugins]
android-application = { id = "com.android.application", version.ref = "agp" }
kotlin-compose = { id = "org.jetbrains.kotlin.plugin.compose", version.ref = "kotlin" }

Build Configuration

The app module is configured in app/build.gradle.kts:

app/build.gradle.kts

plugins {
    alias(libs.plugins.android.application)
    alias(libs.plugins.kotlin.compose)
}

android {
    namespace = "com.example.envasistema"
    compileSdk = 35

    defaultConfig {
        applicationId = "com.example.envasistema"
        minSdk = 33
        targetSdk = 35
        versionCode = 1
        versionName = "1.0"

        testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
    }

    buildTypes {
        release {
            isMinifyEnabled = false
            proguardFiles(
                getDefaultProguardFile("proguard-android-optimize.txt"),
                "proguard-rules.pro"
            )
        }
    }
    
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_11
        targetCompatibility = JavaVersion.VERSION_11
    }
    
    buildFeatures {
        compose = true
    }
}

Minimum SDK: EnvaSistema requires Android 13 (API 33) or higher. Ensure your test devices meet this requirement.

Building the Project

Sync Gradle

After any configuration changes:

./gradlew sync

Or use Android Studio’s Sync Project with Gradle Files button (elephant icon).

Clean Build

./gradlew clean build

Debug Build

./gradlew assembleDebug

The APK will be generated at:

app/build/outputs/apk/debug/app-debug.apk

Release Build

./gradlew assembleRelease

Release builds require signing configuration. See the Signing Configuration section below.

Running the App

Using Android Studio

Connect an Android device via USB or launch an emulator
Click the Run button (green play icon) or press Shift + F10
Select your target device from the dropdown
Wait for the app to install and launch

Using Command Line

# Install on connected device
./gradlew installDebug

# Launch the app
adb shell am start -n com.example.envasistema/.MainActivity

Development Tools

Jetpack Compose Preview

EnvaSistema components include @Preview annotations for rapid UI development:

@Preview(showBackground = true, device = "spec:width=1080px,height=1920px,dpi=400")
@Composable
fun HomeScreenPreview() {
    EnvaSistemaTheme {
        HomeScreen({}, {}, {}, {})
    }
}

View Previews: Open any Composable file and click Split or Design mode in the top-right corner to see live previews.

Layout Inspector

Debug your Compose UI hierarchy:

Run the app on a device/emulator
Go to Tools → Layout Inspector
Select your app process
Explore the component tree and properties

Logcat

View runtime logs:

import android.util.Log

Log.d("EnvaSistema", "Scan count: $count")
Log.e("EnvaSistema", "Error saving data", exception)

Filter logs in Android Studio’s Logcat window using the tag EnvaSistema.

Code Style

Kotlin Style Guide

EnvaSistema follows the official Kotlin Coding Conventions. Key conventions:

Indentation: 4 spaces
Line length: Max 120 characters
Naming:
- Classes: PascalCase
- Functions: camelCase
- Constants: UPPER_SNAKE_CASE
- Composables: PascalCase

Format Code

Format code automatically:

Windows/Linux: Ctrl + Alt + L
macOS: Cmd + Option + L

Or run:

./gradlew ktlintFormat

Testing

Unit Tests

Run unit tests:

./gradlew test

Test files are located in:

app/src/test/java/com/example/envasistema/

Instrumented Tests

Run instrumented tests on a device:

./gradlew connectedAndroidTest

Test files are located in:

app/src/androidTest/java/com/example/envasistema/

Compose UI Tests

Example Compose test:

@Test
fun testMenuCardClick() {
    composeTestRule.setContent {
        EnvaSistemaTheme {
            MenuCard(
                title = "Test",
                subtitle = "Subtitle",
                icon = Icons.Default.Add,
                onClick = { /* verify action */ }
            )
        }
    }
    
    composeTestRule.onNodeWithText("Test").performClick()
    // Assert expected behavior
}

Debugging

Breakpoints

Set breakpoints in Kotlin code:

Click the gutter next to a line number
Run the app in Debug mode (Shift + F9)
The app will pause at breakpoints

Compose Recomposition Debugging

Enable recomposition highlighting:

import androidx.compose.runtime.remember
import androidx.compose.ui.platform.LocalInspectionMode

val isInspecting = LocalInspectionMode.current
if (isInspecting) {
    // Preview-specific code
}

Signing Configuration

Debug Signing

Debug builds are automatically signed with a debug keystore.

Release Signing

For production releases, configure signing:

Create a keystore:

keytool -genkey -v -keystore release.keystore -alias envasistema -keyalg RSA -keysize 2048 -validity 10000

Add to app/build.gradle.kts:

android {
    signingConfigs {
        create("release") {
            storeFile = file("release.keystore")
            storePassword = "your-store-password"
            keyAlias = "envasistema"
            keyPassword = "your-key-password"
        }
    }
    buildTypes {
        release {
            signingConfig = signingConfigs.getByName("release")
        }
    }
}

Security: Never commit keystores or passwords to version control. Use environment variables or gradle.properties for sensitive data.

Troubleshooting

Gradle Sync Failed

Solution:

Check internet connection
Invalidate caches: File → Invalidate Caches / Restart
Delete .gradle and .idea folders, then re-sync
Verify JDK version matches project requirements

Compose Preview Not Showing

Solution:

Ensure you’re in Split or Design mode
Check that the function is annotated with @Preview
Rebuild the project: Build → Rebuild Project
Restart Android Studio

App Crashes on Launch

Solution:

Check Logcat for exceptions
Verify device API level meets minSdk (33+)
Uninstall and reinstall the app
Clear app data from device settings

Dependency Resolution Errors

Solution:

Check gradle/libs.versions.toml for version conflicts
Update Gradle wrapper: ./gradlew wrapper --gradle-version=8.5
Sync project after changes
Review build output for specific error messages

Development Workflow

Recommended Workflow

Create Feature Branch

git checkout -b feature/new-feature

Develop with Previews

Use Compose Preview for rapid UI iteration without running the full app

Test Locally

Run unit and instrumented tests to verify functionality

Code Review

Submit PR and address feedback

Merge to Main

After approval, merge and deploy

IDE Configuration

Recommended Plugins

Kotlin

Core Kotlin language support (bundled)

Compose Multiplatform

Enhanced Compose tooling

ADB Idea

Quick ADB commands from IDE

Material Theme UI

Better IDE theming

Editor Settings

Configure Android Studio for optimal development:

Editor → Code Style → Kotlin
- Set indent to 4 spaces
- Enable auto-format on save
Editor → Inspections
- Enable Kotlin inspections
- Enable Compose-specific warnings
Build, Execution, Deployment → Compiler
- Enable parallel compilation
- Increase heap size to 4GB for faster builds

Performance Optimization

Build Performance

Optimize build times:

gradle.properties

org.gradle.jvmargs=-Xmx4096m -XX:MaxMetaspaceSize=512m -XX:+HeapDumpOnOutOfMemoryError
org.gradle.parallel=true
org.gradle.caching=true
android.useAndroidX=true
kotlin.code.style=official

Compose Performance

Use remember to avoid unnecessary recompositions
Leverage derivedStateOf for computed state
Profile with Compose Layout Inspector

Resources

Kotlin Docs

Official Kotlin documentation

Jetpack Compose

Compose guides and references

Material 3

Material Design 3 guidelines

Android Studio

IDE documentation

Next Steps

Architecture

Understand the app architecture

UI Components

Learn about reusable components

Get Started

Core Features

User Guide

Technical

​Prerequisites

Android Studio

JDK

Kotlin

Android SDK

​Initial Setup

​1. Clone the Repository

​2. Open in Android Studio

​3. Configure SDK

​Project Configuration

​Gradle Version Catalog

​Build Configuration

​Building the Project

​Sync Gradle

​Clean Build

​Debug Build

​Release Build

​Running the App

​Using Android Studio

​Using Command Line

​Development Tools

​Jetpack Compose Preview

​Layout Inspector

​Logcat

​Code Style

​Kotlin Style Guide

​Format Code

​Testing

​Unit Tests

​Instrumented Tests

​Compose UI Tests

​Debugging

​Breakpoints

​Compose Recomposition Debugging

​Signing Configuration

​Debug Signing

​Release Signing

​Troubleshooting

​Development Workflow

​Recommended Workflow

​IDE Configuration

​Recommended Plugins

Kotlin

Compose Multiplatform

ADB Idea

Material Theme UI

​Editor Settings

​Performance Optimization

​Build Performance

​Compose Performance

​Resources

Kotlin Docs

Jetpack Compose

Material 3

Android Studio

​Next Steps

Architecture

UI Components

Build docs developers (and LLMs) love

Prerequisites

Initial Setup

1. Clone the Repository

2. Open in Android Studio

3. Configure SDK

Project Configuration

Gradle Version Catalog

Build Configuration

Building the Project

Sync Gradle

Clean Build

Debug Build

Release Build

Running the App

Using Android Studio

Using Command Line

Development Tools

Jetpack Compose Preview

Layout Inspector

Logcat

Code Style

Kotlin Style Guide

Format Code

Testing

Unit Tests

Instrumented Tests

Compose UI Tests

Debugging

Breakpoints

Compose Recomposition Debugging

Signing Configuration

Debug Signing

Release Signing

Troubleshooting

Development Workflow

Recommended Workflow

IDE Configuration

Recommended Plugins

Editor Settings

Performance Optimization

Build Performance

Compose Performance

Resources

Next Steps