103 lines
4.3 KiB
Markdown
103 lines
4.3 KiB
Markdown
PROJECT BLUEPRINT: lmstudio-bin Maintenance Framework
|
|
|
|
1. Executive Summary
|
|
|
|
Project Name: lmstudio-bin
|
|
|
|
Target Platform: Arch Linux (AUR)
|
|
|
|
Upstream Software: LM Studio (Proprietary AppImage)
|
|
|
|
This project provides an Arch User Repository (AUR) package for LM Studio. It employs a "Maintenance Bridge" architecture to convert dynamic upstream releases into deterministic, security-verified Arch Linux packages while adhering strictly to Arch Linux packaging standards for binary software.
|
|
|
|
2. Core Objectives
|
|
|
|
Correct Naming Convention: Utilize the -bin suffix as mandated by AUR guidelines for software distributed as pre-compiled binaries.
|
|
|
|
Replacement of Legacy Packages: Explicitly provide and conflict with the abandoned lmstudio package to ensure a clean migration path for the community.
|
|
|
|
Security & Determinism: Implement strict SHA256 checksum verification for every release, preventing "moving target" build failures.
|
|
|
|
Full Desktop Integration: Ensure high-resolution icon support, XDG-compliant desktop entries, and taskbar grouping (StartupWMClass).
|
|
|
|
3. Technical Architecture
|
|
|
|
A. The Maintenance Engine (update_package.py)
|
|
|
|
The heart of the project is a Python-based automation script that manages the lifecycle of a release.
|
|
|
|
URL Resolution: Follows the latest redirect to identify the specific build version.
|
|
|
|
Verification: Downloads the AppImage and calculates the SHA256 hash.
|
|
|
|
Template Rendering: Injects metadata into PKGBUILD.template to produce a valid PKGBUILD.
|
|
|
|
Metadata Generation: Automatically updates .SRCINFO for AUR indexing.
|
|
|
|
B. Packaging Logic (PKGBUILD)
|
|
|
|
The build process follows a specific lifecycle to ensure stability:
|
|
|
|
Extraction Stage: Uses --appimage-extract within a temporary sandbox to access internal assets.
|
|
|
|
Icon Strategy (Static Vendoring):
|
|
* Static Icon: The high-resolution (512x512) icon is vendored as `lmstudio.png` in the base repository.
|
|
* Optimization: Icons must be optimized to stay under the 500KB AUR repository blob limit.
|
|
* Rationale: Static vendoring prevents build-time extraction failures and ensures consistent visual presentation across versions without relying on internal AppImage layout stability.
|
|
|
|
Binary Placement: Installs the AppImage to /opt/lm-studio/ and provides a symbolic link at /usr/bin/lm-studio.
|
|
|
|
C. Lifecycle Management (.install)
|
|
|
|
The .install script ensures the host system recognizes changes immediately upon installation, upgrade, or removal by triggering:
|
|
|
|
update-desktop-database (Applications menu)
|
|
|
|
gtk-update-icon-cache (Visual assets)
|
|
|
|
4. Automation Workflow (For Orchestrator Reference)
|
|
|
|
When updating to a new version, the orchestrator should follow this sequence:
|
|
|
|
Sync: Pull latest changes from the AUR remote.
|
|
|
|
Execute: Run ./update_package.py to fetch upstream changes and regenerate files.
|
|
|
|
Validate: * Verify PKGBUILD version matches upstream.
|
|
|
|
Run makepkg -f to test the build locally.
|
|
|
|
Inspect pkg/ directory to ensure icon assets are present at /usr/share/icons/hicolor/512x512/apps/lmstudio-bin.png.
|
|
|
|
Publish: * Refresh .SRCINFO (makepkg --printsrcinfo > .SRCINFO).
|
|
|
|
Commit PKGBUILD, .SRCINFO, lmstudio.desktop, lmstudio.png, and lmstudio-bin.install.
|
|
|
|
Push to origin master.
|
|
|
|
5. Git Hygiene & AUR Constraints
|
|
|
|
* Blob Limit: The AUR imposes a strict 512KB limit on individual file blobs. All vendored assets (like `lmstudio.png`) must be optimized to comply.
|
|
* Tracking Restrictions: Only source-of-truth files and metadata are permitted in the repository. Tracking of `src/` or `pkg/` directories is strictly prohibited.
|
|
* Verification: Use `verify_git_hygiene.sh` to audit the repository state before pushing to the AUR remote.
|
|
|
|
6. Directory Structure
|
|
|
|
.
|
|
├── PKGBUILD # Generated Arch Linux build script
|
|
├── PKGBUILD.template # Blueprint for the maintenance engine
|
|
├── .SRCINFO # AUR metadata index (auto-generated)
|
|
├── lmstudio.desktop # Desktop integration file
|
|
├── lmstudio.png # Static vendored icon (512x512)
|
|
├── lmstudio-bin.install # Post-install hooks for cache clearing
|
|
├── update_package.py # The Maintenance Engine script
|
|
├── verify_git_hygiene.sh # Hygiene enforcement script
|
|
└── LMStudio-bin Blueprint.md # This reference document
|
|
|
|
|
|
7. Maintenance Contacts & Authority
|
|
|
|
Maintainer: madgoat (AUR)
|
|
|
|
Package URL: https://aur.archlinux.org/packages/lmstudio-bin
|