Xcode Integration

Xcode Integration

This guide covers integrating Apex into Xcode projects, particularly for macOS applications.

Framework Build

Apex builds as a macOS framework suitable for Xcode integration:

cd apex
mkdir build && cd build
cmake ..
make

The framework will be at build/Apex.framework.

Adding to Xcode Project

Method 1: Framework Reference

1. Drag Apex.framework into your Xcode project
2. Add to "Frameworks, Libraries, and Embedded Content"
3. Set "Embed & Sign" for the framework

Method 2: CMake Integration

If your project uses CMake:

add_subdirectory(apex)
target_link_libraries(your_app Apex)

Objective-C Wrapper

Apex includes an Objective-C wrapper for easy integration:

Files:

• apex/objc/NSString+Apex.h
• apex/objc/NSString+Apex.m

Basic Usage

#import "NSString+Apex.h"

// Convert with default unified mode
NSString *html = [NSString convertWithApex:markdownText];

// Convert with specific mode
NSString *gfmHtml = [NSString convertWithApex:markdownText mode:@"gfm"];
NSString *mmdHtml = [NSString convertWithApex:markdownText mode:@"multimarkdown"];
NSString *kramdownHtml = [NSString convertWithApex:markdownText mode:@"kramdown"];

API

@interface NSString (Apex)

+ (NSString *)convertWithApex:(NSString *)markdown;
+ (NSString *)convertWithApex:(NSString *)markdown mode:(NSString *)mode;

@end

Parameters:

• markdown - Input Markdown text
• mode - Processor mode: @"unified", @"gfm", @"mmd", @"kramdown", or @"commonmark"

Returns: HTML string (autoreleased)

Direct C API Usage

For more control, use the C API directly:

#include <Apex/apex.h>

- (NSString *)convertMarkdown:(NSString *)markdown {
    apex_options opts = apex_options_default();
    opts.pretty = true;

    const char *md = [markdown UTF8String];
    char *html = apex_markdown_to_html(md, strlen(md), &opts);

    if (html) {
        NSString *result = [NSString stringWithUTF8String:html];
        apex_free_string(html);
        return result;
    }

    return nil;
}

Integration Example

Adding to Marked

Here's how to add Apex support to an existing Marked-style application:

1. Add to processor selection:

// In MKConductorTransformer.m or similar
} else if ([processor isEqualToString:@"Apex"]) {
    result = [NSString convertWithApex:text];
} else if ([processor isEqualToString:@"MultiMarkdown"]) {
    result = [NSString convertWithMultiMarkdown:text];
}

2. Add to preferences:

// In processor dropdown
NSArray *processors = @[
    @"MultiMarkdown",
    @"Discount (GFM)",
    @"CommonMark",
    @"Kramdown",
    @"Apex"  // Add this
];

3. Handle custom processor rules:

// In custom processor handling
} else if ([outputString.uppercaseString isEqualToString:@"APEX"]) {
    [defaults setValue:@"Apex" forKey:@"defaultProcessor"];
}

Build Settings

Header Search Paths

Add to "Header Search Paths":

$(SRCROOT)/apex/include

Framework Search Paths

Add to "Framework Search Paths":

$(SRCROOT)/apex/build

Other Linker Flags

If using static library:

-L$(SRCROOT)/apex/build -lapex

Swift Integration

Apex can be used from Swift via the Objective-C wrapper:

import Foundation

// Use Objective-C wrapper
let html = NSString.convert(withApex: markdownText)

// Or with mode
let gfmHtml = NSString.convert(withApex: markdownText, mode: "gfm")

For direct C API access, create a Swift bridging header:

// Bridging header
#import <Apex/apex.h>

// Swift code
func convertMarkdown(_ text: String) -> String? {
    let opts = apex_options_default()
    let cString = text.utf8CString
    guard let html = apex_markdown_to_html(cString, text.utf8.count, &opts) else {
        return nil
    }
    defer { apex_free_string(html) }
    return String(cString: html)
}

Troubleshooting

Framework Not Found

Ensure the framework is:

1. Added to "Frameworks, Libraries, and Embedded Content"
2. Set to "Embed & Sign"
3. Framework search paths are correct

Linker Errors

• Ensure Apex.framework is linked
• Check framework search paths
• Verify architecture matches (arm64 vs x86_64)

Runtime Errors

• Ensure framework is embedded (not just linked)
• Check code signing settings
• Verify framework is built for correct deployment target

Performance

Apex is built on cmark-gfm, which is highly optimized:

• Small documents (< 10KB): < 10ms
• Medium documents (< 100KB): < 100ms
• Large documents (< 1MB): < 1s

The Objective-C wrapper adds minimal overhead.

Related

• C API - Direct C API documentation
• Usage - Basic usage examples
• Modes - Processor mode details