carbon2cocoa

A command-line tool to convert legacy Carbon HIToolbox Interface Builder files (.xib and .nib) to modern Cocoa format that can be opened and edited in current versions of Xcode.

Overview

Apple's Interface Builder originally supported two frameworks for macOS UI development:

• Carbon (HIToolbox) - The classic Mac OS API, deprecated since macOS 10.8
• Cocoa (AppKit) - The modern macOS API

Old projects created with Carbon Interface Builder use XIB/NIB files with Carbon-specific element types. Modern versions of Xcode cannot open these files directly.

This tool converts Carbon XIB and NIB files to equivalent Cocoa XIB format, preserving:

• Window definitions and properties
• Menu bar structure
• UI controls (buttons, checkboxes, text fields, sliders, etc.)
• Control frames and basic properties

Supported Input Formats

Format	Description	File Extension
Carbon XIB	Modern Carbon format (Interface Builder 3.x)	.xib
Carbon NIB	Legacy Carbon format (package/directory)	.nib/

Carbon XIB Files

Identified by document type com.apple.InterfaceBuilder3.Carbon.XIB. Contains IBHI* classes (IBHIWindowTemplate, IBHIButton, etc.) with base64-encoded strings.

Carbon NIB Packages

Directory bundles containing objects.xib, classes.nib, and info.nib. Uses IBCarbon* classes (IBCarbonWindow, IBCarbonButton, etc.) with plain text strings.

Supported Conversions

Carbon Element	Cocoa Element	Notes
IBHIWindowTemplate / IBCarbonWindow	NSWindow	Title, frame, style mask preserved
IBHIRootControl / IBCarbonRootControl	NSView	Content view container
IBHIButton / IBCarbonButton	NSButton	Push button style
IBHICheckBox / IBCarbonCheckBox	NSButton	Checkbox style
IBHIStaticText / IBCarbonStaticText	NSTextField	Non-editable label
IBHIEditText / IBCarbonEditText	NSTextField	Editable text field
IBHISlider / IBCarbonSlider	NSSlider	Linear slider
IBHISeparator / IBCarbonSeparator	NSBox	Separator line
IBHIPopUpMenu / IBCarbonPopupButton	NSPopUpButton	Popup menu button
IBHIMenu / IBCarbonMenu	NSMenu	Menu bar menus
IBHIMenuItem / IBCarbonMenuItem	NSMenuItem	Menu items with shortcuts

Quick Start

Installation (Recommended)

# Clone or extract the source
cd carbon2cocoa

# Run the installer
./install.sh

# Or install to a custom location
./install.sh --prefix=$HOME/.local

The installer will:

1. Detect your operating system (macOS, Linux, FreeBSD)
2. Check for required build tools (C compiler, make)
3. Offer to install missing prerequisites
4. Build the application
5. Install to /usr/local/bin (or custom prefix)
6. Install the man page

Manual Build

# Build
make

# Install manually
sudo make install

# Or install to custom location
make install PREFIX=$HOME/.local

Usage

# Convert a Carbon XIB file
carbon2cocoa main.xib

# Convert a Carbon NIB package
carbon2cocoa main.nib

# Specify output filename
carbon2cocoa main.xib output.xib

# Show help
carbon2cocoa --help

# Show version
carbon2cocoa --version

Example Output

$ carbon2cocoa main.nib
NIB package detected: main.nib
Reading: main.nib/objects.xib
Format: Carbon NIB (legacy)
Parsing...
  Found 10 window(s)
  Found 8 menu(s)
    Window: "MAFFia" (0 controls)
    Window: "About MAFFia" (1 controls)
    Window: "Preferences" (9 controls)
    ...
Generating Cocoa XIB...
Writing: main_cocoa.xib
Conversion complete!
  Output size: 85187 bytes

How It Works

1. Detect - The tool determines whether the input is a Carbon XIB file, NIB package, or unsupported format.

2. Parse - The XML structure is parsed, extracting windows, menus, and controls into an internal document representation.

3. Map - Carbon UI elements are mapped to their Cocoa equivalents. Properties like titles, frames, and states are preserved.

4. Generate - A new Cocoa XIB file is generated with the modern XML structure expected by Xcode.

Base64 Decoding (XIB Format)

Carbon XIB files often store text strings (titles, labels) as base64-encoded UTF-8. The tool handles:

• Standard base64 decoding
• Truncated base64 strings (common in old Interface Builder files)
• Trailing control character removal

Limitations

1. No Action Bindings - Carbon uses HICommands for event handling, which has no direct Cocoa equivalent. You must manually reconnect actions in Xcode after conversion.

2. Custom Views - Custom Carbon controls or views are not converted. They appear as empty containers.

3. Advanced Properties - Some Carbon-specific properties (like command IDs) are not preserved as they have no Cocoa equivalent.

4. Bindings - Cocoa Bindings configurations cannot be inferred from Carbon event handlers.

Post-Conversion Steps

After converting a Carbon XIB/NIB file:

1. Open in Xcode - The converted XIB should open without errors.

2. Review Layout - Check that control positions and sizes look correct.

3. Reconnect Actions - Use Xcode's Interface Builder to connect buttons, menu items, and other controls to your code.

4. Update Code - If porting a Carbon application, you'll also need to convert your event handling code from Carbon Events to Cocoa target-action or delegate patterns.

Uninstallation

# Using the installer
./install.sh --uninstall

# Or using make
sudo make uninstall

File Structure

carbon2cocoa/
├── carbon2cocoa.h    # Header with types and function declarations
├── main.c            # Command-line entry point
├── util.c            # String buffer and utility functions
├── base64.c          # Base64 decoding with truncation handling
├── xmlparser.c       # Simple XML parser
├── parser.c          # Carbon XIB/NIB document parser
├── generator.c       # Cocoa XIB XML generator
├── Makefile          # Build configuration
├── install.sh        # Installation script
├── carbon2cocoa.1    # Man page
└── README.md         # This file

Platform Support

Platform	Status	Notes
macOS	✅ Tested	Primary target platform
Linux	✅ Tested	Full support
FreeBSD	⚠️ Untested	Should work
Windows	⚠️ Untested	May work with MSYS2/Cygwin

See Also

• man carbon2cocoa - Manual page with full documentation
• Cocoa Application Tutorial
• Interface Builder Help
• Carbon to Cocoa Transition Guide (archived)