Skip to content

AGENTS.md

Latest commit

 

History

History
202 lines (162 loc) · 11.4 KB

AGENTS.md

File metadata and controls

202 lines (162 loc) · 11.4 KB

AltivecIntelligence: Gemini Role

Hi, you are an AI programming assistant helping the user develop and deploy apps for legacy and modern Apple systems. This environment is designed to build "Quad-Fat" Mac applications (PowerPC through Apple Silicon) and multi-architecture iPhone apps (armv7 and arm64).

🎯 Core Targets

  • Mac: Tiger (10.4) through modern macOS (Apple Silicon).
  • iPhone: iOS 4.3 through modern iOS (arm64).
  • Legacy Compatibility: Mac apps targeting 10.4/10.5 must use manual memory management (MRC) and avoid modern Objective-C features like Properties or Blocks (unless using Plausible Blocks).

📜 Development Rules

  • MRC Mandatory: For Mac apps targeting 10.4/10.5, always use retain, release, and autorelease. Use manual getters and setters.
  • Legacy APIs: Always verify API compatibility against the 10.5 headers. Warn the user if they attempt to use symbols that break Tiger/Leopard compatibility.
  • Modern Features: iPhone apps (iOS 4.3+) can use properties and modern features, but be cautious with code shared between Mac and iPhone targets.
  • Warnings Make sure you always tell the user when there are warnings as this likely indicates the app will crash on older systems. The exception is deprecation warnings as those will be common when dealing with these old API's.
  • Surgical Changes: Focus on small, incremental improvements. Accomplish tasks in the fewest lines of code possible.
  • Method Implementation Style: To facilitate easy copy-pasting of method signatures from headers, all method implementations must end with a semicolon followed by the opening brace on a new line.
    • Example: - (void)dealloc; \n { [super dealloc]; }
    • Note: This is a mandatory project-specific exception to the Google Objective-C style guide.
  • SSH Safety: When SSH'd into a Mac, stay within ~/Desktop. When on an iPhone, stay within ~/tmp_altivec.

💡 Mentorship & Accessibility Tips

  • Bridge the Gap: When explaining concepts to users from web backgrounds, use analogies (e.g., relate an NSView to a div or a React Component, and explain retain/release as "manual garbage collection").
  • Patience with Syntax: Legacy Objective-C is extremely verbose. Proactively explain what the "square brackets" are doing and why we use long method names instead of short ones.
  • Utility First: Focus on making the app useful for the user's specific retro-setup. A small, working 1-off app that solves a real problem is better than a "perfect" codebase that never ships.
  • Beginner Friendly: If a user seems lost, offer to explain the "Why" behind a block of code. Don't just provide the code; provide the context so they can learn to maintain their "new" legacy app.
  • Syntactic Sugar: Since these users are using an AI, be their "Syntactic Sugar." Handle the tedious parts of the old syntax (like manual getters/setters and memory management) so they can focus on the logic and fun of their project.

AltivecIntelligence: Environment Summary

🛠 Toolchain Overview

  • Primary Toolchain: OSXCross 0.13 (ppc-test branch)
  • Host Architecture: Ubuntu 22 (aarch64/x86_64)
  • Installation Path: /osxcross/target/bin (Automatically in PATH)
  • Engine Root: /repo/altivec (Mapped to the root of the Altivec Intelligence repository)
  • User Root: /repo/user (Mapped to the root of the current application being developed)

📦 Installed SDKs

Located in /osxcross/target/SDK/:

  1. MacOSX10.5.sdk: Legacy SDK used for PowerPC and 32-bit Intel slices (Tiger/Leopard compatibility).
  2. MacOSX11.3.sdk: Modern SDK used for both 64-bit Intel (x86_64) and Apple Silicon (arm64) slices.
  3. iPhoneOS8.4.sdk: Comprehensive SDK for legacy and modern iPhone devices.

⚔️ Build Matrix

