Installing the MoSync SDK for Windows

Here we describe the system requirements of the MoSync SDK for Windows, and how to download and install it. We also describe how to upgrade from a previous release of the MoSync SDK for Windows.

Downloading MoSync

You can download the last featured release of the MoSync SDK for Windows (and its latest nightly builds) from the Download page at our website: http://www.mosync.com/download.

Important note: The MoSync SDK for Windows enables you to directly build application packages for Java ME, Symbian, Android, Windows Mobile, Smartphone, Pocket PC, and Moblin/Meego devices. You can also use it to build Xcode projects for iOS applications (i.e., for iPhone, iPad, and iPod Touch), however to finalize an Xcode project you will need to transfer it to an Apple Mac running OS X and Xcode and create the application package there. If you already have a Mac available, we recommend that you download and install our OS X development environmant, the MoSync SDK for OS X, which is available from our Download page. 

System Requirements

MoSync is designed to run on any PC that meets the following requirements:

• Microsoft Windows XP, Vista or Windows 7 operating system
• Java SE Runtime Environment (JRE) 6
• 300MB free hard drive space

Install or update your Java SE Runtime Environment before installing MoSync. It can be downloaded here.

Note: we recommend the Oracle/Sun version of JRE. If you wish to use another vendor's JRE and you have set the permanent memory perm gen size to less than the default size of 82Mb, you will get warning message requesting that you increase it.

To use MoSync's device discovery and transfer features, you will also need a Bluetooth-enabled PC, a mobile device and one of the following software stacks:

• Microsoft (included in Windows XP Service Pack 2)
• WIDCOMM (aka Broadcom)
• BlueSoleil

To use the emulator's Bluetooth support when testing programs, you will need the Microsoft stack.

Running the Installer

After you have downloaded the MoSync installer package, double-click the file to begin the installation. The installer will unpack the files and begin the installation process.

When the files have been unpacked, the MoSync splash-screen will appear.



The splach screen will fade and our license agreement will appear. Please take the time to read the MoSync License Agreement — it contains important information about the terms under which we supply the MoSync SDK. Agree to it if you would like to proceed with the installation.



Select the components you wish to install. Note that there isn't any options for the MoSync package, everything needs to be installed.



Select where you would like MoSync to be installed. Please note that MoSync needs to be installed to a directory which is not containing any spaces in its path.



If you have a previously uninstalled copy of MoSync you will get the following notice. Please follow the instruction and make a copy of your project files if they are inside the MoSync installation folder. Even if they shouldn't be removed it's better to be safe than sorry.



If you had a previous installation it will first be removed before the new version of the MoSync SDK is installed on your computer. Please wait for the installation to complete. The installation process may take a few minutes.

As part of the installation process, the Microsoft Visual C++ 2005 Redistributable will also be installed and some changes will be made to environment variables.

MoSync is now installed. Press Finish to end the installer and open the MoSync IDE.

Installing Native Emulators

MoSync includes its own powerful, cross-platform emulator, MoRE. You can also install native emulators -- particularly useful for testing native user interfaces like our Widget API and NativeUI Library, and for testing APIs and libraries that are only currently supported on a limited number of platforms. Instructions for installing native emulators can be found in our user guide Emulating a Device.

Installing the MoSync SDK for OS X

The OS X version of the MoSync SDK enables you to build applications for iOS devices (including Apple iPhones and iPads) as well as for Windows Mobile, Java ME, Symbian, Android, Smartphone, Pocket PC, and Moblin devices. Here we describe the system requirements of the MoSync SDK for OS X, and how to download and install it. We also describe how to upgrade from a previous release of the SDK.

Downloading MoSync

You can download the last stable featured release of the MoSync SDK (and the latest nightly builds) from the Download page: http://www.mosync.com/download.

System requirements

MoSync SDK for OS X has the following system requirements:

• Mac OS X Snow Leopard (10.6.6), 64-bit
• Java SE Runtime Environment 6 or later, 64-bit (usually pre-installed on the Mac)
• 250 MB free hard disk space

Apple imposes strict rules and guidelines on how applications for its App Store are to be built. To build an iOS application with the MoSync SDK, you will need to install Xcode 3.2.5 with the iOS SDK. You will also need to join Apple's Developer Program.

To use MoSync's device discovery and transfer features, you will also need a Bluetooth-enabled Mac, a mobile device and one of the following software stacks:

• Microsoft (included in Windows XP Service Pack 2)
• WIDCOMM (aka Broadcom)
• BlueSoleil

To use the emulator's Bluetooth support when testing programs, you will need the Microsoft stack.

Installing the MoSync SDK

1. Launch the MoSync for OS X Installer.
   
   
   
   
2. Click Continue.
3. Accept the license agreement.
4. The Installation Type window will show you the standard install details:
   
   
   
   
5. To install on your local hard drive, click Install.
   Alternatively, if you want to install MoSync on another drive, click Change Install Location, select the appropriate drive, make sure there is enough free space, click Continue, then Install.
   
   Note: you cannot select where on the hard disk to install the MoSync SDK, it will always be installed in /Applications/MoSync/.
6. The final installation prompt appears:
   
   
   
   
7. Click Continue Installation to install the MoSync SDK.
   
   
   
   
8. To update several important environment variables used by the MoSync SDK, you must log out when the installation completes. Click Log Out to log out and update the environment variables.

Xcode and the iPhone OS SDK

Xcode can be downloaded from the Apple iOS Dev Center.  Make sure that the version you download includes the iPhone OS SDK.

Advice on building iPhone applications can be found in our programmer's guide Developing iPhone Applications.

The iOS Provisioning Portal is designed to take you through the necessary steps to test your applications on iOS devices and prepare them for distribution.

Installing Native Emulators

MoSync includes its own powerful, cross-platform emulator, MoRE. You can also install native emulators -- particularly useful for testing native user interfaces like our Widget API and NativeUI Library, and for testing APIs and libraries that are only currently supported on a limited number of platforms. Instructions for installing native emulators can be found in our user guide Emulating a Device.

Creating Projects from Templates

This guide shows you how to create a new application project in the MoSync IDE and describes the project templates that are available to you. It also introduces the concepts of projects and workspaces. We have templates for various types of C/C++ projects, and templates for hybrid HTML/Javascript/C/C++ projects.

