Status

I’m just getting this project set up, so docs and code are buggy and missing until I update this document.

Intro

TiREPL provides the facility for interactive editing of running titanium mobile applications (sometimes called “Live Coding”). This is done using Read Eval Print Loop (REPL) on the running application connected to a client over a network transport layer. Following is a short description of the main components.

ReplServer

The core of TiREPL are iPhone and Android modules that must be installed along with the other modules in the mobile titanium SDK. These modules are native code, Objective-C (for iPhone) and Java (for Android). The main job of the ReplServer is to listen on a configurable port for remote client connections. When it recieves an incoming connection, it starts a REPL session with that remote client. The REPL session accepts javascript code sent by the client and executes it on the local javascript context of the device. It then sends the response of the evaluation back down to the remote client and waits for the remote client to send more code to evaluate.

Transport Layer

For sending data back and forth between the ReplServer on the mobile device and the remote client, a very simple line-oriented protocol is used. This was chosen because it was simple to bootstrap and test using telnet. Feedback on the protocol is welcome- it is pretty ad hoc but it was easy to get started. The transport layer allows a dual-mode operation. For direct telnet connections, you can simply enter raw javascript line-by line. You can also enter more complex data using irc-like commands. These messages are JSON structures encoded as base64 strings terminated by newlines.

Commands

• /q or /quit Kill the current session and disconnect
• /session_id Get the unique session_id for this active session
• /message <base64 encoded JSON message object> Encoded message object sent by the client
• /message_response <base64 encoded JSON message object> Encoded message reply sent back to the client by the REPL server

Messages

Message objects are just JSON dictionaries. The format is as follows:

• Client request messages have the following keys/values:
  • “session-id” - Id of session this message belongs to.
  • “id” Id of this message. Incremental id unique to this session.
  • “type” Message type of this message. Currently there is only eval_src
  • “src” The javascript source we want eval’d on the remote mobile device
• Server response message have the following keys/values:
  • “session-id” Id of session this message belongs to.
  • “id” Id of the message being replied to.
  • “type” Message type of this message. Currently there is only eval_response
  • “status” status code for this evaluation, either ok or error
  • “result” resulting object or exception object of the remote evaluation

Remote clients

Clients can simply be a telnet session connected directly to the raw socket, or a client can provide more features such as input history, error reporting etc using the JSON encoded messaging interface. There is an emacs client interface provided with this project that uses the messaging interface.

Installation

To install these modules, you will need a fully working and recent Titanium Developer installed, as well as a working Xcode and Android developer setup.

Files you may need to edit

• For building for iPhone: replserver_iphone/ReplServer/titanium.xconfig Make sure the file paths and titanium_mobile sdk match your system
• For building for Android: replserver_android/build.xml Make sure the required file paths match your system

Install iPhone module into titanium mobile SDK

shell:

cd replserver_iphone/ReplServer
python ./build.py

You should now have a file: com.evocomputing.replserver-iphone-0.1.zip

Now, copy this file to your Titanium directory: shell:

cp com.evocomputing.replserver-iphone-0.1.zip "/Library/Application Support/Titanium/"

Titanium should pick this up and install it in the correct directory.

Install Android module into titanium mobile SDK

shell:

cd replserver_android/
ant deploy

This will build the titanium-repl.jar, and install it with the other jars in the mobile sdk

Create titanium project that starts the ReplServer module

Add ReplServer module to tiapp.xml

Initial connection

• iPhone
• Android Open local proxy port for emulator using adb command shell shell:

/opt/android-sdk/tools/adb forward tcp:5051 tcp:5051

Usage

See the app.js file in the examples/ReplTest example project for how to integrate the module in your titanium application.

Example session

shell:

telnet localhost 5061
Trying ::1...
Connected to localhost.
Escape character is '^]'.
Welcome to the ReplTest REPL Server

REPL> win1.backgroundColor = 'red';
red
REPL> replButton.height = 100;
100
REPL> win1.backgroundColor = 'blue';
blue
REPL> win2.backgroundColor = 'green';
green
REPL> /q
Bye!
Connection closed by foreign host.

License

Except where noted, this is all licensed under the Apache License v2, same as Appcelerator Titanium. The emacs lisp code is licensed under the GPL, because it is derived from other GPL’d sources.