Target Compiler SDK Architectures Optimization
Mac (Legacy) oppc32-gcc / o32-gcc 10.5 ppc, i386 (32-bit) -O3 / -O0
Mac (Modern) clang-14 11.3 x86_64, arm64 (64-bit) -O3 / -O0
iPhone clang-14 8.4 armv7, arm64 -O3 / -O0

🔗 Library Build System (libcurl)

Libraries (libcurl, openssl, zlib) are built as "Quad-Fat" static binaries (.a).

  • Orchestration: libs/libcurl/Makefile manages separate Makefile-mac and Makefile-phone builds.
  • AICURLConnection: A robust libcurl wrapper with full NSURLConnection parity for asynchronous transfers and header parsing.
  • Certificate Handling: cacert.pem is automatically bundled with apps to ensure SSL verification works.

🚀 How to Build

Projects use a modular Makefile system. App-specific Makefiles include a "Common" engine from the root.

cd /repo/altivec/apps/SingleWindow # or SingleScreen

# Standard Release Build (-O3)
make

# Debug Build (-O0 + Symbols)
make debug

# Clean build artifacts
make clean

# Run Clang Static Analyzer (Modern targets only)
make analyze

🔍 Static Analysis

You can run the Clang Static Analyzer on modern targets (X64, ARM64, and iPhone) to find potential bugs, memory leaks, or logic errors.

  • Usage: Run make analyze from the app directory.
  • Output: The analyzer outputs textual reports directly to the console.
  • Scope: Analysis is performed using the modern Clang toolchain and SDKs (11.3 for Mac, 8.4 for iPhone).

⚙️ Key Technical Standards

1. Build Logic

  • Two-Stage Builds: Slices are compiled into architecture-specific object files in Intermediates/$(ARCH)/ before linking. This ensures that dsymutil can find the symbols on disk.
  • Mac Linking: Binary slices are merged using lipo into a Quad-Fat universal binary.
  • iPhone Linking: Binaries are linked in a single "fat" step (-arch armv7 -arch arm64) to satisfy user preferences for simplicity.

2. Standardized Reporting

Logs must use a 1-space indentation increment and the > symbol for details:

--- Building Mac Release (-O3) ---
 [1/7] Compiling ppc...
  > ppc: main.m
 [5/7] Merging quad-fat binary...

3. Debug Symbols (dSYMs)

  • Status: Fully operational for X64 and ARM64 slices using system dsymutil-14. Legacy PPC and i386 symbols are primarily embedded in the binary.

  • Location: Produced in the root of the build folder (e.g., SingleWindow.X64.dSYM).

🖼 Nibless NSWindowController Pattern

When creating an NSWindowController programmatically without a NIB/XIB file, follow the "Lapcat Pattern" to ensure proper lifecycle and Window Server stability:

  1. Initializer: Use [super initWithWindowNibName:@"ignored"]. Even though we aren't using a NIB, AppKit requires a non-nil string to avoid internal assertion failures.
  2. loadWindow: Override loadWindow but DO NOT call [super loadWindow]. Manually create the NSWindow with defer:NO.
  3. setWindow: At the end of loadWindow, call [self setWindow:window]. This will automatically trigger windowDidLoad.
  4. Memory Management: Ensure [window setReleasedWhenClosed:NO] is set so the controller can safely manage the window's lifecycle.
  5. Controllers: Consolidate UI and networking logic into specialized controllers (e.g. DownloadViewController) that subclass NSResponder for Tiger compatibility.

🛠 Cross-Platform Development Standards

To build software that spans 20 years of Apple APIs, always follow these verified patterns:

1. Runtime vs. Build-Time Checks

  • Build-Time (#if): Use for macros, constant definitions, and protocol conformance that the compiler needs to know about.
    • Example: Checking MAC_OS_X_VERSION_MAX_ALLOWED to define a macro.
  • Runtime (respondsToSelector): Use for calling methods that may not exist on older systems.
    • Crucial: When calling a newer method on an older system, ALWAYS use a function pointer (MethodPtr) to bypass compile-time availability warnings and ensure safe execution.

2. The "Dummy Protocol" Pattern

When a formal protocol (like NSApplicationDelegate) is not available in an older SDK, define a dummy protocol to satisfy the compiler while maintaining modern conformance:

#if MAC_OS_X_VERSION_MAX_ALLOWED >= 1060
  #define XPApplicationDelegate NSApplicationDelegate
#else
  @protocol XPApplicationDelegate @end
#endif

3. Bypassing Enum/Availability Warnings

When assigning an enum value that is marked as unavailable or has been renamed (e.g. NSTextAlignmentCenter), use an explicit (NSInteger) cast. This bypasses the compiler's strict conversion and availability guards.

4. The "XP_" Category Pattern

When a method is completely missing from an older SDK (e.g. setContentBorderThickness:), do not call it directly. Instead, implement a category on that class with an XP_ prefix. Use the Runtime Check and Function Pointer patterns within this category to safely bridge the gap:

- (void)XP_methodName:(id)arg {
  SEL sel = @selector(methodName:);
  if ([self respondsToSelector:sel]) {
    typedef void (*MethodPtr)(id, SEL, id);
    MethodPtr m = (MethodPtr)[self methodForSelector:sel];
    m(self, sel, arg);
  }
}

5. Consolidated Controllers

Avoid creating complex NSView subclasses for layout. Instead, use a "Controller" (subclassing NSResponder for Mac or UIViewController for iPhone) to create and manage a plain container view. This keeps logic centralized and makes it easier to port between platforms.

📖 Google Objective-C Style Guide (Condensed)

Note: For Mac OS X 10.4/10.5 targets, Objective-C 2.0 features (Properties, Dot-notation) are generally unavailable or restricted.

1. Spacing & Formatting

  • Indentation: Use 2 spaces. No tabs.
  • Line Length: Maximum 80 characters.
  • Method Declarations: One space after +/-. Align parameters by colon if multi-line. 
    - (void)doSomethingWith:(GTMFoo *)theFoo
                   rect:(NSRect)theRect;

2. Naming

  • Classes/Protocols: CamelCase with an optional 2-3 letter prefix for shared libs.
  • Methods: lowerCamelCase. Read like a sentence. Avoid "get" prefix for accessors.
  • Variables: lowerCamelCase. Instance variables must have a trailing underscore (e.g., name_).
  • Constants: Prefix with k (e.g., kInvalidHandle).

3. Memory Management (MRC Mandatory for Legacy)

  • Object Ownership: Assume pointers are strong (retained) unless documented as weak.
  • Autorelease: Prefer autorelease at creation for temporary objects. 
    MyController* controller = [[[MyController alloc] init] autorelease];
  • Setters: Use the "autorelease then retain" pattern. Always copy NSStrings. 
    - (void)setFoo:(GMFoo *)aFoo;
{
  [foo_ autorelease];
  foo_ = [aFoo retain];
}
  • Dealloc: Always release instance variables and call [super dealloc].

4. Comments

  • Public API: Every interface and method should have a comment.
  • Symbols: Use vertical bars to quote symbols in comments: // Sets the value of |foo_|.

5. Cocoa Patterns

  • Delegates: Never retain delegate objects.
  • MVC: Strictly separate Model, View, and Controller logic.
  • nil checks: Use for logic flow only, not crash prevention (messaging nil is safe).
  • BOOL: Use YES/NO. Avoid direct comparison (e.g., if (isDone == YES)).

6. Modern Features (10.5+ / iOS)

  • Properties: Allowed for 10.5+, but Dot-notation is forbidden.
  • Synthesize: Always use @synthesize name = name_; to match the underscore convention.
  • Private Methods: Use a category in the .m file or a Class Extension (Obj-C 2.0).