Projects and Workspaces

The MoSync IDE is based on Eclipse. Eclipse organizes your source code using projects and workspaces. A workspace is a collection of projects. A project is a collection of a set of source files. Projects can be individual applications or modules, depending on how you choose to organize your workspaces. Each project maps to a corresponding directory in the file system.

The different projects in a workspace may map to different file system directories or drives, although, by default, all projects map to subdirectories of a single workspace directory. All files in the workspace are directly accessible to the standard programs and tools of the underlying operating system.

The Project Explorer view in the IDE shows you all the projects in the current workspace and their source files.

Creating a New Project

In the MoSync IDE, you create a new project by doing one of the following:

• From the File menu, choose New > Project, or
  
• Right-click in the Project Explorer, then choose New > Project
  
  (If you have hidden the Project Explorer view, you can show it again by selecting Window > Show View > Other > General > Project Explorer and then clicking OK.)

When the New Project window opens, expand the MoSync folder:



In the folder MoSync you will find wizards for creating MoSync projects.

Select the one called MoSync Project.

Click Next.

The project name and location screen appears:



Enter the Project name "HelloWorld". (Note: to ensure compatibility with all platforms and devices, avoid using spaces in project names; it is always safe to use the underscore character.)

Tick the Use default location box. Click Next.

A new window will open showing you the templates that are available for you new project:

Select a template and click Finish.

Your new project will now be created from the template and loaded in the MoSync IDE.

MoSync Project Templates

We provide you with many different project templates, adapted to meet the needs of various different application types.

All templates have:

• Default compiler flags for Release configuration: -O2
• Default compiler flags for Debug configuration: O0
• Dead code elimination: Off
• Default library: mastd.lib, if enabled.

Launching and Registering MoSync

The first time you start the MoSync IDE you will be offered the chance to register the product and you will also see the Welcome screen which provides helpful links to get you started. Here we look at some of the options you have when starting MoSync.

Starting MoSync

Starting the MoSync IDE on Windows:

• If you created a desktop shortcut during installation you can use that to launch the MoSync IDE.
• Alternatively, you can use the MoSync IDE shortcut icon under Start > MoSync on your Windows Desktop.
• If you choose to install without shortcuts, the path to MoSync is \eclipse\mosync.exe in the root of the installation (default: C:\MoSync).

Starting the MoSync IDE on OS X:

• Click on the Applications folder in the Dock. Click MoSync > eclipse > mosync to launch the IDE.

The MoSync Splash Screen

When you start MoSync the first thing you will see is its splash-screen:

The splash screen shows you the target platforms that this version of MoSync can build packages for. It is worth checking this screen whenever you update MoSync because we regularly add new platforms.

The splash screen also shows the version number of the MoSync SDK in the form:

<major>.<minor> <status> (<build>)

Selecting a Workspace

Next, the MoSync IDE will ask you which workspace you want to start working in this session:

The MoSync IDE is based on the popular development environment Eclipse, and workspaces are Eclipse's way of organizing projects. You can have several workspaces, with different projects in each. (Workspaces and projects are normal folders that you can see in the file system.)

If this is the first time you are launching MoSync, you can just accept the default workspace by clicking OK. The MoSync IDE will finish loading.

(Later you can create new workspaces and use them to orgainse your different projects. Note that workspace names cannot include spaces — only alphanumeric characters (a-z, A-Z, 0-9) and underscore (_)).

Registering MoSync

When you start the MoSync IDE, it will prompt you to register the program if you have not already done so.

MoSync registration is completely free, and it means that you can get automatic device profile updates whenever you start MoSync and full access to your website including our Developer's Forum. You also have the option of subscribing to our mailing list for news about new features.

If you have not registered with us before, simply enter your desired username and e-mail address and follow the instructions. Your e-mail address must be valid because we will send a confirmation e-mail to that address.

If you have already registered with us, follow the Already registered? Click here link and enter you username and password.

When you have completed the registration process, click Continue.

Troubleshooting Registration

If you do not receive a confirmation email within a few minutes, it may be because your e-mail provider's spam filter has blocked it. Check in your spam or junk email folder to see if it has been put there.

If you are using Gmail and some similar email systems, and you have requested the MoSync IDE to resend your confirmation email, you may get an apparently empty email. Simply click on the "show quoted text" in this email to see the confirmation text.

If you have disabled the registration screen and want to display it later, you can find it under Help > Register in the IDE.

The Welcome Screen

When you successfully registered the MoSync IDE will next display its Welcome screen:

The Welcome screen provides you with many useful links to get you started with MoSync, including links to our guides and examples:

• Online user guides — all our documentation for the current featured release
• Example applications — loads all our application examples into the current workspace*
• Online tutorials — all our step-by-step programming tutorials for the current featured release
• API reference manual — our Doxygen API Reference for the your version of the MoSync SDK
• Developer center — our developer forum and latest posts
• Screencasts — video tutorials about the MoSync SDK and IDE

*If the examples already exist in the current workspace they are not replaced. If you make changes to the examples, you can still import the originals at a later time (see Importing the Examples). The examples are stored in the /examples folder in your MoSync installation directory.

If you choose not to show the Welcome screen at start-up, you can always find it again under Help > Welcome in the IDE.

When you are ready to leave this screen, click the Close the welcome screen and start using MoSync link. You will now see the normal Eclipse views in the IDE.

Views and Toolbars in the MoSync IDE

The main screen of the MoSync IDE consists of several "views" and toolbars. If you are familiar with Eclipse, many aspects of the IDE will be familiar to you, but we have added a lot of many features to support the MoSync IDE. Some of the more important features are labelled in the diagram below.

The main views in the MoSync IDE include:

