= Building iOS framework

You can build Gauche as an iOS framework, so that you can evaluate
Gauche code within iPhone and iPad app.  This is still an experimental
feature, so cross your fingers to proceed.

Note: It doesn't mean you can build iPhone app with Gauche -- the
created framework doesn't know anything about ObjC or other
runtime on iOS, so although you can use most of Gauche functionalities
including system functions, you can't create, say, `UIViewController`
from Gauche code.  We're working on that part and it would be a
separate framework.

1. Build and install Gauche on your macOS machine as usual.
The build script for iOS needs the HEAD version of Gauche which
is running on macOS.

2. In `$(top_srcdir)`, run `src/cross-compile-ios.scm`:
+
[source,console]
----
$ gosh src/cross-compile-ios.scm
----
+
This runs cross compiler for various arm architectures and
x86 (for the emulator), link them together and put the resulting
framework under `build-ios/Gauche-iOS-core.framework`.

3. You can just copy `Gauche-iOS-core.framework` to wherever
suits you.

Now, the following steps are to use Gauche inside iOS app:

1. In your App, add `Gauche-iOS-core.framework` in the framework
section.  You also need to add libraries Gauche depends on --
typically it's `libz` and `libiconv`.

2. You have to call initialization routine before any other
Gauche functions.  We'd suggest to call it in ``AppDelegate``'s
`application:didFinishLaunchingWithOptions`.  You need these
two imports near the beginning of `AppDelegate.m`.
+
[source,objc]
----
#import <Gauche-iOS-core/gauche.h>
#import <Gauche-iOS-core/gauche/static.h>
----
+
And in `application:didFinishLaunchingWithOptions` method,
call:
+
[source,objc]
----
SCM_INIT_STATIC();
----
+
This sets up Gauche runtime.

3. For other files, you only need to include `gauche.h`:
+
[source,objc]
----
#import <Gauche-iOS-core/gauche.h>
----
+
And you can call Gauche API.
+
NB: Gauche requires Gauche VM to be attached to the thread
the Gauche API is called.  If you're in a thread that iOS created,
it's likely that there's no Gauche VM.  You should call
`Scm_AttachVM()` within the thread (but that feature is way less
tested; expect some rough road.)
