Table Of Contents

Quick Start Guide

Preparation

System requirements

Mac OS X:

  • Snow Leopard
  • Lion
  • Mountain Lion

Xcode: version 3.2.6 or later, we recommend:

  • Xcode 4.2 for Snow Leopard
  • Xcode 4.5.x, Xcode 4.6.x for Lion and Mountain Lion

iOS SDK: SDK 4.0 or later, we recommend SDK 5.0 or later

Deployment Target: iOS 3.0 or later

Installation

For Xcode 4.5.x ~ 4.6.x users

  1. First, make sure your Xcode has installed at the default location: /Applications/Xcode.app
  2. Download an appropriate .dmg file for your Xcode version.
  3. Double-click the downloaded .dmg file, and follow its instructions to install.

After a successful installation, iGC Core should be installed at your home directory ~/Library/iGC. Everything is ready for iGC app development.

To uninstall, run the Uninstall.app in the downloaded .dmg package.

For other Xcode versions

You can download iGC core and compiler patches separately, and install them as described below.

Manually install iGC core

Download the iGC Core, extract it to ~/Library/iGC directory.

~/Library/iGC/include
~/Library/iGC/lib
~/Library/iGC/samples
...

To uninstall iGC core, delete the iGC subdirectory.

Apply patches to Xcode compilers

  1. download all compiler patches (or those required), into a subdirectory devtools.
  2. download and run patch-devtools script, follow its instructions.

For example, run

$ sudo ./patch-devtools -i

to install patches to Xcode at the default location. This script will search under the current directory and the devtools subdirectory, and choose appropriate patches for your Xcode compilers .

To uninstall and restore Xcode files, run:

$ sudo ./patch-devtools -u

If your Xcode was installed at other locations, specify it like this:

$ sudo ./patch-devtools -i -d "/Applications/Xcode-4.6.3.app"

Getting Started: the “Hello World”

Build Settings” of the project

Start Xcode, open an iOS application project, modify the Build Settings of it:

  • (optional) Add ~/Library/iGC/include to “Header Search Paths”

    You can skip this step if you do not use any iGC header files.

  • Add ~/Library/iGC/lib to “Library Search Paths”

  • Add -u __iGC__ -liGC -lstdc++ to “Other Linker Flags”

    You might need to add some other linker flags, see Linker flags.

_images/LinkerFlags.png

For your convenience, there is a .xcconfig file at the iGC/samples subdirectory.

Coding in a GC way

In the section, we are going to demonstrate how to build a full-fledged GC application.

Setup compiler flags

Add a file main.m to the project, modify the Compiler Flags at the Build Phrases tab.

_images/CompilerFlags.png

Because we are going to write an ARC-compatible code with GC enabled (mode ARCGC_C), we add -fobjc-gc compiler flag, with “Objective-C Automatic Reference Counting(CLANG_ENABLE_OBJC_ARC)” already set to “Yes”.

Note

Different types of compiled code can be mixed in a project, including Apple’s MRR and ARC, and iGC specific MRRGC, ARCGC and ARCGC_C.

Write code using iGC

Paste the following ARCGC_C code into main.m in the project.

#import <Foundation/Foundation.h>

#include "hnxgc.h"

@interface Foo : NSObject {
    Foo *next;
}
@end

@implementation Foo
- (void)dealloc {
    printf("Foo(%p) deallocated\n", self);
}

int main() {
    @autoreleasepool {
        Foo * foo = [[Foo alloc] init];

        foo->next = foo;     // make a cycle of references
    }
    // ARC does not reclaim `foo' because of the cycle.

    printf("-- invoke GC collection explicitly --\n");
    HXSystem_gc();          // iGC specific function

    return 0;
}
@end

Build and run, enjoy it!

You may see something like the followings at the console.

2013-05-30 08:51:06.011 iTestARCGC_C[40162:11303] HnxGC garbage collector v3.5-837:856 (release)
    for ObjC started, Copyright 2006-2012 (c) Harnix Technologies Inc., All Rights Reserved.
-- invoke GC collection explicitly --
Foo(0x791c910) deallocated
... 07:51:06.527 [11303] *** HnxGC garbage collector is shut down. ***

As you can see, the object foo, which leaks in ARC, now is collected by iGC. see also: HXSystem_gc, GC and Tuning.

Further readings

Under the ~/Library/iGC/samples directory, you can find iGC sample code which are ready for build and run.

See online URL http://harnixtechnologies.ca/iGC and local directory ~/Library/iGC/docs for more information.