rhodes 2.2.6 → 2.3.0.beta.1

data/doc/synchronization.txt

@@ -0,0 +1,542 @@
+Synchronization with Rhodes
+===
+As we've shown in the [Rhom section](/rhodes/rhom), adding synchronized data via [RhoSync](/rhosync/introduction) to your Rhodes application is as simple as generating a model and enabling a `:sync` flag.  This triggers the internal Rhodes sync system called the **`SyncEngine`** to synchronize data for the model and transparently handle bi-directional updates between the Rhodes application and the RhoSync server.
+
+This section covers in detail how the `SyncEngine` works in Rhodes and how you can use its flexible APIs to build data-rich native applications.
+
+## Sync Workflow
+The `SyncEngine` interacts with RhoSync over http(s) using [JSON](http://www.json.org/) as a data exchange format.  With the exception of [bulk sync](/rhosync/bulk-sync), pages of synchronized data, or "sync pages" as we will refer to them here, are sent as JSON from RhoSync to the `SyncEngine`.  
+
+Below is a simplified diagram of the `SyncEngine` workflow:
+
+<a href="https://img.skitch.com/20110121-8qqyi7n2mg9fampmhcpqb5g9fi.png"><img height="80%" src="https://img.skitch.com/20110121-8qqyi7n2mg9fampmhcpqb5g9fi.png"/></a>
+
+This workflow consists of the following steps:
+
+* `SyncEngine` sends authentication request to RhoSync via [`SyncEngine.login`](#syncengine-api).  RhoSync calls [`Application.authenticate`](/rhosync/authentication) with supplied credentials and returns `true` or `false`.
+
+* If this is a new client (i.e. fresh install or reset), the `SyncEngine` will initialize with RhoSync:
+
+	* It requests a new unique id (client id) from RhoSync.  This id will be referenced throughout the sync process.
+
+	* It will register platform information with RhoSync.  If this is a [push-enabled application](/rhodes/device-caps#push-notifications) application, the `SyncEngine` will send additional information like device push pin.
+
+* `SyncEngine` requests sync pages from RhoSync, one model(or [Rhom](/rhodes/rhom) model) at a time.  The order the models are synchronized is determined by the model's [`:sync_priority`](/rhodes/rhom#property-bag), or determined automatically by the `SyncEngine`.
+
+## Sync Authentication
+When you generate a Rhodes application, you'll notice there is an included directory called `app/Settings`.  This contains a default `settings_controller.rb` and some views to manage authentication with [RhoSync](/rhosync/introduction).
+
+### `login`
+In `settings_controller.rb#do_login`, the `SyncEngine.login` method is called:
+
+	:::ruby
+	SyncEngine.login(
+	  @params['login'], 
+	  @params['password'], 
+	  url_for(:action => :login_callback) 
+	)
+	
+Here login is called with the `login` and `password` provided by the `login.erb` form.  A `:login_callback` action is declared to handle the asynchronous result of the `SyncEngine.login` request.
+
+### `login_callback`
+When `SyncEngine.login` completes, the callback declared is executed and receives parameters including success or failure and error messages (if any).
+
+	:::ruby
+	def login_callback
+      error_code = @params['error_code'].to_i
+      if error_code == 0
+        # run sync if we were successful
+        WebView.navigate Rho::RhoConfig.options_path
+        SyncEngine.dosync
+      else
+        if error_code == Rho::RhoError::ERR_CUSTOMSYNCSERVER
+          @msg = @params['error_message']
+        end
+        
+        if not @msg or @msg.length == 0   
+          @msg = Rho::RhoError.new(error_code).message
+        end
+      
+        WebView.navigate( 
+		  url_for(:action => :login, :query => {:msg => @msg}) 
+		)
+      end  
+    end
+
+This sample checks the login `error_code`, if it is `0`, perform a full sync and render the settings page.  Otherwise, it sets up an error message and re-displays the login page with an error.
+
+
+### `application.rb#on_sync_user_changed`
+If the `SyncEngine` already knows about a logged-in user and a new user logs in, then the `on_sync_user_changed` hook is called (if it exists) before the `login_callback`.  This is useful, for example, if you want to re-initialize personalized settings for a new user.
+
+	:::ruby
+	require 'rho/rhoapplication'
+
+	class AppApplication < Rho::RhoApplication
+	  def initialize
+	    super
+	  end
+	
+	  def on_sync_user_changed
+	    super
+		MyCoolApp.reset_user_preferences!
+	  end 
+	end
+
+**NOTE: If `on_sync_user_changed`, data for all sync-enabled models will be removed.  To remove data for all local models as well:**
+
+	:::ruby
+	def on_sync_user_changed
+	  super
+	  Rhom::Rhom.database_local_reset
+	end
+	
+Other auth-related methods are described in the [`SyncEngine` API section](/rhodes/synchronization#syncengine-api).
+
+## Notifications
+The `SyncEngine` system uses notifications to provide information about the sync process to a Rhodes application.  Notifications can be setup once for the duration of runtime or each time a sync is triggered.  One a sync is processing for a model, notifications are called with parameters containing sync process state.  Your application can use this information to display different wait pages, progress bars, etc.
+
+To set a notification for a model, you can use the following method:
+
+	:::ruby
+	SyncEngine.set_notification(
+	  Account.get_source_id,
+	  url_for(:action => :sync_notify),
+	  "sync_complete=true"
+	)
+	
+Which is the same as:
+
+	:::ruby
+	Account.set_notification(
+	  url_for(:action => :sync_notify),
+	  "sync_complete=true"
+	)
+	
+In this example, once the sync process for the `Account` model is complete, the view will be directed to the `sync_notify` action (with params 'sync_complete=true') if user is on the same page.
+
+**NOTE: In these examples, after the sync is complete the notifications are removed.**
+
+You can also set a notification for all models:
+
+	:::ruby
+	SyncEngine.set_notification(
+	  -1, url_for(:action => :sync_notify), 
+	  "sync_complete=true"
+	)
+	
+**NOTE: This notification will not be removed automatically.**
+
+### Notification Parameters
+When the notification is called, it will receive a variable called `@params`, just like a normal Rhodes controller action.
+
+#### Common Parameters
+These parameters are included in all notifications.
+
+* `@params["source_id"]` - The id of the current model that is synchronizing.
+* `@params["source_name"]` - Name of the model (i.e. "Product")
+* `@params["sync_type"]` - Type of sync used for this model: "incremental" or "bulk"
+* `@params["status"]` - Status of the current sync process: "in_progress", "error", "ok", "complete", "schema-changed"
+
+#### "in_progress" - incremental sync
+* `@params["total_count"]` - Total number of records that exist for this RhoSync source.
+* `@params["processed_count"]` - Number of records included in the sync page.
+* `@params["cumulative_count"]` - Number of records the `SyncEngine` has processed so far for this source.
+
+#### "in_progress" - bulk sync
+* `@params["bulk_status"]` - The state of the bulk sync process: "start", "download", "change_db".
+
+
+#### "error"
+* `@params["error_code"]` - HTTP response code of the RhoSync server error: 401, 500, 404, etc.
+* `@params["error_message"]` - Response body (if any)
+* `@params["error_type"]` - Type of RhoSync adapter error (if exists): "login-error", "query-error", "create-error", "update-error", "delete-error", "logoff-error"
+* `@params["create_error"]` - Array of hashes each containing an "object" (that failed to create) and a corresponding "error_message".
+
+#### "ok"
+* `@params["total_count"]` - Total number of records that exist for this RhoSync source.
+* `@params["processed_count"]` - Number of records included in the last sync page.
+* `@params["cumulative_count"]` - Number of records the `SyncEngine` has processed so far for this source.
+
+#### "complete"
+This status returns only when the `SyncEngine` process is complete.
+
+#### "schema-changed"
+This status returns for bulk-sync models that use [`FixedSchema`](/rhom#fixed-schema) when the schema has changed in the RhoSync server.  
+
+**NOTE: In this scenario the sync callback should notify the user with a wait screen and start the bulk sync process.**
+
+### Notification Example
+Here is a simple example of a sync notification method that uses some of the parameters described above:
+
+	:::ruby
+	def sync_notify
+	  status = @params['status'] ? @params['status'] : ""
+	  bulk_sync? = @params['sync_type'] == 'bulk'
+
+	  if status == "in_progress" 	
+	    # do nothing
+	
+	  elsif status == "complete" or status == "ok"
+	    WebView.navigate Rho::RhoConfig.start_path
+	
+	  elsif status == "error"
+	    err_code = @params['error_code'].to_i
+	    rho_error = Rho::RhoError.new(err_code)
+   
+		if err_code == Rho::RhoError::ERR_CUSTOMSYNCSERVER
+    	  @msg = @params['error_message']
+	    end
+	
+	    @msg = rho_error.message unless @msg and @msg.length > 0   
+
+	    if rho_error.unknown_client?(@params['error_message'])
+	      Rhom::Rhom.database_client_reset
+	      SyncEngine.dosync
+	
+	    elsif err_code == Rho::RhoError::ERR_UNATHORIZED
+	      WebView.navigate( 
+		    url_for(
+			  :action => :login, 
+			  :query => { :msg => "Server credentials expired!" } 
+			)
+		  )                
+	    else
+	      WebView.navigate( 
+		    url_for(
+			  :action => :err_sync, 
+			  :query => { :msg => @msg } 
+			)
+		  )
+	    end    
+	  end
+	end
+
+**NOTE: If the view was updated using AJAX calls, this mechanism may not work correctly as the view location will not change from one AJAX call to another.  Therefore, you might need to specify the `:controller` option in WebView.navigate.**
+
+### Sync Object Notifications
+The `SyncEngine` can also send a notification when a specific object on the current page has been modified.  This is useful if you have frequently-changing data like feeds or timelines in your application and want them to update without the user taking any action.
+
+To use object notifications, first set the notification callback in `application.rb#initialize`:
+
+	:::ruby
+	class AppApplication < Rho::RhoApplication
+	   def initialize
+	    super
+
+	    SyncEngine.set_objectnotify_url(
+		  url_for(
+			:controller => "Product",
+			:action => :sync_object_notify
+		  )
+		)
+	   end
+	end
+
+Next, in your controller action that displays the object(s), add the object notification by passing in a record or collection of records:
+	
+	:::ruby
+	class ProductController < Rho::RhoController
+
+	  # GET /Product
+	  def index
+	    @products = Product.find(:all)
+
+	    add_objectnotify(@products)
+	    render
+	  end
+	
+	  # ...
+	
+	  def sync_object_notify
+	    #... do something with notification data ...
+	
+		# refresh the current page
+	    WebView.refresh
+	  end
+	end
+
+**NOTE: If you use `url_for` in your .erb files, then when you select a specific object(s) to view, those objects are added to the object notify map automatically.**
+
+#### Object Notification Parameters
+The object notification callback receives three arrays of hashes: "deleted", "updated" and "created".  Each hash contains values for the keys "object" and "source_id" so you can display which records were changed.
+
+## Binary Data and Blob Sync
+Synchronizing images or binary objects between RhoSync and the `SyncEngine` is declared by having a 'blob attribute' on the [Rhom model](/rhodes/rhom).  Please see the [blob sync section](/rhosync/blob-sync) for more information.
+
+## Filtering Datasets with Search
+If you have a large dataset in your backend service, you don't have to synchronize everything with the `SyncEngine`.  Instead you can filter the synchronized dataset using the `SyncEngine`'s `search` function.
+
+Like everything else with the `SyncEngine`, `search` requires a defined callback which is executed when the `search` results are retrieved from RhoSync.
+
+### Using Search
+First, call `search` from your controller action:
+
+	:::ruby
+	def search
+	  page = @params['page'] || 0
+	  page_size = @params['page_size'] || 10
+	  Contact.search(
+	    :from => 'search',
+	    :search_params => { 
+		  :FirstName => @params['FirstName'], 
+		  :LastName => @params['LastName'], 
+		  :Company => @params['Company'] 
+		},
+	    :offset => page * page_size,
+	    :max_results => page_size,
+	    :callback => url_for(:action => :search_callback),
+	    :callback_param => ""
+	  )
+	  render :action => :search_wait
+	end
+
+
+Your callback might look like:
+	
+	:::ruby
+	def search_callback
+	  status = @params["status"] 
+	  if (status and status == "ok")
+	    WebView.navigate( 
+		  url_for( 
+		    :action => :show_page, 
+		    :query => @params['search_params']
+		  ) 
+		)
+	  else
+	    render :action => :search_error
+	  end
+	end
+	
+**NOTE: Typically you want to forward the original search query `@params['search_params']` to your view that displays the results so you can perform the same query locally.**
+
+Next, the resulting action `:show_page` will be called.  Here we demonstrate using Rhom's [advanced find query syntax](/rhodes/rhom#advanced-queries) since we are filtering a very large dataset:
+
+	:::ruby
+	def show_page
+	  @contacts = Contact.find(
+		:all,
+	    :conditions => { 
+	      {
+		    :func => 'LOWER', 
+		    :name => 'FirstName', 
+		    :op => 'LIKE'
+		  } => @params[:FirstName], 
+	      {
+		    :func => 'LOWER', 
+		    :name=>'LastName', 
+		    :op=>'LIKE'
+		  } => @params[:LastName],
+	      {
+		    :func=>'LOWER', 
+		    :name=>'Company', 
+		    :op=>'LIKE'
+		  } => @params[:Company],
+	    }, 
+	    :op => 'OR', 
+	    :select => ['FirstName','LastName', 'Company'],
+	    :per_page => page_size, 
+	    :offset => page * page_size 
+	  )    
+	  render :action => :show_page
+	end
+
+
+If you want to stop or cancel the search, return "stop" in your callback:
+	
+	:::ruby
+	def search_callback    
+	  if(status and status == 'ok')
+	    WebView.navigate( url_for :action => :show_page )
+	  else
+	    'stop'
+	  end
+	end
+	
+Finally, you will need to implement the `search` method in your source adapter.  See the [RhoSync search method](/rhosync/source-adapters#source-adapter-api) for more details.
+
+## SyncEngine API
+Below is the full list of methods available on the `SyncEngine`:
+
+### `login(login, password, callback)`
+Authenticates the user with RhoSync.  The callback will be executed when it is finished.  See the [authentication section](/rhodes/synchronization#sync-authentication) for details.
+
+	:::ruby
+	SyncEngine.login(
+	  @params['login'], 
+	  @params['password'], 
+	  url_for(:action => :login_callback) 
+	)
+
+### `logout`
+Logout the user from the RhoSync server.  This removes the local user session.  See the [authentication section](/rhodes/synchronization#sync-authentication) for details.
+
+	:::ruby
+	SyncEngine.logout
+
+### `logged_in`
+Returns 1 if the `SyncEngine` currently has a user session, 0 if not.  
+
+	:::ruby
+	if SyncEngine::logged_in == 1
+	  render :action => :index
+	else
+	  render :action => :login
+	end
+
+### `dosync(show_sync_status = true)`
+Start the `SyncEngine` process and display an optional status popup (defaults to true).
+
+	:::ruby
+	SyncEngine.dosync(false)
+	  #=> no status popups are displayed
+
+### `dosync_source(source_id, show_sync_status = true)`
+Star the `SyncEngine` process for a given source_id and display an optional status popup (defaults to true).
+
+	:::ruby
+	SyncEngine.dosync_source(Product.get_source_id, true)
+
+### `lock_sync_mutex`
+Blocking call to wait for `SyncEngine` lock (useful for performing batch operations).
+
+	:::ruby
+	SyncEngine.lock_sync_mutex
+	#... perform blocking tasks...
+	SyncEngine.unlock_sync_mutex
+
+### `unlock_sync_mutex`
+Release the acquired `SyncEngine` lock (make sure you do this if you call `lock_sync_mutex`!).
+
+###	`stop_sync`
+Stops any sync operations currently in progress.
+
+	:::ruby
+	SyncEngine.stop_sync
+	  #=> no callback is called
+
+### `set_notification(source_id, callback_url, params = nil)`
+See the [sync notification section](/rhodes/synchronization#notifications).
+
+### `set_notification(-1, callback_url, params = nil)` 
+Set notification callback for all models. This callback is not removed after the sync process completes.  See the [sync notification section](/rhodes/synchronization#notifications).
+
+### `clear_notification(source_id)`
+Clears the sync notification for a given source id.
+
+	:::ruby
+	SyncEngine.clear_notification(Product.get_source_id)
+
+### `set_pollinterval(interval)`
+Update the `SyncEngine` poll interval. Setting this to 0 will disable polling-based sync.  However, you may still use [push-based-sync](/rhosync/push).
+
+	:::ruby
+	SyncEngine.set_pollinterval(20)'
+	  #=> now polls every 20 seconds
+
+### `set_syncserver(server_url)`
+Sets the RhoSync server address and stores it in [`rhoconfig.txt`](/rhodes/configuration).
+
+	:::ruby
+	SyncEngine.set_syncserver("http://myapp.com/application")
+	  #=> don't forget the '/application' path
+
+### `set_objectnotify_url(url)`
+See the [sync notification section](/rhodes/synchronization#notifications).
+
+### `set_pagesize(size)`
+Set the sync page size for the `SyncEngine`. Default size is 2000. See [the `SyncEngine` workflow](/rhodes/synchronization#syncengine-workflow) for how this is used.
+
+	:::ruby
+	SyncEngine.set_pagesize(5000)
+
+### `get_pagesize`
+Get the current sync page size for the `SyncEngine`. See [the `SyncEngine` workflow](/rhodes/synchronization#syncengine-workflow) for how this is used.
+
+	:::ruby
+	SyncEngine.get_pagesize
+	  #=> 2000
+	
+	SyncEngine.set_pagesize(5000)
+	SyncEngine.get_pagesize
+	  #=> 5000
+
+### `enable_status_popup(false)`
+Enable or disable show status popup. True by default for Blackberry, false for other platforms.
+
+	:::ruby
+	SyncEngine.enable_status_popup(true)
+
+### `set_ssl_verify_peer(true)`
+Enable or disable verification of RhoSync ssl certificates, true by default.
+
+	:::ruby
+	# using a self-signed cert
+	SyncEngine.set_ssl_verify_peer(false)
+
+### `get_user_name`
+Returns current username of the `SyncEngine` session if `logged_in` is true, otherwise returns the last logged in username.
+
+	:::ruby
+	SyncEngine.get_user_name
+	  #=> "testuser"
+
+### `search(*args)`
+Call search on the RhoSync application with given parameters.  See the [search section](#filtering-datasets-with-search) for more details.
+
+	:::ruby
+	# :from 			Sets the RhoSync path that records 
+	#					will be fetched with (optional).
+	#					Default is 'search'.
+	#
+	# :search_params	Hash containing key/value search items.
+	#
+	# :offset 			Starting record to be returned.
+	#
+	# :max_results		Max number of records to be returned.
+	#
+	# :callback 		Callback to be executed after search
+	#					is completed.
+	#
+	# :callback_param	(optional) Parameters passed to callback. 
+	#
+	# :progress_step	(optional) Define how often search callback 
+	#					will be executed with 'in_progress' state. 
+	Contact.search(
+	  :from => 'search',
+	  :search_params => { 
+	    :FirstName => @params['FirstName'], 
+	    :LastName => @params['LastName'], 
+	    :Company => @params['Company'] 
+	  },
+	  :offset => page * page_size,
+	  :max_results => page_size,
+	  :callback => url_for(:action => :search_callback),
+	  :callback_param => ""
+	)
+
+### `search(*args) (multiple sources)`
+Call search on the RhoSync application with multiple source names.  This is useful if your `search` spans across multiple models.
+
+For example:
+
+	:::ruby
+	SyncEngine.search(
+	  :source_names => ['Product', 'Customer'],
+	  :from => 'search',
+	  :search_params => { 
+        :FirstName => @params['FirstName'], 
+        :LastName => @params['LastName'], 
+        :Company => @params['Company'] 
+      },
+	  :offset => page * page_size,
+	  :max_results => page_size,
+	  :callback => url_for(:action => :search_callback),
+	  :callback_param => ""
+	)
+
+
+Parameters are the same as for ModelName.search with an additional parameter:
+
+* `:source_names` - Sends a list of source adapter names to RhoSync to search across.

data/doc/test-log-debug.txt

@@ -0,0 +1,148 @@
+# Testing, Logging, and Debugging 
+
+## Testing
+
+### Adding Unit Tests
+
+When you [generate a model](generator#add-new-model), you will now get an _spec.rb file generated along with your controller.
+
+	Generating with model generator:
+	....
+	[ADDED]  app/Person/person_spec.rb
+
+This file contains tests for your controller and is in the mspec format: [rubyspec.org](http://rubyspec.org/) 
+
+	:::ruby
+	describe "Person" do
+	  #this test always fails, you really should have tests!
+
+	  it "should have tests" do
+	    true.should == false
+	  end
+	end
+
+We use this test format internally as well. You can see our specs for the core framework [here](http://github.com/rhomobile/rhodes/tree/1.4.0/spec/framework_spec/app/spec/) which use many functions of mspec.
+
+To run these tests however, you need the testing framework to be included in your app. To add this, you would run the rhogen task in your application folder:
+
+	:::term
+	$ rhogen spec
+
+You will then see the mspec framework added to your application:
+
+	Generating with spec generator:
+	     [ADDED]  app/SpecRunner
+	     [ADDED]  app/spec
+	     [ADDED]  app/mspec.rb
+	     [ADDED]  app/spec_runner.rb
+
+Finally, add the fileutils and mspec extensions to your build.yml:
+	
+	extensions: ["fileutils", "mspec"]
+
+You are now ready to run the tests. Simply add a link to the SpecRunner controller, and you will get a summary of number of passing/failing tests
+
+In your index.erb:
+	:::html
+	<li><a href="SpecRunner">Run tests</a></li>
+
+A summary of the results will be displayed on the screen.
+
+Detailed results will be displayed in your rholog.txt:
+
+	I 01/15/2010 16:36:33 b0185000                  APP| FAIL: Product - Expected true
+	 to equal false
+
+	apps/app/mspec/expectations/expectations.rb:15:in `fail_with'
+	apps/app/mspec/matchers/base.rb:8:in `=='
+	apps/app/Product/product_spec.rb:5:in `block (2 levels) in <main>'
+	...
+
+And finally, a summary will be printed in rholog.txt as well:
+
+	I 01/15/2010 16:36:33 b0185000                  APP| ***Total:  3
+	I 01/15/2010 16:36:33 b0185000                  APP| ***Passed: 1
+	I 01/15/2010 16:36:33 b0185000                  APP| ***Failed: 2
+
+### Disabling tests
+When you are ready to do a production build of your application, change build.yml's build property to 'release' and the specs will not be included in the binary:
+
+	...
+	vendor: Acme, Inc.
+	build: release
+	...
+
+## Logging
+There are two methods to log messages. 
+
+From any controller you can log using the methods app_info and app_error. These methods take a string and will write that to rholog.txt with the category of your controllers name. See platform specific [build topic](build) to see notes on how to get rholog.txt.
+
+There also is a logging Ruby class called RhoLog. This class has methods info and error which take 2 strings. The first string is the category, the second string is the message.
+
+In rholog.txt the lines appear as follows:
+
+	<Timestamp> <category> | <message>
+
+### RhoError class
+You may find access to the error class useful in logging and reporting:
+
+This class contains error codes and the method message() to translate error code to a text message.
+All callbacks return an error code from this class. The status text in the callback contains some internal error message, so in most cases it should not be exposed to user.
+Currently RhoError contains the following error codes:
+
+	ERR_NONE = 0
+	ERR_NETWORK = 1
+	ERR_REMOTESERVER = 2
+	ERR_RUNTIME = 3
+	ERR_UNEXPECTEDSERVERRESPONSE = 4
+	ERR_DIFFDOMAINSINSYNCSRC = 5
+	ERR_NOSERVERRESPONSE = 6
+	ERR_CLIENTISNOTLOGGEDIN = 7
+	ERR_CUSTOMSYNCSERVER = 8
+	ERR_UNATHORIZED = 9
+
+### Sample
+See [Login/Logout Manager]() as an example.
+
+## Debugging
+
+You can debug your Rhodes app running on OSX using the Rhodes Debugger.
+
+The Rhodes Debugger app is located in [platform/osx/Rhodes Debugger](https://github.com/rhomobile/rhodes/tree/master/platform/osx/Rhodes%20Debugger). An xcode project is located there that you can use to build the debugger.
+
+Launching the debugger, by default it listens for debugger connections over tcp. There is a checkbox to enable scanning using gdb for a local emulator running.
+
+Be aware that debugging using the methods below will have a noticeable performance penalty on your application. GDB performance penalty is incurred when the debugger connects to the application and until the application is relaunched. TCP performance penalty is incurred if the application makes a successful connection to the debugger.
+
+[This video demonstrates debugging using TCP on iPhone and Android](http://www.youtube.com/watch?v=xtpjlIdOdQE).
+
+[This video demonstrates debugging using GDB](http://www.youtube.com/watch?v=dHJ3qvzjcuA).
+
+### TCP debugging
+
+Tcp debugging works across multiple platforms, and can be run from the device.
+
+To enable tcp debugging, you have two make a few small modifications to your application:
+
+Include the extensions net-http and debugger in your build.yml.
+
+	extensions: ["net-http", "debugger"]
+
+Modify your rhoconfig.txt add a line at the bottom debug_host. This should be set to an ip address of the machine that the debugger app is running on that is reachable by the phone or emulator.
+
+	debug_host = '192.168.1.106'
+
+Modify your application.rb. At the top of the application.rb file in your app, after the first require add the line:
+
+	:::ruby
+	require 'debugger'
+
+Then you can launch your application and you should see the text in the bottom left of the debugger change from 'Waiting for Rhodes' to 'Connected'. Once this is connected, browse to your rhodes application and then you can set breakpoints or execute ruby commands.
+
+Once you are done debugging, you should click the disconnect button on the debugger to disconnect the debugger from the app.
+
+### Gdb debugging
+
+Gdb debugging only works when you run the debugger and iphone simulator on the same machine. It only works with the iphone simulator.
+
+There is no changes needed to your application to use gdb debugging. Simply launch the Rhodes Debugger app select the gdb checkbox and then launch your application in the iphone simulator. The debugger will detect your application and connect to it automatically.