MagicalRecord Deployment and Usage Guide

Prerequisites

• iOS/macOS Development Environment: Xcode 9.0 or later
• Objective-C Knowledge: MagicalRecord is an Objective-C library for Core Data
• Core Data: Basic understanding of Core Data concepts and NSManagedObjectContext
• CocoaPods (Recommended): For easy dependency management in iOS/macOS projects

Installation

Using CocoaPods (Recommended)

1. Add MagicalRecord to your Podfile:

   pod 'MagicalRecord'
   

2. Run the following command in your project directory:

   pod install
   

3. Open your project using the .xcworkspace file generated by CocoaPods.

Manual Installation

1. Clone the MagicalRecord repository:

   git clone https://github.com/magicalpanda/MagicalRecord.git
   

2. Add the MagicalRecord source files to your Xcode project:

   • Drag and drop the MagicalRecord folder into your Xcode project navigator
   • Ensure "Copy items if needed" is checked
   • Add the files to your target

3. Import MagicalRecord in your code:

   #import "MagicalRecord.h"
   

Configuration

Core Data Stack Setup

MagicalRecord requires you to set up your Core Data stack. Here's a basic setup:

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    [MagicalRecord setupCoreDataStackWithAutoMigratingSqliteStoreNamed:@"YourDataModel.sqlite"];
    return YES;
}

Environment Variables

MagicalRecord doesn't require specific environment variables, but you should configure your Core Data model name and store type based on your application needs.

Build & Run

Development

1. Open your Xcode project workspace (.xcworkspace if using CocoaPods)
2. Select your target scheme
3. Choose a simulator or connected device
4. Click the Run button or press Cmd+R

Production

1. Ensure your Core Data model is properly configured
2. Set up proper error handling for Core Data operations
3. Consider using background contexts for heavy operations
4. Build for distribution using Xcode's archive feature

Deployment

MagicalRecord is a library that runs on iOS and macOS devices, so deployment follows standard iOS/macOS app deployment procedures:

1. App Store Distribution:

   • Use Xcode's Archive feature
   • Upload to App Store Connect
   • Submit for review

2. Enterprise Distribution:

   • Use Xcode's Archive feature
   • Export as Enterprise build
   • Distribute through your enterprise distribution method

3. Ad Hoc Distribution:

   • Use Xcode's Archive feature
   • Export as Ad Hoc build
   • Distribute to registered devices

Usage Examples

Basic Fetching

// Simple fetch
NSArray *people = [Person MR_findAll];

// Fetch with conditions
NSArray *peopleNamedJohn = [Person MR_findByAttribute:@"firstName" withValue:@"John"];

// Fetch with sorting
NSArray *peopleSorted = [Person MR_findAllSortedBy:@"lastName" ascending:YES];

Creating Entities

Person *person = [Person MR_createEntity];
person.firstName = @"John";
person.lastName = @"Doe";

Deleting Entities

[person MR_deleteEntity];
[[NSManagedObjectContext MR_defaultContext] MR_saveToPersistentStoreAndWait];

Saving Context

[[NSManagedObjectContext MR_defaultContext] MR_saveToPersistentStoreAndWait];

Troubleshooting

Common Issues

1. "NSInvalidArgumentException: Unable to load NSPersistentStoreCoordinator"

   • Solution: Ensure your Core Data model name matches what you passed to setupCoreDataStackWithAutoMigratingSqliteStoreNamed:

2. Performance Issues with Large Datasets

   • Solution: Use background contexts with MR_contextWithParent: and perform operations asynchronously

3. Data Not Persisting

   • Solution: Ensure you're calling MR_saveToPersistentStoreAndWait on the appropriate context

4. Threading Issues

   • Solution: Always use the context associated with the current thread. MagicalRecord provides thread-safe contexts

5. Migration Failures

   • Solution: Use setupCoreDataStackWithAutoMigratingSqliteStoreNamed: for automatic migrations, or implement custom migrations for complex schema changes

Debug Logging

Enable MagicalRecord logging for debugging:

[MagicalRecord setLoggingLevel:MagicalRecordLoggingLevelVerbose];

Testing

When writing unit tests, use an in-memory store:

[MagicalRecord setupCoreDataStackWithInMemoryStore];
// Run your tests
[MagicalRecord cleanUp];

Migration Issues

For complex data model changes, consider using custom migrations instead of automatic migrations. Implement NSPersistentStoreCoordinator migration policies for fine-grained control over data transformation during schema changes.