In the first post in this series on TiShadow, we covered TiShadow’s component architecture. In this post we will cover the basic usage of TiShadow for accelerating our Titanium development process.
TiShadow offers a number of useful capabilities but the thing that strikes you first is how fast the build and deployment is to connected TiShadow apps. The consequence of this is a vastly faster edit/compile/test loop while developing applications.
As an example, I built a simple Titanium Alloy application containing a single window with a scrollable view containing three other views. I built and deployed that application to the iOS simulator using the standard approach and then by running the TiShadow app on the iOS simulator and using TiShadow to build and deploy. The time from starting the build until the application came up on the simulator went from 68 sec down to 3 sec!
I then made a minor modification to the application by setting the layout on View 1 to vertical and adding a couple of buttons to the View. Once again, comparing the standard incremental build and deploy to that of using TiShadow resulted in a drop from 19 sec down to less than 2 sec.
Just as great is the ability to deploy to multiple connected TiShadow apps at the same time. Rather than having to sequentially build and deploy to your set of test devices (various smartphones and tablets) you can deploy to all of them concurrently. We know that we have to test on a variety of devices and now we can very rapidly do that as well.
We will provide more motivation in later posts when we talk about using TiShadow to perform Jasmine tests and to enhance your ability to deliver beta updates of your applications.
You basically have two options for installing TiShadow, either via the NPM (the Node Package Manager) repository or by cloning a copy from GitHub. The basic difference is that working from a clone of the GitHub repository will allow you to have the latest and greatest version at the expense of a very slightly more involved installation. Note that in either case you will need to have already installed Node.js version 0.8.x or later, which is required to run TiShadow.
Installing from NPM repository
With the npm tool you have the option of installing the TiShadow package in the local directory or into a global shared location (typically under /opt/local on Mac OS X and Linux). You are going to want to go with the global installation as this is a general purpose tool that should be shared for all of your Titanium projects.
To install into the privileged global location the installation command needs to be run as a privileged user: sudo npm install -g tishadow
It will take a little while to install and build some of the dependencies. Make sure that the installation location of the tishadow executable (typically /opt/local/bin on Mac OS X and Linux) is in your search path so that you can simply type tishadow to execute the tool. Now type tishadow at the command prompt and you should see the top level help showing the list of sub-commands available for execution.*
Installing from GitHub
The process for installing from GitHub is very similar to installation from NPM with the addition of the need to clone the repository locally using Git.
Choose an installation directory to clone the repository and type git clone firstname.lastname@example.org:dbankier/TiShadow.git. Once the repository has been cloned locally, move to the new TiShadow directory and type sudo npm install -g. This will build and install the TiShadow package as in the previous section.
Follow the remainder of the instructions from the last paragraph in ‘Installing from NPM repository’.
Starting a Local TiShadow Server
Now that we have installed TiShadow we can easily start the TiShadow server on the local machine. No configuration is required if you are happy with the default behavior of binding to port 3000 on the the primary IP address and the loopback interface. To connect to a different port or IP address it is necessary to provide them as command line options, e.g. tishadow server -p
The server has an command line option to force the use of XHR long polling in situations where web sockets are not supported (this should not be an issue when running locally). This may be necessary if you deploy your TiShadow server to a hosting service that does not currently support web sockets.
The TiShadow server dumps out status, connected TiShadow app logging statements and error/exception messages to the console.
Creating, Building and Deploying TiShadow app
Our next task is to create a TiShadow skeletal app that can be deployed to connected devices, simulators and emulators.
Start off by creating a directory to store the TiShadow app. For this tutorial we will use ShadowApp. To create the skeletal TiShadow app type tishadow app -d ShadowApp. The TiShadow app creator will request an application ID for the new app and then create the app in the ShadowApp directory. Note that the application created is a classic Titanium app (not Alloy).
The TiShadow app is built and deployed to connected devices and simulator/emulators using the standard Titanium development procedures. If building using Titanium or Appcelerator Studio, you will first need to import the ShadowApp mobile project (File → Import).
Once ShadowApp has been deployed it can be started and then configured to connect with a running instance of TiShadow server.
The image on the right shows the TiShadow app running on the iOS simulator with the startup screen configuration set to connect to the TiShadow server listening on the loopback interface at port 3000 (default). The Room field can be ignored for now but will be discussed in a later post when we talk about multiple sessions running on the TiShadow server.
Building and Deploying Application Bundles to Target Devices
Having now started a TiShadow server and having connected with one or more TiShadow apps, the next step is to build and deploy an application bundle to run on the connected TiShadow apps. For this tutorial we will demonstrate using the simple Alloy application that was used for the initial performance tests. Clone the application with Git by typing git clone https://github.com/joliva/ShadowTest.git.
If the application is an Alloy application (which this one is), you first need to run the Alloy compiler which processes all of the Titanium Alloy constructs to yield a classic Titanium application. It is necessary to pass an option to the Alloy compiler to inform it of the target platform (e.g. ios or android), so that the compiler can include platform specific layout elements, styling and code segments and exclude those for other platforms. Type the following to use Alloy to compile for iOS: *alloy compile -c platform=ios* while in the ShadowTest directory.
Let’s modify ShadowTest like was done for the performance tests to add a couple of buttons to View 1. You need to modify the index.xml file to look like this:*
Since we have already performed a full build with TiShadow it is only necessary to do an incremental build, but first we must run the Alloy compiler as was done previously. Now we can perform the incremental build and deploy by typing *tishadow run -u* (for update). That was super fast and only needed to bundle a single file to update the application running on the connected TiShadow apps.
It is sort of a pain to have to continually type out the Alloy and TiShadow commands each time. I recommend that you create some aliases to simplify the process. Here are some that I use:
- alias ac=’alloy compile -c platform=ios’
- alias acb=’ac && b2i’
- alias act=’ac && tishadow run’
- alias actu=’ac && tishadow run -u’
- alias aca=’alloy compile -c platform=android’
- alias acat=’aca && tishadow run’
- alias acatu=’aca && tishadow run -u’
Default configuration, Viewing Logs and Housekeeping
It is quite possible that you may run multiple TiShadow servers or may use different server rooms for your work. Rather than having to continually type the host, port and room options with TiShadow CLI commands to direct it to the proper TiShadow server session, you can set up defaults using the tishadow config -o
You have the option to view the TiShadow server status messages, TiShadow app logs and error/exception messages by connecting with a TiShadow server using the *tishadow log* command. This will continually print the log on that server until you quit the command.
Finally, the TiShadow CLI provides a couple of housekeeping commands that might come in handy. The tishadow close command halts the currently running application bundle, and the tishadow clear command removes the deployed application bundles and associated application databases from the connected TiShadow app caches.
In this post we explored the basic usage of TiShadow to greatly accelerate the code/build/test development process. In the following posts we will dig deeper into more advanced tasks and usage scenarios.