- Project Structure
- CLI Tasks
- Studio Tasks
- Test the Module
- Add a Third-Party Framework
- Bundle Module Assets
- Distribute your Module through the Appcelerator Marketplace
This guide covers how to manage your module project as well as how to add third-party frameworks and bundle assets with your module.
In order to develop iOS modules, you need to have your environment setup to build iOS applications with the Titanium SDK as well as the Python Markdown module.
- To setup Titanium, see Setting up Studio.
- To setup your environment for iOS, see Installing the iOS SDK.
- To install Markdown, see Installing Required Python Packages.
When you create a new project, it generates the following directories and files. Titanium expects to find files in certain directories with a specific naming convention.
Filename / Directory
Description / Purpose
A special .gitignore file used by the revision control system git to instruct it to ignore certain temporary files and directories. This file is not distributed with your module. This file can be safely ignored if you are not using git.
The file that gives a short explanation of the module project. This file is not distributed with your module.
The directory where you should place module assets, such as images.
The directory where you should place your module documentation for end-users. The file index.md is a Markdown-formatted template file that you should use when writing your module documentation. You may also write your documentation using the TDoc Specification. This is only required for module distributed in the Appcelerator Marketplace. You can safely ignore this directory if you do not intend to distribute your module.
The directory where your module example(s) should go. The file app.js will be generated to include a sample loading of your module in a test window. This file can be used for quickly testing your module as well as give an example to end-users on how to use your module. This directory is distributed with your module.
The directory where you Objective-C headers and implementation classes should go, used by the Xcode compiler. By default, when you create a new project, you are given a boiler plate module class (
The pre-compiled header file used by the Xcode compiler. This file is not distributed with your module.
A special file that describes metadata about your module and used by the Titanium compiler. This file is required and is distributed with your module.
A special file used by Xcode when your module is compiled in an end-user Titanium application which references your module.
Directory for platform-specific assets. This is analogous to the
|iphone/Resources||Directory for platform-specific assets. This is analogous to the |
The directory which contains your Xcode project. Open this directory to launch your module project in Xcode. This directory is not distributed with your module.
Titanium module configuration file. The format is described in tiapp.xml and timodule.xml Reference. This file is not currently supported by iOS modules.
A special file used by Xcode when your module is compiled when building your module. This file is a Xcode configuration file which can setup special compiler and linker directives that are specific to your module. This file is not distributed with your module and only used during module development.
Titanium Xcconfig File
titanium.xcconfig file is used when compiling your module for packaging. It defines the following environment variables:
TITANIUM_SDK_VERSION: Version of the Titanium SDK to build the module library.
TITANIUM_SDK: Path to the Titanium SDK.
TITANIUM_BASE_SDK: Path to the Titanium SDK iOS header files. Do not modify.
TITANIUM_BASE_SDK2: Path to the Titanium SDK iOS TiCore header files. Do not modify.
HEADER_SEARCH_PATHS: Path to the Titanium SDK header files. Do not modify.
Normally, you do not need to edit this file once it is created. If you delete the Titanium SDK referenced by the file, you need to update the
TITANIUM_SDK variables to use another Titanium SDK to build the module.
Module Xcconfig File
If your module needs a special Framework, other system library or special compiler directives, you can use the module's
xcconfig file to define them. The
module.xcconfig is used by the application compiler when the application is built and your module is referenced. This allows you to control the compiler directives used during this process.
For a list of variables you can add to this file, see Xcode Build Setting Reference: Build Setting Reference
For example, if you include the
GameKit framework with your module, you need to modify the
OTHER_LDFLAGS variable to include the framework. To not overwrite the Titanium application's
OTHER_LDFLAGS variable, add
Titanium module metadata is described in a special text file named
manifest. This file is a simple key/value property format.
Before you distribute your module, you must edit this manifest and change a few values. Some of the values are pre-generated and should not be edited. These are noted with the comment before them. In the manifest file, any line starting with a hash character (#) is ignored. The following are the descriptions of each entry in the manifest:
This is the version of your module. You should change this value each time you make major changes and distribute them. Version should be in the dotted notation (X.Y.Z) and must not con-tain any spaces or non-number characters.
|architectures||The binary architectures the module supports as a delimited list. Example: armv7 arm64 i386 x86_64|
This is a human-readable description of your module. It should be short and suitable for display next to your module name.
This is a human-readable author name you want to display next to your module. It can simply be your personal name, such as "Jeff Haynie" or an organizational name such as "Appcelerator".
This is a human-readable name of your license. You should use a short description such as "Apache Public License" or "Commercial".
This is a human-readable copyright string for your module. For example, "Copyright (c) 2010 by Appcelerator, Inc."
This is a read-only name of your module that is generated when you created your project. You must not edit this value.
This is a read-only module id of your module that is generated when you created your project. You should not edit this value. NOTE: you must generate a unique id. We recommend using your reverse-DNS company name + module_name as a pattern to guarantee uniqueness. The Titanium Marketplace will only allow unique module ids when distributing modules. If you must edit this value, you must also edit the value in your module implementation file.
This is a read-only unique module id for your module that is generated when you created your project. You must not edit this value.
This is a read-only platform target of your module that is generated when you created your project. You must not edit this value.
The is a generated value for the minimum Titanium SDK version that was used when creating your module. This is currently not used and reserved for future use.
Create a New Module Project
To create a new module project, run the following Titanium CLI command:
If you omit any of the options, the CLI will prompt you to enter them.
Build and Package the Module
To build and package a module, run the
ti build command inside the
After the build completes, you should have a ZIP file in the
iphone directory and see the following message in the console:
With the ZIP file, you can either:
- Uncompress it in the Titanium SDK home path to install the module globally for all your Titanium applications
- Uncompress it in a Titanium project's parent directory to install the module locally for that one Titanium application
- Distribute the ZIP file
Create a New Module Project
- From the menu, select File > New > Mobile Module Project to open the New Mobile Module Project dialog.
- In the Project name field, enter a name for the module.
- In the Module Id field, enter a module ID for the module.
- In Deployment Targets, select iOS.
- Click Next.
- In the Module Manifest File page, enter information about your module, such as the license information, version number, etc. You can also edit this information in the
- Click Finish.
Build and Package the Module
- Select your module folder in the Project Explorer view.
- Verify Package and iOS Module are displayed in Launch Mode and Launch Target, respectively.
- Click the Package icon to open the Package iOS Module dialog.
- In Output Location, select either
- Titanium SDK to install the module in the Titanium SDK home path to be accessed by any Titanium application
- Mobile App Project and choose an application to install the module locally that can be accessed by one that Titanium application
- Location and enter a path to copy the ZIP file to for distribution
- Click Finish.
Test the Module
To test a module:
- Create a new Titanium Classic or Alloy project.
- Install the module to either the Titanium SDK home directory or in the project.
- Add the module as a dependency to the project.
- Load the module and make module API calls.
Link the Test Application and the Module Projects
To make it easier to debug your module, you can link the module to the test application. Then you can run the test application, which will rebuild the module project. You need to build the test application and module project at least once before proceeding.
- Close the module project if it is open in Xcode.
- Open the test application's Xcode project (
- Expand the Frameworks folder, right-click the module library (
lib<MODULE_ID>.a) and select Delete.
- Click Remove Reference.
- Right-click the project name and select Add Files to <PROJECT_NAME>...
- In the dialog:
- Locate your module's Xcode project and select it.
- Uncheck Copy item if needed if it is checked.
- Select all targets under Add to targets.
- Click Add.
- In the project's Build Phases:
- Under Target Dependencies, click the Add button, then select the module and click Add.
- Under Link Binaries with Libraries, click the Add button, then select the module library (
lib<MODULE_ID>.a) and click Add.
- From the menu bar, select Product > Clean.
After you are done, the module Xcode project should be under the test application Xcode project. Expand the module Xcode project. You can edit and work on your module project, then build the test application project to test the module.
If the module project appears under the test application project, but you cannot expand the module project, the module project was opened when you linked the two projects together. Exit Xcode, then reopen the test application Xcode project.
Add a Third-Party Framework
To use a third-party framework in your module, add the framework to the module's
platform directory, so it can be copied over during the module's build process and linked when building the application. Add and setup the framework in Xcode, then code and build your project to verify the project compiles correctly. You need to modify the module's
module.xxconfig file to include the path to the framework when it is installed in a local project or globally in the Titanium SDK home directory, and modify the linker flags to include the framework when building the application.
- Copy the framework to the module project's
- Open the module project in Xcode. Open the
- Add the framework to the project. Right-click the project name and select Add File to <PROJECT_NAME>...
- Follow any additional directions to incorporate the framework, such as adding additional linker flags.
- Verify that the framework is included in the project. In Build Phases, check that the framework is listed in the Link Binary With Libraries section.
- In your header and source files, add the framework's header files and add the third-party APIs.
- Build your project in Xcode to verify it will compile and link correctly.
Open the module project's
iphone/module.xcconfigfile and set the:
FRAMEWORK_SEARCH_PATHSvariable to the path(s) to the module's
platformfolder once it is installed. The example below specifies the local install location and global install locations.
OTHER_LDFLAGSvariable to the
<FRAMEWORK_NAME>for each framework you are adding. Add the
$(inherited)variable to the beginning to not overwrite the variable for the application build command.
Bundle Module Assets
To distribute module assets with your module distribution, you must place them in the
Distribute your Module through the Appcelerator Marketplace
To distribute your module through the Titanium+Plus Marketplace, you'll first need to package normally. Once you have tested your module locally and are ready to distribute it, you can then submit it to the marketplace for distribution. There are several prerequisites you'll need before you can distribute:
- You must have a valid Titanium developer account.
- You must have fully completed filling our your manifest values.
- You must have a valid license text in the LICENSE file in your project.
- You must have a valid documentation file in the index.md file in your documentation directory of your project.
- You must specify some additional metadata upon upload such as the price (which can be free).
- If you are charging for your module, you must establish a payment setup with Appcelerator so we can pay you.
- You must accept the Titanium+Plus Marketplace terms of service agreement.
Once you have upload your module and completed the necessary submission steps, your module will be queued for submission and availability in the marketplace directory.