EditAttachPrintable
r11 - 04 Nov 2008 - 17:46:41 - GuilhermeCHazanYou are here: SuperWaba >  Codev Web  >  ChangeLogs > TotalCross > TotalCrossSDK

In this page we will describe the SDK structure, and how to install the samples and the vms in the devices.

The TotalCross SDK Java files are covered by the LGPL version 3. By installing the SDK you are agreeing with this. The virtual machine follow another license.

In order to deploy applications, you will have to install JDK 1.6 or higher.

The VM provided in the SDK is a demo version. It will work during 80 hours on all platforms. The time is updated each 5 seconds. In the devices, doing a hard-reset (and changing the user's name in Palm OS) is enough to provide another 80-hours of test. There's no license violation doing this hard-reset. In win32, there's no way to provide another 80-hour test unless reformatting your hard drive and reinstalling windows.

Directory structure

The SDK has the following folders: 

TotalCrossSDK
     + dist
     + docs
     + etc
     + src

Inside dist, we have:

  • \TotalCrossSDK\dist\tc.jar : this file must be added to Eclipse (or your favorite IDE), and it contains all totalcross.* base classes and the deploy tools.
  • \TotalCrossSDK\dist\samples : the installation files for all samples. Lets take the UIGadgets sample, located at dist\samples\UIGadgets. Inside there's an install folder, and below the following folders:
    • applet: contains some html files (representing most used devices) and a self-containing JAR file with everything that's needed to run the sample. Each time you open the html, you will have to close your multi-tabbed browser, otherwise errors may arrise.
    • bb: blackberry installation files. The alx, cod and jad files are used to deploy the file to the pda, and the csl and cso to sign the file (read the BlackBerry section below).
    • iphone: there are always two files in this folder, a xml and a zip file, which must be uploaded to a server and then downloaded to the iphone's Installer tool. Read more at the iPhone section below.
    • palm: contains the pdb and prc files to be installed in the device. Optionally, you can use the install.exe file, which installs the same files, but allowing you to select the user from a combo box.
    • win32: there are two files, an exe and a tcz, which must be copied to the same folder where the TotalCross VM for Win32 is located, or to a folder below it. For example, if the vm is installed at c:\totalcross, copy these two files to c:\totalcross, or create a c:\totalcross\UIGadgets and copy these two files to the UIGadgets folder. The exe is smart enough to find the path to the vm.
    • wince: there are 6 cab files. Just run the bat file inside that folder and the correct cab file for the currently connected Windows CE device will be choosen. If something goes wrong, you can copy the cab file to your device and open it using the windows explorer.
  • \TotalCrossSDK\dist\vm : virtual machine files that which will interpret your TotalCross code at the device. Below are instructions of how install them in each platform:
    • bb: open the TotalCross.alx file in your blackberry desktop software.
    • iphone: upload the files to your server and download them using the iphone's Installer.
    • palm: install TCBase.pdb, TCFont.pdb and TCVM.prc. Optionally, click in the Install.exe file which will install the same files but letting you choose the user.
    • win32: copy the files TCSync.dll, TCSyncLib.tcz and TCVM.dll to somewhere (usually c:\totalcross). The first two are the conduit synchronization files, and the tcvm.dll is the vm. You must also copy dist\vm\TCBase.tcz and dist\vm\TCFont.tcz files to the same folder.
    • wince: just run the _CEInstall-RunMe.bat file and the correct cab file will be installed in the device. Optionally, you can grab the TCVM.dll file inside the target plaform's folder and copy it to the device (usually \TotalCross but can be anywhere else if all vm and application files are being installed manually). If not using the bat file, you must also copy dist\vm\TCBase.tcz and dist\vm\TCFont.tcz files to the same folder.

Inside docs, you have:

  • TotalCross Companion.pdf (not available in the BETA version)
  • an html folder. Add the file TotalCrossSDK\docs\html\index.html file to your browser, to be able to read the generated javadocs.

Inside etc, we have:

  • images: some images used by the sdk
  • launchers: used by tc.Deploy
  • security: signature files
  • tools: tools used by the tc.Deploy. Inside this folder, you may have to use the apache folder, which contains a xml-rpc server, and the commapi, which contains files that must be added to the classpath if you use the PortConnector class at desktop.

Inside src :

  • tc\samples: the sources of all samples.
  • totalcross: the sources for the totalcross API used at desktop.

Application deployment

BlackBerry

Deployment

You must update your ROM to version 4.3. TotalCross will not run on versions before that one.

To deploy a TotalCross application or library for BlackBerry devices, run tc.Deploy as follows:

tc.Deploy [–Drim.root=] [-Drim.class.path=] [/s] -bb

where:

  • is the path to the BlackBerry JDE or BlackBerry Component Package root directory. If not specified, tc.Deploy will use the internal BlackBerry Component Package distribution: “…/TotalCrossSDK/etc/tools/bb”;
  • is the set of paths to search for BlackBerry libraries (.jar files). This path must include the BlackBerry library (net_rim_api.jar), the TotalCross for BlackBerry (tcbb.jar) and any other TotalCross libraries needed by your application (like Litebase, for example). If not specified, tc.Deploy will search for libraries only under the default library directory: “…/TotalCrossSDK/etc/tools/bb/lib”;
  • is path to the .jar file containing the TotalCross application or library being deployed.
If the optional parameter “/s” is specified, tc.Deploy will automatically open SignatureTool after the TotalCross application or library has been deployed. It is important to say that the two signature files (see the Signature section for details) must be placed under the directory, otherwise SignatureTool will claim that no signature key was found.

Installation

To install a TotalCross application or library on BlackBerry devices, first you have to deploy it. Then, make sure tc.Deploy has generated the following files under the “…/install/bb” directory:

  • .cod contains the application modules for BlackBerry. It is used both in desktop and OTA (over-the-air, refer to http://www.blackberry.com/developers) installations;
  • .alx is used together with .cod to install the application or library using the BlackBerry Desktop Software.
  • .jad is used together with .cod to install the application or library using the OTA method.

The Desktop installation method is very straightforward. In the BlackBerry Desktop Software, open the “Application Loader” and follow the instructions. When the list box containing all the applications that are currently installed on the device is displayed, click “Add…”, select the .alx file and confirm. The selected application should appear on the list. If so, click “Next” and wait until the process is finished.

Signature

Before a TotalCross application can be installed on a BlackBerry device it is necessary to sign its module using the SignatureTool and the keys provided by RIM – Research In Motion.

If you do not have the signature keys, you must request them directly to RIM. More information can be found here: http://na.blackberry.com/eng/developers/downloads/api.jsp. After receiving and registering your keys in your computer, you will see the two key files in your BlackBerry JDE or BlackBerry Component Package root directory: sigtool.csk and sigtool.db.

Signing a TotalCross application or library is the same as signing any other BlackBerry application: you must open SignatureTool (the RIM signature application) and load the application .cod module. Then, click request, type your password and wait until the signing process is finished.

You can also automatically sign TotalCross applications or libraries during the deployment process. To do this, you must specify the option “/s” when running tc.Deploy (see the Deployment section for details).

iPhone

First, to deploy TotalCross in your iPhone, you will have to JailBreak it. An iPhone TC application could be generated as easily as any other platform by providing the "-iphone" option during the "tc.Deploy" invocation.

To deploy an application to iPhone you must define some totalcross.sys.Settings attributes, as described below:

  • totalcross.sys.Settings.appCategory: category name of the application to fasten package searching. For example, "Foo Applications".
  • totalcross.sys.Settings.appLocation: http URL where the zip file could be downloaded, the URL without the path is used as the application's website for additional information. For example, "http://www.mycompany.com/iphone/download"
  • totalcross.sys.Settings.appDescription: a brief application description. For instance, "Foo Task Force".

Basically, to install a TC application on iPhone, you have two choices. The first one is to do a manual install and the other one is to support the package manager named "Installer".

Manual install

The "tc.Deploy ... -iphone" execution generates 3 files in a "install/iphone" folder. One file is a package description file ".plist" that describes the package install/uninstall/update operations and provides many information about the package. This file will be used in the second method only (installer support) and could be ignored. The second file is a rep.xml file that will also be used by the installer. The third file is a zip file which is the standard package archive format used by the Installer tool. The zip file has a file structure similar to the file structure of an installed applications. Thus, all you need to do is to unzip the zip file on the iPhone filesystem like that:

scp MySample.zip root@iphone:/Applications ssh root@iphone cd /Applications unzip MySample.zip && rm MySample.zip

Miserably, the zip archive doesn't support file permissions and thus you have to apply manually file permissions. Excetute the following commands:

chmod a+x /Applications/MySample.app/start /Applications/MySample.app/MySample

The latest step is to notify the SpringBoard about a package change. The current solution is just to kill it to cause a SpringBoard refresh. Just enter:

killall SpringBoard

The new installed application should appear now.

"Installer" support

This tool was the first package manager on the iPhone. It's configured to process a list of "sources" and each source contains one or several softwares. You can add your own source by pressing the lower right "Sources" button, pressing the "Edit" button and finaly pressing the "Add" button to enter your source URL.

As you can see, the URL have to start with http which is the unique supported protocol. Thus you will need a web server such as Apache, IIS, etc. to deploy your TC application(s). Cancel the source adding since we are not yet ready to enter a valid URL.

The source URL have to deliver a ".plist" content describing the source but also the list of available packages. TC provides a tool (tc.tools.deployer.IPhoneBuildSource) to build that file by providing a list of folders as argument where your iPhone apps have been deployed (each application consists in 2 files in "install/iphone"). The result is a "rep.xml" file that can be uploaded on your web server and you will provide as source URL in Installer the URL to access this packages catalog file. For example, to build a single rep.xml for all Litebase samples we use: 

cd totalcrosssdk\dist\samples
java tc.tools.deployer.IPhoneBuildSource .

Of course, in addition to this list of apps, you will also have to upload all the applications to your web server. Just copy all your application's zip archives into the folder containing rep.xml. The IPhoneBuildSource should be used when you want to provide to your user many applications in your server, for example, the TCVM and your application. It allows the user to use a single source to download the applications.

Optionally, you can use the installs/iphone/rep.xml and the zip files and copy them directly to your server. This rep.xml will allow you to download only the application that was generated.

Now add your new source of applications to the Installer as described above, don't forgetting that the source url must contain the rep.xml file (E.G.: http://www.mycompany.com/iphone/download/rep.xml) and once the source has been refreshed, you will see your applications in the list of available apps, ready to be installed.

Palm OS

Palm OS application deployment is easy, just pass -palm to the tc.Deploy tool. By default, the application will be installed in a "TotalCross Apps" category. To change it to another category, set the Settings.appCategory flag to the desired category. Note that there's a limit in the number of categories a Palm device can have, it it overflows, the category is ignored.

Eclipse Configuration

To configure eclipse (tested with 3.12, may be almost the same for newest releases), follow these steps:

  1. Create a Java project.
  2. Go to Project properties / Java Build Path. Click Libraries tab, and "Add external jar" button
  3. Select "TotalCrossSDK/dist/tc.jar".
  4. Back to the Libraries tab, click in the + right before the jar's name
  5. Source attachment: select the TotalCrossSDK/src folder
  6. Go to the Java Compiler
  7. Select "Enable project specific settings"
  8. Select "Compiler compliance level" and set to 1.3

That's it.

Edit | Attach | Printable | Raw View | Backlinks: Web, All Webs | History: r11 < r10 < r9 < r8 < r7 | More topic actions
 
SuperWaba home
This site is powered by the TWiki collaboration platformCopyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding SuperWaba? Send feedback