# **Build Instructions for Beginners** / **入门构建指南**

## Overview

_This document seeks to improve clarity and coherence._

See also [Developer Guide](./Developer_Guide.md).

_Last Updated at 2026.05.28_

## Requirements

### Build Environment:

You would like to build the application from source instead of developing and contributing. 

- A desktop computer [^PC]:
    - at least 4G RAM
    - enough available storage space, on user home disk (at least ~3G)  
- Compatible desktop operating system [^PC]:
    - Windows 10/11 (tested)
    - Ubuntu 24.04 (tested)
- JDK 21 (Android Gradle Plugin 9.2.1 along with Gradle 9.5.1 are used in this project)
- Android SDK (automatically downloaded via AGP)
- Internet connection 

[^PC]: Compatibility is uncertain on Termux; Android 16 with full Linux VM may be compatible.

### Development Environment:

If you would like to contribute:

- Git
- Android Studio Panda 4 | 2025.3.4 Patch 1
  (Note: JetBrain IDEA may not be compatible due to its limited support on latest Android Gradle Plugin) 

## Build Instructions

(`bash` or `powershell`)

### 1. Obtain Source Code

Choose one of the following methods:

- Download from release page (`Source code (zip/tar.gz)`)
- Clone using Git:
  ```shell
  git clone <REPO-URL> --depth=1 -b <VERSION>
  ```

### 2. Install JDK

Temurin by Eclipse Adoptium Foundation for example:

##### Windows

```shell
winget install --id EclipseAdoptium.Temurin.21.JDK
```

##### Linux (Debian / Ubuntu / ...)

```shell
apt-get install temurin-21-jdk
```

##### Linux (Fedora / RedHat / SUSE)

```shell
yum install temurin-21-jdk
```

### 3. Change Directory to Repository Root

```shell
cd <SOURCE>
# Set-Location <SOURCE>
```

### 4. Generate or Prepare Signing Key

See [Generate A New Keystore for Signing](#generate_keystore) if you hadn't.

### 5. Configure Signing Configuration

Set environment variables `RELEASE_KEYSTORE_FILE`, `RELEASE_KEYSTORE_PASSWORD`, `RELEASE_KEY_ALIAS`, `RELEASE_KEY_PASSWORD` to values for your signing keys; 
Or append `<USER_HOME>\.gradle\gradle.properties` (replace <\*> with yours):

```properties
release.keystoreFile=<path-to-signing-key>
release.keystorePassword=<keystore-password>
release.keyAlias=<key-alias>
release.keyPassword=<key-password>
```

See Also Appendix [Generate Signing Configuration](#generate_signing_properties)

### 6. Build Project

Now, we can build project in variant of `Modern` and `Stable` with Build Type `Release` now. [^f]

[^f]: See more in section _Build Variant_ from [Development Guild](./Developer_Guide.md#build-variants).

```shell
./gradlew assembleModernStableRelease
```

### 7. Locate Output Artifacts

Built apk is in `./app/build/outputs/apk/modernStable/release/` with name `PhonographPlus_<VERSION>-modern-stable-release.apk`

You can run

```shell
./gradlew PublishModernStableRelease
```

to move apk to `./products/ModernStableRelease` and rename to `Phonograph Plus_<VERSION>_ModernStableRelease.apk`

## Appendices

### Generate A New Keystore for Signing <a id="generate_keystore"></a>

Use JDK's `keytool` to generate a new one if you haven't:

```shell
keytool -genkeypair -storepass <keystore-password> -alias <key-alias> -keypass <key-password> -keyalg RSA -keysize 2048 -keystore <your-signing-key-file-path>
```

### Generate Signing Configuration <a id="generate_signing_properties"></a>

For bash users, you can append global `gradle.properties` via these commands (replace <\*> with yours), if Gradle home directory is set to default:

```shell
echo "release.keystoreFile=<your-signing-key-file-path>" >> ~/.gradle/gradle.properties
echo "release.keystorePassword=<keystore-password>" >> ~/.gradle/gradle.properties
echo "release.keyAlias=<key-alias>" >> ~/.gradle/gradle.properties
echo "release.keyPassword=<key-password>" >> ~/.gradle/gradle.properties
```
(_local `gradle.properties` in project root is passible as well_)

Or export environment variables every time:
```shell
export RELEASE_KEYSTORE_FILE=<your-signing-key-file-path>
export RELEASE_KEYSTORE_PASSWORD=<keystore-password>
export RELEASE_KEY_ALIAS=<key-alias>
export RELEASE_KEY_PASSWORD=<key-password>
```