• Project Explorer View - this view shows the projects that you have created or imported into the MoSync IDE. This is your main file manager.
• Editor View - this view is where you create and edit your application code. It features all the standard features of Eclipse, such as auto code highlighting and indenting. If you hover over an identifier of a class, method, etc. its documentation will pop-up. Type part of an identifier and press Crtl-Spacebar for auto-complete. It is worthwhile taking a little time to explore the comprehensive Eclipse workbench and C/C++ documentation on the Help menu to learn more about the editing features of the IDE.
• Device Profiles View - this view lists the list of available devices for which you can build you current projects. You can set filters so that only devices which match certain criteria are included in the list. The current device profile that will be used if you run your application in the MoRE emulator is highlighted in the list, and also shown at the top of the view.
• Finalizer View - this view shows the current finalizer script that will be used to finalize your application for all the devices listed in the Device Profiles view.
• Problems View - lists any problems encountered during a build.
• Console View - this view shows the output of the execution of your application and enables you to enter input. You can customize this view using the toolbar displayed in the view header bar.
• MoRE Emulator - The MoSync Runtime Environment (MoRE) starts up when you click the Run button on the main toolbar. The most visible feature of MoRE is its emulator which looks like a generic mobile device and is matched in various ways to the current target device profile.

If you close a MoSync-specific view (for example the Device Profiles view or the Finalizer view you can reopen it again by selecting Window > Show View > Other > MoSync.

Keyword Help

You can jump directly to the documentation for MoSync syscalls and other keywords by highlighting the keyword in the Editor View and pressing the F1 key. The Help View will open where you can find a link to the keyword's documentation:

Importing the Examples

Here we show you how to import the example applications in the /examples folder into MoSync. For a description of each example application, see the Example Applications overview.

There are two ways to import the example applications:

• On the MoSync Welcome screen, click the Example applications link. (To see the Welcome screen if it is closed, select Help > Welcome). A new workspace will open with the examples loaded into it. (If the examples already exist in the current workspace they are not replaced.)

• Use the Import wizard. This method allows you to choose the workspace into which the example applications will be imported and to set various import options. See Importing Projects and Files for information about the Import wizard.

After import, the example application projects will be visible in the Project Explorer:

To build and run an example application in the MoRE emulator, open one of the examples in Project Explorer, then click the Run button on the toolbar, or press Ctrl+F11.

Note that examples that use NativeUI and OpenGLES will not run in the MoRE emulator. They need to be transfered to a device (see Sending to a Device).

Working with MoSync Libraries

MoSync's libraries provide you with thousands of pre-written classes and functions that you can use within your application. Here we show how to connect to the libraries from your applications, and give you a brief overview of each of the main libraries.

Using the MoSync Libraries

MoSync's libraries contain both code files and matching header files. To get be able to use the syscalls, classes, and functions in the code files you need to reference the appropriate header files in your application using #include statements:

Here we are including the header file for Moblet (MoSync's event handling framework) and some header files for MAUI. That will enable us to access to the Moblet code and the MAUI screens and widgets later in our application.

You can get a list of all the header files that you can include in your application by browsing the Includes folder in your project:

As well as referencing the header files in your application code, you also need to specify the actual libraries that you want to use in the project's Build Settings (Project > Properties > MoSync Project > Build Settings):

Here we are including the mautil.lib library that contains the moblet code and the maui.lib library that contains the screen and widget code.

Note that the mastd.lib library is always included in the build — you don't need to specify it in your list of additional libraries.

When you build your application, MoSync's Pipe-Tool links the libraries that are listed in the Additional Libraries field and mastd.lib with your code:

The Libraries

The MoSync libraries are stored in the /lib directory in your MoSync installation. A complete description of the libraries and their contents can be found in the MoSync IDE's help system (Help > MoSync API Reference) and also in our online API Reference Guide.

Using Device Profiles

MoSync comes with a comprehensive set of device profiles to help you deploy your applications to the widest possible range of mobile devices. Each device profile defines the characteristics and capabilities of a single mobile device. Device profiles are used by MoSync's MoRE emulator and during the build process to dynamically tailor the application to a particular device.

About Device Profiles

MoSync comes with hundreds of device profiles, categorized by vendor.  Each device profile holds important information about the characteristics of target mobile device, including information such as:

• Screen dimensions
• Memory capacity
• Supported features (for example, Bluetooth)

The available device profiles are shown on the Device Profiles tab in the IDE:

When you start a new project, the active device profile is always the profile for the MoSync emulator.  (You can find this profile in the Device Profile view under Mobile Sorcery > Emulator.)

Changing the Current Device Profile

The current device profile is highlighted with an orange background to its icon.

To change the current device profile, right-click on the name of a device in the Device Profile view and select Set Target Phone.

Viewing Device Profile Information

If you want to see more information about a particular device, select Show Profile Info from the right-click menu. You will then see the header file that MoSync will use when it builds the application for the emulator:

Filtering Device Profiles

You can filter the list of device profiles so that only a subset of the full device profile list is shown in the Device Profiles view so that, when you build your application, packages will only be built for the devices listed.

You can set more than one filter: setting the right combination of filters enables you to build only for the devices that meet the exact requirements of your application.

To set a filter, click the Add button beneath the Device Profiles view. The Select Filter Type window will open:

The first option is Vendor/Device. Here it's possible to choose which vendors and devices you want to include or exclude from your profiles. Use the checkboxes to select the combination of vendors and devices you require.

The second option is Feature/Bug. Here it's possible to include and exclude devices according to the features and bugs that we know exist on the various devices. It's also possible to select device operating systems through this option:

The third option is Device Constant Condition. These are constant values set in all devices. They include the screen sizes and the available heap sizes of the various devices:

By using multiple filters you can select the devices that satisfy the requirements for your application. Mutliple filters are combined using the AND operator: a device is listed only if it satisfies the conditions of all filters.

Editing and Removing Filters

To remove or edit a currently applied filter, highlight the filter beneath the Device Profiles view, then click Remove or Edit.

Accessing Device Profiles in your Code

To access device profile definitions in your C/C++ code, include the maprofile header file:

 #include <maprofile.h> 

Useful profile definitions include MA_PROF_STRING_VENDOR and MA_PROF_STRING_DEVICE, which are the names of the device and its vendor.

For writing vendor-specific or device-specific code, MA_PROF_VENDOR_* and MA_PROF_DEVICE_* definitions are also available. For example MA_PROF_VENDOR_NOKIA and MA_PROF_DEVICE_6630.

MA_PROF_SUPPORT_JAVAPACKAGE_BLUETOOTH is defined if and only if the device supports Bluetooth.

MA_PROF_CONST_SCREENSIZE_X, MA_PROF_CONST_SCREENSIZE_Y are defined as integers that describe the screen size in pixels. MA_PROF_CONST_BITSPERPIXEL describes the color depth.

Showing the Device Profiles View

If you close the Device Profiles view you can reopen it again by selecting Window > Show View > Other > MoSync > Device Profiles.

Emulating a Device

So that you can rapidly test your application from within the IDE, MoSync includes an emulator called the MoSync Runtime Environment (MoRE). MoRE can emulate any device in MoSync's device profile database. The device profile information provides all the configuration settings it needs. You can also install the native Android Emulator and iPhone/iOS Simulator and run your application in those too -- useful if you are working with OpenGL ES, NativeUI, or other APIs that are only available for Android or iOS.

Available Emulators

All MoSync releases:

• The MoSync MoRE emulator is a virtual machine that directly executes MoSync bytecode. It's not just a compilant MoSync implementation - it's the actual reference implementation that all the real device platforms are required to conform to. It is the default emulator in the IDE.

From MoSync 2.6:

• The Android Emulator and iPhone/iOS Simulator can be installed and specified as the target emulator for Android or iOS applications so that you can test OpenGL ES, NativeUI Library, and Widget API-based applications. Once installed you just need to select an Android or iOS device profile before you run your application in the IDE. The appropriate native emulator will start up authomatically. For installation instructions, see Installing and Working with Native Emulators.

Starting the MoSync Emulator

To start the MoSync MoRE emulator, click the Run button on the toolbar (or press Ctrl+F11). The current project is be saved, built using the "Release" build configuration, and loaded into the emulator. A graphical phone is displayed.

(You can also start the emulator in debug mode by clicking the  Debug button on the toolbar. In this case the current project is built using the "Debug" build configuration, before being loaded into the emulator.)

Controlling the MoSync Emulator

The emulator is controlled either by clicking the keys on the graphical phone, or using a number of keyboard shortcuts:

The emulator communicates with the MoSync IDE, sending call stacks, panics, and other useful data to the console window.

Screen orientation

The F4 key on the keyboard toggles the screen orientation of the emulator between portrait and landscape modes (and causes an EVENT_TYPE_SCREEN_CHANGED to be sent to the application).

Multitouch emulation

MoSync 2.5+

Right-click with the mouse pointer on the emulator screen to engage multitouch simulation. Two filled circles appear, equidistant and opposite from the screen's centre point:

To emulate pinch-in, pinch-out, and rotational guestures, move the pointer in different directions while holding down the right mouse button.

Closing the emulator

The Esc key closes the emulator.

The Emulator Device Profile

When it executes a MoSync application, the emulator uses the current device profile. For instance, the screen dimensions of the graphical phone varies according to settings in the current device profile.

When you create a new MoSync project, MoSync defaults to a generic device profile.  You can find this profile in the Device Profile view under Mobile Sorcery > Emulator. The default device profile has the following characteristics:

• Platform: JavaME
• Bluetooth: yes
• MMAPI: yes
• Screen size: 240 x 320

You can use the default profile when you start to explore MoSync, and for many of our basic tutorials, but sooner or later you will want to test your application by setting up the emulator to use another device profile.

Changing the Emulator's Device Profile

The device profile that the emulator currently uses is highlighted in the Device Profile list with an orange background. To make the emulator emulate another device, right-click on a device in the Device Profile view and select Set Target Phone.

If you want to see more information about the device, select Show Profile Info from the right-click menu. You will then see the header file that MoSync will use when it builds the application for the emulator.

Configuring the MoSync Emulator

MoSync 2.6 onwards:
If you would like to run your application directly in the Android Emulator or iPhone/iOS Simulator you will need to install and configure them. Once you have done this, when you select an Android or iPhone/iOS device profile and start the emulator, your application will run in the appropriate emulator.

• To be able to use the iPhone Simulator from the IDE, you need to be using the MoSync SDK for OS X on an Apple Mac.
• To be able to use the Android Emulator from the IDE, you can use either the MoSync SDK for OS X on an Apple Mac, or the MoSync SDK for Windows.
• On both Windows and Mac OS X you can, of course, still use MoSync's MoRE Emulator.

Installing the iPhone simulator

1. Install the MoSync SDK for OS X, including Xcode 4 with iPhone SDK support. For full instructions, see Installing the MoSync SDK for OS X.

Installing the Android emulator

1. Install the MoSync SDK for Windows (instructions: Installing the MoSync SDK for Windows) or the MoSync SDK for OS X.
2. Install the Android SDK and use the AVD manager to install at least one platform to emulate (see Google's instructions for Installing the SDK).
3. Start the MoSync IDE.
4. Specify the location of the Android SDK. On Windows, open Window > Preferences > MoSync Tool > Android SDK. On OS X, MoSync IDE > Preferences > MoSync Tool > Android SDK.
5. In the SDK location field, enter the absolute path of where you installed Android SDK. (This directory usually contain directories such as "tools", "platforms", etc).

Launching a MoSync application on a native emulator

1. Make sure you have prepared your environment as described above.
2. In the MoSync IDE device profiles list, select either an Android or an iOS device.
3. Click the Run button.

Important! Those of you who are already familiar with the Android Emulator will know that it can take a long time -- and we mean a really long time -- to start. Time enough, indeed for you to make lunch, or even dinner. Nothing to do with us. Talk to Mr Google.

Scanning for a Device

MoSync makes it easy to scan for nearby devices and connect to them using Bluetooth. Of course, both your computer and the device must have Bluetooth installed and enabled, the device must be configured as "discoverable" so that the computer can find it. The device must also support the OBEX communications protocol. Once you have connected to your device, you will be able to send your application to it over Bluetooth.

Scanning for a Device

Click the Select Target Device icon (or select Scan for Device from that icon's drop-down menu):

The transport selection dialog will appear.

Select Bluetooth. If you have correctly configured your Bluetooth stack, MoSync will start a search for all discoverable Bluetooth devices in range and display the ones that it finds:

Highlight the device that you want to send your application to and click OK.

MoSync will now check that the selected device has the OBEX service available for binary transfers:

The Device Profile-Target Device Association

In MoSync 2.3, when the OBEX service is detected, the Select Preferred Profile window will appear:

Select the MoSync device profile you want to associate with the target device. Usually, this will be the profile for the target device, e.g., the N95 profile for the N95 phone. However, if there is no suitable profile for your device, you can choose another compatible profile. Click OK to associate the chosen device profile with the target device.

When the OBEX service is detected, MoSync automatically completes the device selection by associating the device profile currently selected in the project with the target device. For more about this association, including how to check its current setting and how to change it, see Sending to a Device.

Windows Mobile Bluetooth Issues

We have noted some issues with the pairing of Windows Mobile devices to Windows computers.

The first issue seems to happen if the device has been previously paired with the computer outside of MoSync. If you are having problems sending application packages files from the MoSync SDK to a Windows Mobile bluetooth device, try unpairing the device in the Windows Bluetooth Device Manager or its equivalent, and then searching for it again in the MoSync SDK.

The second issue relates to Windows Active Sync and/or HTC Active Sync. These applications can cause  problems when trying to connect Windows Mobile devices to the computer via MoSync and Bluetooth. Try disabling Active Sync if you are experiencing connection or file transfer issues.

Documentation Inbox X Reply | Abi Waqas  to me show details 28 Aug (3 days ago)   Hi Chris.. I just have found a problem and we need to document it somewhere.... its about connecting windows mobile (the crappy one :D ) with mosync. if the windows active sync/HTC active sync for windows mobile is installed on the computer, one might face soooo many problems to connect it to the computer via bluetooth in MoSync. One can find the device, associate it with the preferred profile but can't send the application to the device.. I also have tried to send the cab file through windows bluetooth file wizard but it didn't work.. tried it on a couple of fone.. then I forcefully exit the the active sync and it started working fine... one may think its mosync problem but its not.... -- Med vänlig hälsning / Best regards,  Abi Waqas Asmat (Ghuman) Test and Verification Engineer MoSync AB Cell: +46(0)760064164 Email: abi@mosync.com Reply Forward Reply by chat to Abi

Sending to a Device

Once you have scanned for a device and selected it (see Scanning for a Device) you can send your application package to it via Bluetooth. Alternatively, if your target device is not Bluetooth-enabled or cannot be detected, you can transfer your package to it via a cable or viaa  web server. Here we describe all these methods.

Checking the Target Device and Device Profile Association

Before you send your application to a device, it is always a good idea to check what target device is currently selected and which device profile is associated with it. That's because MoSync will send the package for the device profile associated with the target device.

The association is set up when you first scan for and select a target device:

• In MoSync 2.3, you can chose the device profile that should be associated with the target device,
• In MoSync 2.2, MoSync automatically attaches the device profile active in the project.

Here's how to see the current associations and how to change them if necessary.

Click the small down arrow next to the Select Target Device icon. A drop-down menu will appear:

At the top of the menu you will see the names of the devices followed [in brackets] by the device profiles currently associated with them. In the example above, the phone called "Nokia 6630 demo2" is associated with MoSync "6630" device profile, while the phone called "W715" is associated with the closest match in MoSync's database, the "W710" device profile.

The current target device has a tick against it (here it's the Nokia phone).

Note: The device name is a setting in the mobile device. This name is usually set by the manufacturer, but it is often configurable, which can be helpful if you are testing your application on two otherwise identical devices.

Changing the Target Device and Device Profile Association

You can change the device profile associated with a target device by selecting Edit Device List from the Select Target Device icon's drop-down menu. The Select Preferred Profile window will appear:

Select the target device you want to edit from the top list box. Double-click on a device profile in the bottom list, then click OK. The new device profile will be associated with the chosen target device.

Sending Your Application to the Target Device

Click the Send to Target Device icon to send the package that matches the device profile to the currently selected device:



How the actual installation on the device works is platform- and device-specific. If you are not sure how this is done or where your application is located after installation, consult the user manual for your device.

File transfer over Bluetooth (OBEX) doesn't work?

If your target device does not have Bluetooth file transfer (OBEX), you will need to transfer your package using one of the following methods:

• USB connection/Android device:
  Install the device vendor's drivers on your machine. Connect your device using the vendor's USB cable, then select Scan for Android USB Device from the Select Target Device drop-down menu.
• USB connection or other cable/any device:
  Connect the device to your PC using the cable provided by the device vendor and use the vendor's own file transfer solution.
• No cable connection:
  Upload the package to a web server, then download it to the device using the device's web browser; or copy the application to a memory card and transfer that to the device.

Finding the Package to Transfer

Open MoSync, select your device profile, and build your project. You will find the executable package that MoSync has built for your application in the folder:

C:\<install-path>\<workspace>\<project>\FinalOutput\<build-config>\<vendor>\<model>\<package>

where <install-path> is the place you installed MoSync.

To install your application, copy the executable package to your device using the vendor's own file transfer solution and run it.

Build Configurations and Settings

The MoSync IDE provides you with several ways to build your application (i.e. to compile it into a package ready for installation on a mobile device). Builds can be set to start automatically or can be started manually. The project's build configuration specifies the compiler, packager, and linker settings to use when building the project. In this guide we describe the build options available to you, and the effect of various build settings on the output packages.

Automatic Builds

When the automatic build feature is on, your application will be built whenever any file in the project is saved. By default, the automatic build feature is turned off. You can enable it by selecting Build Automatically from the Project menu.

Manual Builds

When the automatic building feature is turned off, there are several ways to build your application manually:

• Select Build Project from the Project menu, or
• Right-click on a project in the Project Explorer view, then select Build Project from the pop-up menu, or
• Click the Run button to run the application in the emulator, or
• Double-click on a new device in the Device Profile view.

In the case of both automatic and final builds done this way, the package is only built for the currently selected device profile. To build the application for all devices in the Device Profile view, you will need to Finalize Your Application.

Output Location

The location where the newly built package is stored can be seen in the IDE's Console view.

Cleaning a Project

If something goes wrong during the build process (or you find inconsistencies in your application when it runs), you should clean up your project files. Cleaning removes the intermediate files created during the build process.

To clean up your project files, do one of the following:

• Select Clean Project from the Project menu, or
• Right-click on a project in the Project Explorer view, then select Clean Project from the pop-up menu.

Release and Debug Configurations

All new MoSync projects have two build configurations available by default: Release and Debug. These are the build configurations for creating standard release packages and for building a debug version of the application.

You can create more build configurations if you need them. For example, if your target platforms have different screen sizes and want to use different image files, you can create new build configurations to make sure the right images are included in each package. (Excluding files is done on a per-configuration basis, so in the above case it would be easy to have one resource list file for, say, 320x240 screens, and one for 220x176 screens, and just exclude/include the desired files.)

Selecting a Build Configuration

To see the currently available build configurations for your project, and to see which one is active:

1. Highlight your project in Project Explorer.
2. Select Properties from the Project menu (or right-click on the project and select Properties).
3. Open the MoSync Project element and select Build Configurations.
4. Tick the Activate Configurations box.

All launch configurations as well as the Finalizer have settings that control which build configuration to use.

For example, when you press the Debug toolbar button (or select Debug from the Run menu), the build configuration is automatically set to "Debug" prior to launching your application in the MoRE emulator.

Note: if you do debug your application, the Debug profile will be set to [Active]; you will need to make the Release build configuration [Active] to launch a standard (non-debug) version of your application in the MoRE emulator.

Like the Debugger, the Finalizer has a similar setting: To see these settings, right-click the project and select Properties... > Mosync Project > Finalizer:

Note: All new MoSync projects come with build configurations activated: the Activate Configurations box is ticked by default. (The ability to inactivate build configurations is there for historical reasons as this is a fairly recent addition to the IDE.)

Adding a New Build Configuration

To add a new build configuration to a project:

1. Highlight your project in Project Explorer.
2. Select Project > Properties > MoSync Project > Build Configurations.
3. Make sure that the Activate Configurations box is ticked. You will now see the existing build configurations for the project. The currently active build configuration is marked with the label [Active].
4. Click Add to add a new build configuration (or highlight an existing one and click Duplicate). A new build configuration will appear in the list.
5. If you want to rename the new build configuration, highlight it and click Edit.
6. Select the Build Settings element from the properties tree.
7. Adjust the build settings as required (see table below).

Build Settings

Path Variables

MoSync 2.5+

In Build Settings you can use the following variables in paths:

Note: If you open in MoSync 2.5 a workspace created with an earlier version of MoSync, MoSync 2.5 will automatically add the %mosync-home% variable to the Additional Include Paths and Additional Library Paths in the project's Build Settings. If you then want to go back to an earlier version of MoSync you will have to remove those variables.

Setting Application Permissions

Some devices (particularly Symbian and JavaME devices) require that your application must have permission to access functions and services like Bluetooth, Calendar, Camera, Contacts, file storage, Internet, location, power management, SMS, and vibration. The MoSync SDK makes it easy to grant access to such services and functions.

An error on a device such as the Symbian OS error code "-46 KErrPermissionDenied" is a sure sign that you are trying to access a function or service without the necessary permissions. You can set the access permissions you need from the Properties menu for your project. Highlight your project in Project Explorer, then select Project > Properties > MoSync Project > Application Permissions.

Use the checkboxes to grant access to the device services that you application uses when it executes.

Click Apply to apply the changes, then rebuild your project.

You can use the Restore Defaults button to reset access permissions to their original settings.

We strongly recommend that you grant your application just enough permissions to run properly, and no more. This is not only for the sake of security, but also to avoid annoying end-users who might decide that an application that has unnecessary permissions is suspicious and is doing stuff that it shouldn't.

Using Pipe-Tool

Pipe-Tool is MoSync's code transformation engine. It combines the functions of a resource compiler, code linker and assembler, and performs code verification, optimization and dead code elimination to produce highly optimized outputs for each of the target platforms.

Invoking Pipe-Tool

Pipe-Tool is automatically invoked by the MoSync IDE during the normal build process, so in the normal case you don't need to do anything to use Pipe-Tool, just build (or rebuild) your project.

For specialist uses, Pipe-Tool can also be run on demand from the command line (see below).

What Pipe-Tool Does

When it is invoked, Pipe-Tool makes several passes through your code. It is very fast: it takes only around one second to make six passes through a 25000 line application.

Resource Compilation

Pipe-Tool compiles and indexes the external resources that your application uses when it runs. These resources include image and audio files, binary files, and namespaces.

Pipe-Tool's resource compilation function is automatically invoked as the first stage of the build process, prior to the compilation of your code by GCC. Resource compilation can also be invoked from the command line using the command:

pipe-tool -R outfile infile1 [infile2 ...]

for example:

pipe-tool -R resources audio.lst images.lst other.lst 

You identify the resources that your application needs by listing them in a resource list file. In the example above, Pipe-Tool compiles all the resources that are referenced in the three resource list files called audio.lst, images.lst, and other.lst and then concatenates them into a single binary file called resources, ready for deployment to the device.

As well as outputting the binary file, Pipe-Tool also creates a header file called MAheaders.h which you need to include in your application program. This header file contains the #defines that symbolically link your application to its resources.

For more information about resource list files and their syntax, see our Resource Compiler Reference.

Code Compilation

Pipe-Tool invokes the GCC compiler to compile your application code.

Code Verification and Optimization

A little later in the build process, Pipe-Tool takes the output from GCC and performs code verification, code optimization, and dead code elimination. Code verification includes among other things:

• Bounds checking
• Division error detection
• Stack abuse detection
• Function tracing

Depending partly on the output required by the target platform, Pipe-Tool's code optimization features help create faster, smaller programs by:

• Converting immediate values to constant register values
• Eliminating jump-to-jump occurrences
• Rewriting functions to perform constant value inlining
• Analyzing and optimizing program flow
• Analyzing and optimizing register life
• Performing memory index reduction and adaptive index scaling

During the dead code elimination phase, Pipe-Tool looks through the application tree, marking any nodes that are unreachable. Unlike a traditional linker that marks only whole objects or functions for elimination, Pipe-Tool eliminates dead code down to the lowest level of granularity: right down to individual instructions and bytes.

Linking

After optimization, Pipe-Tool links the MoSync IL from GCC with the pre-compiled MoSync libraries, and the compiled resource binary to create the MoSync bytecode, Java bytecode, or C/C++ source code that will be packaged with the platform runtimes.

Assembly

When a program has been optimized and linked, Pipe-Tool sends the internal representation of the program to the compiler backend. The backend transforms the application into a representation that can be understood by the target architecture. Most commonly the program gets assembled into MoSync bytecode which in turn may be interpreted or recompiled by the MoSync runtimes. We also have experimental support for producing a Java bytecode representation of the application that can be executed on Java virtual machines.

Using Pipe-Tool from the Command Line

Compiling Resources

pipe-tool -R options outfile infile1 [infile2 ...]

Building a Library

pipe-tool -L options outfile infile1 [infile2 ...]

In -L mode, Pipe-Tool combines the specifed infiles (.s files) into a single library .lib file.

Building an Application

pipe-tool -B options outfile infile1 [infile2 ...]

In -B mode, Pipe-Tool combines the specifed infiles to create a single output file.

Manual Page

The options are described in the Pipe-Tool manual page, which can displayed using:

pipe-tool -h 

General options:
  -h | --help            show this usage info
  -error-paths         show file paths in errors
        -xerr                extra information in case of errors
        -master-dump         also dump the input into a single text file
        -s<dir>              search <dir> for input libraries

Build application (-B) options:
  -entry=sym           set code entry point (default 'crt0_startup')
  -datasize=size       set data size (default 65536)
  -stacksize=size      set stack size (default 2048)
  -heapsize=size       set heap size (default 16384)
  -appcode=value       set application code (default 'TEST'(0x54455354))
  -p=vendor/model      link with device profile
  -dump-syms           dump symbol tables
  -dump-unref          dump unreferenced symbols
  -sld=file            output source/line translation
  -stabs=file          output debug information
  -elim                eliminate unreferenced code/data
  -no-verify           prevent code verification
        -java                build a Java class file
  -gcj=flags           for -java option: set flags for GCJ

Resource compiler (-R) options:
  -depend=file         output dependencies in makefile syntax

Known Issues with Pipe-Tool

• Dead code elimination sometimes gives unstable results.

Finalizing Applications

MoSync's great strength is that you can use it to build your one application into the different packages you need for hundreds of mobile devices. MoSync's Finalizer will build all the executable packages, ready to be transferred to the devices you've propogated from your device profiles list.

Preparing to Finalize

Device profiles list

Before you finalize your application, it is worthwhile checking that the set of devices listed on the Device Profiles tab includes all the devices you want to build the final packages for. If it doesn't, adjust the device profile filters until it does. (But don't worry if you can't get exactly the subset you want, you can adjust things later.)

Finalizer build configuration

When you finalize your application, the build process will use the build configuration set in the properties for your project. To see which build configuration will be used, right-click on your project in the Project Explorer view and select Properties > MoSync Project > Finalizer.

Generating and Editing the Finalizer Script

When you are ready to finalize your application, click the Finalizer tab next to the Device Profiles tab. The Finalizer view appears:

Click the Propagate button. MoSync will generate a build script based on the devices listed in the Device Profiles tab:

The script is editable so you can make changes such as adding device to it or removing devices from it.

Running the Finalizer Script

To run the script and build all your application packages, press the Finalize button.

If you have selected many devices and you have a large project, this operation can of course take quite some time. A progress bar will indicate progress:

When you run the Finalizer, the built packages are placed in a directory called \FinalOutput in your project folder. Each device package is placed in a directory hierarchy sorted by vendor and model.

Organising Your Workspaces

Workspaces are useful for organizing projects. For example you can use them to working with different versions of projects, or as sandboxes. Here we describe how to create workspaces and switch between them.

Creating a New Workspace

From the File menu, select Switch Workspace > Other.

The Workspace Launcher will open:

In the Workspace box, enter a name for your new workspace. Workspace names cannot include spaces — only alphanumeric characters (a-z, A-Z, 0-9) and the underscore character (_).

Click OK.

MoSync will restart with the new workspace loaded. (If the Welcome page opens, just close it.)

To add projects to your new workspace, see Importing Projects and Files.

Switching Workspaces

To switch between your workspaces, select Switch Workspace from the File menu.

If you have already used the other workspace in this session, you can choose it directly from the pop-up menu. Otherwise, select Other to open the Workspace Launcher and browse for you workspace from there.

In the Workspace Launcher you have the option to copy the current workbench layout and working sets from the current workspace to the new one.

Importing Projects and Files

Here we show you how to import projects and files into MoSync. We give detailed instructions on how to import existing MoSync projects, and some information about importing other resources like archives, files systems, preference settings, breakpoints, launch configurations, and team project sets.

Importing Existing MoSync Projects

To see an existing MoSync project in your current workspace, you need to import it.

The Import wizard guides you through all the necesary steps of the import process and allows you to set various options.

Note: You can follow these steps to import our example applications (which of course are just another type of project). However, there is a much quicker way of importing them, which we describe in Importing the Examples.

Open the Import wizard in one of the following ways:

• Right-click inside the Project Explorer view and choose Import from the pop-up menu, or
• Select Import from the File menu.

Choose the import source by opening the MoSync group, selecting Existing MoSync project into workspace, and clicking Next. The Import Projects dialog will open.

Select the Select root directory option and click its Browse button.

Browse for the folder where your projects are stored, highlight it, and click OK.

A list of the projects available for import will be displayed (in this case it is example application projects in our \examples folder):

You have the choice of copying the projects into the workspace or leaving them in their current location.

• If you copy the projects (by ticking the Copy projects into workspace option), MoSync will put its builds in the new project folders that it has copied into the workspace.
• If you do not copy the projects, MoSync will put its builds in to the original project folders.

Make sure that the checkboxes of the projects you want to import are ticked, then click Finish to import the projects into your workspace.

Importing Other Projects and Files

The Import wizard can also be used to import other types of projects and files. Many of these import options will be familiar to Eclipse users. A brief overview of the available options is given in the table below.

Building Projects from the Command Line

Use the following syntax to build MoSync projects from the Windows command line:

mosyncc.exe -application com.mobilesorcery.sdk.builder.headless  -data workspacelocation -project
   [-f finalizerscript] projectname

Replace workspacelocation with the location of your workspace, and projectname with the name of the project to build. This will actually launch a Finalizer build with the currently set device filters.

If you wish to produce binaries for a different set of devices you will need to create a Finalizer script and use the -f switch. A finalizer script is just a text file containing lines like the ones produced when you click the Propagate button in the Finalize view in the IDE.

MoSync with Visual Studio 2005

You can use MoSync with Microsoft Visual Studio although, of course, much of the functionality concerning building for mobile devices will be lost this way. The gain is that you will be able to use the fully-featured debugger in Visual Studio. Here we describe how to set up Visual Studio, and how to use it to build and debug an application.

It is only possible to use Microsoft^® Visual Studio C++ 2005 Express Edition at this time. You will also need the Microsoft^® Windows Server 2003 SP1 Platform SDK. You can download these products here:

• Visual Studio
• Platform SDK

Our win32 library for Visual Studio 2005 implements the MoSync syscall APIs. This enables developers to build MoSync projects using Visual C++ and use all of Visual Studio's features, including its debugging facilities.

You should be aware that Visual Studio produces a native windows application, which is fundamentally different from a real MoSync application. For starters, a different compiler is used, which has a number of implications, including a different layout of code and data. Furthermore, if you use the native Win32 libraries (including the Win32 API itself) the resulting source code will not work in MoSync.

(Our win32 library was originally provided because MoSync lacked a proper debugger, and although the debugging experience would be inaccurate with respect to when the application is built for the MoSync architecture, it was considered better than nothing. Today, we would encourage you to use the debugger provided in the MoSync IDE. It is still not perfect, but we are working hard to improve it and are grateful for any feedback or bug reports.)

Setting up Visual Studio

If you haven't installed Visual Studio 2005 you will need to install it first.
Also check so that you have installed the Platform SDK.



First we need to add the correct search paths to Visual Studio. Choose Options from the Tools menu.



Expand Projects and Solutions and choose VC++ Directories. Add the search path for the MoSync library files as shown.



Choose 'Include Files' and add the path for MoSync include files.

If you use the Visual Studio 2005 Express edition you will need to follow these steps before closing the dialog

To be able to build you will also need to add the following search paths for the Windows Platform SDK:

• To executable files
  C:\Program Files\Microsoft Platform SDK for Windows Server 2003 R2\Bin
• To include files
  C:\Program Files\Microsoft Platform SDK for Windows Server 2003 R2\Include
• To library files
  C:\Program Files\Microsoft Platform SDK for Windows Server 2003 R2\Lib

Now you have added all the correct search paths so that Visual Studio will be able to build your applications.

Close the Options window by clicking OK.

Now you just have to make one more adjustment before you will be able to create new projects. Inside the directory C:\Program Files\Microsoft Visual Studio 8\VC\VCProjectDefaults you will need to edit the file corewin_express.vsprops. Find the following string:

AdditionalDependencies="kernel32.lib"

You will need to change that line to:

AdditionalDependencies="kernel32.lib user32.lib gdi32.lib winspool.lib 
comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib"

More information about this can be found at http://msdn.microsoft.com/en-us/vstudio/aa700755.aspx

Configuring a MoSync project in Visual C++

Start with a Win32 project.

In the Application Wizard, in Application Settings, select Empty Project.

• Add a C/C++ file. This allows you to access C/C++ project properties.

In Project Properties:

• Select All Configurations.

In General:

• Change Output Directory from $(SolutionDir) to $(ProjectDir).
• Change Character Set to Not Set

In C/C++, General:

• Set Detect 64-bit Portability Issues to No
• Optional but Recommended: Set Treat Warnings As Errors to Yes.

In Linker, add the libraries needed (mosynclib.lib and MAStd.lib are required) Input:

• Set Additional Dependencies to mosynclib.lib MAStd.lib MAUtil.lib MAUI.lib

In Linker, System:

• Set SubSystem to Windows

Building and debugging an application

If you build and run your project, the MoSync emulator will start with your project running in it. You will also be able to debug your application using the Visual Studio debugger so you are able to set breakpoints and single step through your code. Note that the program is compiled as pure x86 code, so the execution envionment may be more forgiving to badly behaved code.

MoSync with Visual Studio 2010

You can use MoSync with Microsoft Visual Studio although much of the functionality concerning building for mobile devices will be lost this way. The gain is that you will be able to use the fully-featured debugger in Visual Studio. Here we describe how to set up Visual Studio, and how to use it to build and debug an application.

MoSync supports Microsoft^® Visual Studio C++ 2010 at this time. You can download it here:

• Visual Studio 2010 Express

Our library for Visual Studio implements the MoSync syscall APIs. This enables developers to build MoSync projects using Visual C++ and use all of Visual Studio's features, including its debugging facilities.

You should be aware that Visual Studio produces a native windows application, which is fundamentally different from a real MoSync application. For starters, a different compiler is used, which has a number of implications, including a different layout of code and data. Furthermore, if you use any other native Win32 libraries (including the Win32 API itself) the resulting source code will not work in MoSync.

(Our win32 library was originally provided because MoSync lacked a proper debugger, and although the debugging experience would be inaccurate with respect to when the application is built for the MoSync architecture, it was considered better than nothing. Today, we would encourage you to use the debugger provided in the MoSync IDE. It is still not perfect, but we are working hard to improve it and are grateful for any feedback or bug reports.)

Configuring a MoSync project in Visual C++

Start with a Win32 project.

In the Application Wizard, in Application Settings, select Empty Project.

• Add a C/C++ file. This allows you to access C/C++ project properties.

In Project Properties:

• Select All Configurations.

In General:

• Change Output Directory from $(SolutionDir) to $(ProjectDir).
• Change Character Set to Not Set

In VC++ Directories:

• Add MoSync\include to Include Directories.
• Add MoSync\libs\vs2010 to Library Directories.

In C/C++, General:

• Optional but Recommended: Set Treat Warnings As Errors to Yes.

In Linker, add the libraries needed (mosynclib.lib and MAStd.lib are required) Input:

• Set Additional Dependencies to mosynclib.lib mastd.lib mautil.lib

Building and debugging an application

If you build and run your project, the MoSync emulator will start with your project running in it. You will also be able to debug your application using the Visual Studio debugger so you are able to set breakpoints and single step through your code. Note that the program is compiled as pure x86 code, so the execution envionment may be more forgiving to badly behaved code.