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.

Topics

Automatic Builds
Manual Builds
Output Location
Cleaning a Project
Release and Debug Configurations
Selecting a Build Configuration
Adding a New Build Configuration
Build Settings
Path Variables

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:

Highlight your project in Project Explorer.
Select Properties from the Project menu (or right-click on the project and select Properties).
Open the MoSync Project element and select Build Configurations.
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:

Highlight your project in Project Explorer.
Select Project > Properties > MoSync Project > Build Configurations.
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].
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.
If you want to rename the new build configuration, highlight it and click Edit.
Select the Build Settings element from the properties tree.
Adjust the build settings as required (see table below).

Build Settings

Project type		A project can be a stand-alone application or a library. Note: when building a library, make sure to check the Ignore default checkbox to the right of the Additional Libraries text box, otherwise the default set of libraries will be included during the build and you will get errors.
Incremental Build Strategy		The default incremental build strategy is to compile all C files with the GCC -MF switch which generates dependency files consumed by the IDE and used for determining which files to rebuild. The other strategy is to always perform a full build.
Configuration		The configuration selected in this box is the one being edited.
Paths and Files	Additional Include Paths / Library Paths / Libraries	These three options allows the user to set additional C/C++ include paths, library paths and libraries to be used during compilation and linking. The Ignore Default checkboxes is an advanced option to exclude the MoSync system libraries from the build. Note that, from MoSync 2.5 onward, there are several Path Variables you can use in paths.
	Exclude file pattern	A space-separated list of files to not include in the build. An example could be test.c which will exclude all C files that start with test. There is an option to explicitly include files as well, which can be useful for example if all except one file in a directory should be included. To include a file, prefix the file with a + character. So the line /images +player1.png will exclude all files in the images directory except the player1.png* file. Files can also be excluded/included from a build by right clicking a file in the project explorer and selecting the Exclude From Build and Do Not Exclude From Build menu items respectively.
	Output File (libraries only)	The output file of the built library, relative to the project's Output directory.
	Output Directory (applications only)	The output directory of the built application, relative to the project's Output directory.
Compiler Flags	Activate Dead Code Elimination	This option instructs the linker to remove all redundant code from the resulting binary. (Only applicable for applications; we cannot tell which parts of a library is dead code before it has been incorporated in an application)
	Additional GCC Switches	Allows the user to set additional GCC switches. By default an optimization level switch is set for each configuration; -O0 for the debug configuration and -O2 for other configurations. Note: that no other optimization level than -O0 should be set for debug configurations as this will confuse the debugger and trigger errors during debugging.
	Additional Resource Compiler Switches / Additional Linker Switches	Allows the user to set additional compiler and linker switches. To get an overview of the available options, run Pipe-Tool from the Windows command line with the -h switch (pipe-tool -h).
	GCC Warnings	Compiler warning levels, corresponding to the GCC -Wall, -Wextra and -Werror switches.
	Memory Settings > Heap size / Stack size	Sets the amount of memory (in kilobytes) to allocate to the heap and the stack respectively. If your application runs our of memory (e.g. you get a "malloc failed" error) you can increase the amount of memory allocated for the heap. But see Memory Settings > Data size below for some limitations.
	Memory Settings > Data size	Sets the total amount of memory (in kilobytes) to allocate, including the heap and stack. The size will be rounded up to the nearest power of two. Memory settings must be chosen so they conform to the following rule: Data Size > Heap Size + Stack Size + Application's static data section Since there's no easy way of knowing the exact size of the statically allocated memory, a good rule of thumb is to use the following relationship: Data Size = n Heap Size = n/2 Different devices have different amounts of memory available. If you specify a Data Size greater than the amount of available memory on the device, your program will fail to execute.
Packaging	Use Debug Runtimes	This option instructs the packager to create packages with debug runtimes. Debug runtimes carry more information to aid the developer during application development. In particular more descriptive error messages will be shown if the debug runtimes are included. [And in the future, this is where on-device debugging support will be put.]
	Version	Your application's version number (major.minor), used as a label in the application packages. For example "2.4". Note that the minor version number may not be supported on all platforms. Default: "1.0".
	Publisher	Your publisher or vendor name, used as a label in the application packages. For example: "Joe Smith Software". Default: "Built with MoSync SDK". Note that some platforms (for example Android) have no publisher identification within the package. For Windows Mobile, this value will be used for both the "provider" and "manufacturer" label within the package.
	Application Name	The name to be used for the application's installation package. For example, if Application Name is to "MyCoolApp_setup", the installation package created for Android devices will be *MyCoolApp_setup.apk. If not set, the project's name will be used instead. Note: the name of the installed application will always be the project name, which can be changed by right-clicking on the project in Project Explorer and selecting Rename*.

Path Variables

MoSync 2.5+

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

%app-name%	Name of the application defined in "Build Settings" -> Packaging.
%app-vendor%	Application vendor defined in "Build Settings" -> Packaging.
%app-version%	Version of the application, as defined in "Build Settings" -> Packaging.
%compile-output-dir%	Path to the directory where the compiled source files will be stored.
%mosync-bin%	Path to the MoSync bin directory.
%mosync-home%	Path to the MoSync home defined by environment variable MOSYNCDIR.
%package-output-dir%	Path to the directory where the resulting package will be stored.
%platform%	The name of the platform in the profile being built for, e.g. android_7, wm6 etc.
%profile%	The device name in the profile being built for, e.g. Desire.
%programcomb-output%	Output directory of program.comb (combined program and resource files).
%program-output%	Path to the directory where the program file will be stored.
%project:<project>%	Path to the root of another project in the workspace, e.g. %project:3dlines%.
%project-name%	Name of the project.
%runtime-dir%	Path to the runtime directory.
%vendor%	The name of the vendor in the profile being built for, e.g. HTC.
%version-major%	Major part of the version number (see %app-version% above).
%version-micro%	Minor part of the version number (see %app-version% above).

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.