Development Environment Setup

Emmanuel BRUNO
emmanuel.bruno@univ-tln.fr

Université de Toulon

LIS UMR CNRS 7020

2025-03-17

Development Environment Setup Guide

This document provides instructions for setting up the development environment for the fitness tracking application. Following these steps will ensure a consistent development experience across the team.

System Requirements

Minimum Requirements

  • CPU: Quad-core 2.0 GHz or higher
  • RAM: 8 GB (16 GB recommended)
  • Disk Space: 10 GB free space (SSD recommended)
  • Operating System:
    • Windows 10/11 (64-bit)
    • macOS 10.15 (Catalina) or later
    • Linux with GNOME or KDE desktop (Ubuntu 20.04 LTS or equivalent)

Required Software

1. Android Studio (Latest Stable Release)

Android Studio is our primary IDE for development.

Installation Instructions

For Windows:

  1. Download Android Studio from developer.android.com/studio
  2. Run the installer and follow the prompts
  3. Use the standard installation with the Android Virtual Device (AVD)

For macOS:

  1. Download Android Studio from developer.android.com/studio
  2. Open the DMG file and drag Android Studio to the Applications folder
  3. Launch Android Studio and follow the setup wizard

For Linux:

  1. Download Android Studio from developer.android.com/studio
  2. Extract the archive: tar -xzf android-studio-*.tar.gz
  3. Navigate to the android-studio/bin directory and execute ./studio.sh

Android Studio Configuration

After installation, configure Android Studio with the following settings:

  1. Install the latest Android SDK:
    • Go to Tools > SDK Manager
    • Select “Android 13.0 (Tiramisu)” and at least one previous version, e.g., “Android 12.0 (S)”
    • Under the SDK Tools tab, ensure the following are installed:
      • Android SDK Build-Tools
      • Android Emulator
      • Android SDK Platform-Tools
      • Google Play services
      • Intel x86 Emulator Accelerator (HAXM) if on Intel CPU
  2. Configure Code Style:
    • Go to Settings/Preferences > Editor > Code Style > Kotlin
    • Import the project code style from config/codestyle/kotlin-codestyle.xml
  3. Install Required Plugins:
    • Kotlin
    • Room
    • Git Integration
    • Markdown
    • Database Navigator

2. Git

Git is our version control system.

Installation Instructions

For Windows: 1. Download Git from git-scm.com 2. During installation, select “Use Git from the Windows Command Prompt” 3. For line endings, select “Checkout as-is, commit as-is”

For macOS: 1. Install with Homebrew: brew install git 2. Alternatively, download from git-scm.com

For Linux: 1. Ubuntu/Debian: sudo apt install git 2. Fedora: sudo dnf install git

Git Configuration

Configure Git with your information:

git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"
git config --global core.autocrlf input

3. Java Development Kit (JDK)

JDK 17 is required for our project.

Installation Instructions

Option 1: Install through Android Studio 1. Open Android Studio > Settings/Preferences > Build, Execution, Deployment > Build Tools > Gradle 2. Set “Gradle JDK” to “Download JDK” 3. Select version 17 and vendor (Amazon Corretto, Eclipse Temurin, or Oracle OpenJDK)

Option 2: Manual Install 1. Download OpenJDK 17 from adoptium.net 2. Install following the platform-specific instructions 3. Set JAVA_HOME environment variable: - Windows: Set in System Properties > Environment Variables - macOS/Linux: Add to ~/.bash_profile or ~/.zshrc: export JAVA_HOME=/path/to/jdk

4. Kotlin

Our project uses Kotlin 1.8.0 or newer.

  • Kotlin comes bundled with Android Studio, but ensure you have the latest version:
    1. In Android Studio, go to Settings/Preferences > Languages & Frameworks > Kotlin
    2. Check “Update channel” is set to “Stable”
    3. Click “Check for updates now” if needed

5. Room Database

Room is our primary persistence library.

  • Room comes with Android Studio as part of Android Jetpack
  • Ensure the latest version is specified in our project’s build.gradle file

Project Setup

Cloning the Repository

git clone https://github.com/organization/fitness-tracking-app.git
cd fitness-tracking-app

