237 lines
9.6 KiB
Markdown
237 lines
9.6 KiB
Markdown
# Contributing
|
|
|
|
## Prerequisites
|
|
|
|
- Python 3.11+
|
|
- Make (optional, but recommended)
|
|
- Git
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
# Clone the repository
|
|
git clone https://github.com/RJNY/Obtainium-Emulation-Pack.git
|
|
cd Obtainium-Emulation-Pack
|
|
|
|
# Make your changes to src/applications.json (or use make add-app)
|
|
make validate # check for structural errors
|
|
make test # verify configs resolve to real APKs
|
|
make release # normalize, regenerate README, build release JSONs
|
|
```
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
src/
|
|
applications.json # Source of truth - all app definitions
|
|
scripts/
|
|
validate-json.py # Validates applications.json
|
|
test-apps.py # Live-tests configs resolve to downloadable APKs
|
|
add-app.py # Interactive CLI to add a new app
|
|
generate-table.py # Generates the README table
|
|
generate-readme.py # Stitches markdown files into README
|
|
minify-json.py # Creates release JSON files
|
|
normalize-json.py # Normalize key order and backfill defaults
|
|
release.py # Automated release workflow (tag, push, gh release)
|
|
constants.py # Shared constants and Obtainium source schema
|
|
utils.py # Shared utility functions and .env loader
|
|
pages/
|
|
header.md # README header/intro
|
|
table.md # Generated - app tables (do not edit)
|
|
faq.md # FAQ section
|
|
footer.md # Short section linking here (stitched into README)
|
|
obtainium-emulation-pack-latest.json # Standard release
|
|
obtainium-emulation-pack-dual-screen-latest.json # Dual-screen release
|
|
```
|
|
|
|
## Adding a New Application
|
|
|
|
### Option A: Quick Add (Recommended for GitHub apps)
|
|
|
|
Use the interactive CLI to quickly add a new app:
|
|
|
|
```bash
|
|
make add-app
|
|
```
|
|
|
|
This will:
|
|
|
|
- Prompt you for the GitHub URL
|
|
- Auto-detect the source, author, and app name
|
|
- Ask for the Android package ID and category
|
|
- Generate proper Obtainium settings
|
|
- Add the app to `applications.json`
|
|
|
|
> **Tip:** To find the package ID, open the app in Obtainium - the package ID is displayed directly below the source URL (e.g., `com.example.android`).
|
|
|
|
After running, execute `make release` to regenerate all files.
|
|
|
|
### Option B: Manual Add (For complex configs or non-GitHub sources)
|
|
|
|
#### Step 1: Export the app config from Obtainium
|
|
|
|
1. Open Obtainium on your device
|
|
2. Add the app you want to include (configure it how you want)
|
|
3. Long-press the app and select "Export"
|
|
4. Choose "Obtainium Export" format
|
|
5. Transfer the JSON to your computer
|
|
|
|
#### Step 2: Add the app to applications.json
|
|
|
|
Open `src/applications.json` and add your app to the `apps` array:
|
|
|
|
```json
|
|
{
|
|
"id": "com.example.emulator",
|
|
"url": "https://github.com/example/emulator",
|
|
"author": "example",
|
|
"name": "Example Emulator",
|
|
"preferredApkIndex": 0,
|
|
"additionalSettings": "{...}",
|
|
"categories": ["Emulator"],
|
|
"overrideSource": "GitHub"
|
|
}
|
|
```
|
|
|
|
#### Step 3: Add meta fields (optional)
|
|
|
|
Add a `meta` object to customize how the app appears:
|
|
|
|
```json
|
|
{
|
|
"id": "com.example.emulator",
|
|
"url": "https://github.com/example/emulator",
|
|
"author": "example",
|
|
"name": "Example Emulator",
|
|
"preferredApkIndex": 0,
|
|
"additionalSettings": "{...}",
|
|
"categories": ["Emulator"],
|
|
"overrideSource": "GitHub",
|
|
"meta": {
|
|
"nameOverride": "Example Emu",
|
|
"urlOverride": "https://example-emu.org"
|
|
}
|
|
}
|
|
```
|
|
|
|
#### Step 4: Validate, test, and regenerate
|
|
|
|
```bash
|
|
make validate # check for structural errors
|
|
make test # verify your app config resolves to a real APK
|
|
make release # normalize, regenerate README, build release JSONs
|
|
```
|
|
|
|
## Pre-Commit Checklist
|
|
|
|
Before committing, run `make test` and `make release`, then verify:
|
|
|
|
- [ ] `make test` passes (all app configs resolve to downloadable APKs)
|
|
- [ ] `obtainium-emulation-pack-latest.json` has been updated
|
|
- [ ] `obtainium-emulation-pack-dual-screen-latest.json` has been updated
|
|
- [ ] `README.md` has been updated
|
|
- [ ] The README table shows a friendly application name (use `nameOverride` if not)
|
|
- [ ] The README table links to the correct homepage (use `urlOverride` if not)
|
|
- [ ] Beta apps are excluded with `meta.excludeFromExport: true`
|
|
|
|
## Available Make Commands
|
|
|
|
| Command | Description |
|
|
| -------------------------------- | ----------------------------------------------------------- |
|
|
| `make help` | Show all available commands |
|
|
| `make add-app` | Interactive CLI to add a new app |
|
|
| `make validate` | Validate applications.json (structure, regex, source types) |
|
|
| `make test` | Live-test all app configs resolve to downloadable APKs |
|
|
| `make test-app APP=name` | Live-test a single app by name (partial match) |
|
|
| `make test-verbose` | Live-test all apps with APK URL details |
|
|
| `make release` | Full pipeline: validate, normalize, readme, both JSONs |
|
|
| `make normalize` | Normalize key order and backfill defaults |
|
|
| `make table` | Generate the README table only |
|
|
| `make readme` | Generate README.md from pages |
|
|
| `make minify` | Generate standard release JSON |
|
|
| `make minify-dual-screen` | Generate dual-screen release JSON |
|
|
| `make publish` | Tag, push, and create a GitHub release |
|
|
| `make publish-dry-run` | Preview release notes without publishing |
|
|
| `make publish-from-file FILE=..` | Publish using a previously edited release notes file |
|
|
|
|
## Meta Field Reference
|
|
|
|
These fields in the `meta` object control how apps are processed:
|
|
|
|
| Field | Type | Default | Description |
|
|
| --------------------- | ------ | ------- | ------------------------------------------------------------------- |
|
|
| `excludeFromExport` | bool | `false` | Exclude from both release JSON files. Use for beta/unstable apps. |
|
|
| `excludeFromTable` | bool | `false` | Exclude from the README table. |
|
|
| `includeInStandard` | bool | `true` | Include in standard release. Set `false` for dual-screen-only apps. |
|
|
| `includeInDualScreen` | bool | `true` | Include in dual-screen release. Set `false` for standard-only apps. |
|
|
| `nameOverride` | string | `null` | Override the display name in the README table. |
|
|
| `urlOverride` | string | `null` | Override the homepage link in the README table. |
|
|
|
|
## Categories
|
|
|
|
Apps are organized into categories that appear as sections in the README table:
|
|
|
|
| Category | Description |
|
|
| -------------- | ---------------------------------------------------------------- |
|
|
| `Emulator` | Console/handheld emulators (Dolphin, RetroArch, PPSSPP, etc.) |
|
|
| `Frontend` | Emulator launchers and game library managers (Daijisho, Pegasus) |
|
|
| `Utilities` | Helper apps (Syncthing, OdinTools, LED controllers, etc.) |
|
|
| `PC Emulation` | Windows/PC game layers (Winlator, etc.) |
|
|
| `Streaming` | Game streaming clients (Moonlight, etc.) |
|
|
| `Track Only` | Version tracking without APK downloads (drivers, meta-packages) |
|
|
|
|
An app can belong to multiple categories.
|
|
|
|
## Dual-Screen vs Standard
|
|
|
|
The pack supports two variants:
|
|
|
|
- **Standard** (`obtainium-emulation-pack-latest.json`): For regular Android devices
|
|
- **Dual-Screen** (`obtainium-emulation-pack-dual-screen-latest.json`): For dual-screen devices like LG V60/Velvet
|
|
|
|
Some apps have dual-screen-specific forks (e.g., Cemu, MelonDS). Use the `includeInStandard` and `includeInDualScreen` flags to control which variant(s) include each app.
|
|
|
|
**Why this matters:** Apps with the same Android package ID (`id` field) will conflict in Obtainium. If two apps share an ID (like standard Cemu and dual-screen Cemu), they **must not** both appear in the same JSON file.
|
|
|
|
Example: Standard Cemu excluded from dual-screen, dual-screen fork excluded from standard:
|
|
|
|
```json
|
|
// Standard Cemu - exclude from dual-screen JSON
|
|
{
|
|
"id": "info.cemu.cemu",
|
|
"name": "Cemu",
|
|
"url": "https://github.com/SSimco/Cemu",
|
|
"categories": ["Emulator"],
|
|
"meta": { "includeInDualScreen": false }
|
|
}
|
|
|
|
// Dual-screen Cemu fork - exclude from standard JSON
|
|
{
|
|
"id": "info.cemu.cemu",
|
|
"name": "Cemu",
|
|
"url": "https://github.com/SapphireRhodonite/Cemu",
|
|
"categories": ["Dual Screen"],
|
|
"meta": { "includeInStandard": false }
|
|
}
|
|
```
|
|
|
|
## Choosing the Right Category and Variant
|
|
|
|
Use this decision tree:
|
|
|
|
1. **Is this app device-specific?** (e.g., AYN Thor frontend)
|
|
|
|
- Yes: Set `includeInStandard: false` and use appropriate category
|
|
- No: Continue to step 2
|
|
|
|
2. **Does this app share an ID with another app in the pack?** (e.g., forks, beta builds, dual-screen variants)
|
|
|
|
- Yes: Only one app per ID can be in each release JSON. Options:
|
|
- Use `includeInStandard`/`includeInDualScreen` to split between variants
|
|
- Use `excludeFromExport: true` on the less stable version (e.g., nightly builds)
|
|
- No: App can be in both variants (default)
|
|
|
|
3. **Is this app stable and ready for users?**
|
|
- Yes: Include normally
|
|
- No: Set `excludeFromExport: true` (still visible in table but not in release JSONs)
|