Skip to content

AGENTS.md

Latest commit

 

History

History
81 lines (56 loc) · 2.91 KB

AGENTS.md

File metadata and controls

81 lines (56 loc) · 2.91 KB

AGENTS.md

This document provides instructions for agents and automated systems to work with this repository.

Development Environment Setup

The project has been upgraded to a modern Android build environment. Strict adherence to these versions is required to ensure a successful build.

1. Java Development Kit (JDK)

  • Version: Java 21 is mandatory.
  • Installation: 
    sudo apt-get update && sudo apt-get install -y openjdk-21-jdk
  • Verification: Ensure Java 21 is the default version: 
    java -version

2. Android SDK

  • compileSdk: 36
  • targetSdk: 36
  • minSdk: 21
  • buildToolsVersion: The Android Gradle Plugin will automatically download the required version. Ensure the ANDROID_HOME environment variable is correctly set to your SDK location.

3. Gradle

  • Gradle Version: 9.3.0
  • Android Gradle Plugin (AGP) Version: 8.9.1
  • Kotlin Version: 2.2.10 (Downgraded from 2.3.0 due to CodeQL incompatibility)
  • The Gradle wrapper (./gradlew) is included in the repository and should be used for all build commands. It will automatically download the correct Gradle version.

4. CodeQL Analysis

This repository uses a custom Advanced Setup workflow (.github/workflows/codeql.yml).

IMPORTANT: You must disable GitHub's Default Setup for CodeQL in the repository settings. If Default Setup is enabled, the custom workflow will fail to upload results. See docs/CODEQL_SETUP.md for detailed instructions.

Building the Project

  • Clean the project: 
    ./gradlew clean
  • Build a debug APK: 
    ./gradlew assembleDebug
  • Run unit tests: 
    ./gradlew test

Troubleshooting

Build Failures due to Permission denied

During the build process, you may encounter Permission denied errors related to the .gradle or .kotlin directories in the project root. This is often due to file ownership issues within the sandbox environment.

Solution:

Before running a build, ensure the current user owns these directories by running the following commands from the repository root:

sudo chown -R $(whoami) .gradle/
sudo chown -R $(whoami) .kotlin/

If the build fails with an error related to deleting the app/build directory, you may need to remove it manually with sudo:

sudo rm -rf app/build

Build Failures due to R class not found

If the build fails with "cannot find symbol" errors related to the R class (e.g., R.attr.colorPrimary), it signifies that the Android resource processor failed. This is almost always a symptom of another underlying issue.

Do not attempt to fix R class errors directly. Instead, look for other compilation errors in the build log. Fixing those will typically resolve the R class generation problem. If there are no other errors, the cause is likely a misconfiguration in the app/build.gradle file's dependencies.