Opening the Project

  1. Open Android Studio
  2. Select “Open an existing project”
  3. Navigate to and select the cloned repository folder
  4. Wait for the Gradle sync to complete

Running the Application

On an Emulator

  1. In Android Studio, open AVD Manager (Tools > AVD Manager)
  2. Create a new virtual device or use an existing one
    • Recommended: Pixel 4 or newer with Play Store
    • System Image: Android 13.0 (API 33) or as specified in project requirements
  3. Start the emulator
  4. Run the application (Shift+F10 or Run > Run ‘app’)

On a Physical Device

  1. Enable Developer options and USB debugging on your device
  2. Connect your device to your computer via USB
  3. Allow USB debugging permission if prompted on the device
  4. Select your device from the target device dropdown in Android Studio
  5. Run the application (Shift+F10 or Run > Run ‘app’)

Database Setup

Our app uses Room for local persistence.

Database Inspection

To inspect the database during development:

  1. Use Database Inspector in Android Studio:

    • Run the app in debug mode
    • Go to View > Tool Windows > App Inspection
    • Select “Database Inspector”
    • Connect to the running app process
    • Browse tables and run SQL queries

  2. Export database for external inspection:

    adb shell run-as com.example.fitnessapp cp /data/data/com.example.fitnessapp/databases/fitness_database.db /sdcard/
adb pull /sdcard/fitness_database.db

  3. Use a SQLite browser like DB Browser for SQLite to open the exported database

API Keys and Secrets

For features requiring external services, API keys should be stored securely:

  1. Create a file named apikeys.properties in the project root (this file is git-ignored)

  2. Add your API keys in the format:

    API_KEY_NAME="your_api_key_here"

  3. These keys are accessed through the build system and not committed to version control

Development Workflow

Branch Strategy

We use a simplified GitFlow workflow:

  • main: Production-ready code
  • develop: Integration branch for features
  • feature/feature-name: For new feature development
  • bugfix/issue-description: For bug fixes
  • release/X.Y.Z: For release preparation

Pull Request Process

  1. Create a feature branch from develop
  2. Implement your changes with appropriate unit tests
  3. Verify code passes all automated checks
  4. Create a pull request to merge back to develop
  5. Assign reviewers according to the CODEOWNERS file
  6. Address any feedback from code review
  7. Squash and merge when approved

Code Style and Quality

  • Follow the Kotlin coding conventions
  • Maintain test coverage (minimum 80% for business logic)
  • Use static analysis tools configured in the project:
    • Detekt
    • Android Lint
    • ktlint

To run quality checks locally:

./gradlew detekt
./gradlew lint
./gradlew ktlint

Commit Message Format

We use the following format for commit messages:

type(scope): Short description

Longer description if needed

where type is one of: - feat: New feature - fix: Bug fix - docs: Documentation changes - style: Code style changes (formatting, etc.) - refactor: Code refactoring - test: Adding or modifying tests - chore: Maintenance tasks

Building for Release

To build a release APK/AAB:

  1. Update version information in build.gradle
  2. Run ./gradlew bundleRelease for AAB or ./gradlew assembleRelease for APK
  3. Sign the release with the production keystore

Troubleshooting Common Issues

Gradle Sync Failures

If Gradle sync fails:

  1. Try “File > Invalidate Caches / Restart”
  2. Check internet connection (for dependency downloads)
  3. Update Gradle to the latest version
  4. Check for compatibility between Gradle, Gradle Plugin, and Android Studio versions

Emulator Issues

If the emulator is slow or unstable:

  1. Enable Hardware Acceleration:
    • Windows: Install and configure HAXM
    • macOS: Should work out of the box on Intel Macs
    • Linux: Install KVM
  2. For ARM-based Macs (M1/M2):
    • Use the ARM-specific emulator image for better performance
    • Ensure Android Studio version supports Apple Silicon natively

Build Errors

For common build errors:

  1. “SDK not found”: Update SDK paths in Project Structure dialog
  2. Missing dependencies: Check Maven Central/Google repository connectivity
  3. Version conflicts: Review dependency versions for compatibility

Reference Documentation

Team Contacts

For environment setup issues, contact:

  • Development Environment Support: dev-support@example.com
  • Repository Access: repo-admin@example.com
  • CI/CD Pipeline Issues: ci-admin@example.com