- Project structure
- CLI tasks
- Studio tasks
- Test the module
- Add a third-party framework
- Bundle module assets
- Format / Lint source-code
- 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.
- To setup Titanium, see Setting up Studio.
To setup your environment for iOS, see Installing the iOS SDK.
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
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
The directory where your module example(s) should go. The file
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 to place native frameworks and (static) libraries in. Examples are
|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.
The CLI generates a module project containing multiple platforms. The module contains platform-dependent folders, for example,
ios , that contain platform-specific resources and common folders for assets, documentation and examples.
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.
For example, if you include the iOS 11
CoreML 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 contain any spaces or non-number characters.
The internal module API version of the SDK that is required to build this module. Currently this is at version 2 for iOS modules which is supported by all recent versions of the Titanium SDK. By default, this will be automatically set to the module API version of the SDK that was used when creating your module.
You only need to ever change this if a new SDK has internal breaking changes to the module API. In the rare event that the module API did change, you need to migrate the module to the new module API and then update this property to match the API version of the SDK you are trying to build with.
|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 "Jon Doe" or an organizational name such as "Axway Appcelerator".
This is a human-readable name of your license. You should use a short description such as "Apache Public License", "MIT" or "Commercial".
This is a human-readable copyright string for your module. For example, "Copyright (c) 2010-Present by Axway 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.
Indicates the minimum version of the SDK your module is compatible with. Users of your module will need to build their app with the specified SDK version (or later versions). This will be set to the Titanium SDK version that was used when creating your module by default. Adjust this if you change your module later on and use features that were introduced in new versions of the Titanium SDK or you know that your module is compatible with older versions of Titanium SDK as well.
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
appc run -p ios --build-only 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
Since release 6.2.0, Titanium supports both static and dynamic framworks. Frameworks written in Swift are also supported if they expose an Objective-C interface header in combination with the Swift framework hook. Please refer to the individual framework to see if it meets this requirement to be used with Titanium and if it requires additional configuration.
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. If you are targeting Titanium 6.2.0 and above, these setup steps is all you have to complete as the frameworks will be integrated automatically. In older versions, you need to take additional steps to modify the module's
module.xcconfig 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 and open
- 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 static frameworks are listed in the Link Binary With Libraries section. Dynamic frameworks need to be added to the Embedded Binaries section, which will also generate the entry 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.
Optional: this step is only required if your module needs to be compatible with in Titanium 6.2.0 and earlier: Open the module project's
ios/module.xcconfigfile and set the:
FRAMEWORK_SEARCH_PATHSvariable to the path(s) to the module's
platformdirectory 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.
Set any other build settings the framework might require via the module's
ios/module.xconfigto make sure they get applied when building the application.
- Build your project in Xcode to verify it will compile and link correctly.
Bundle module assets
To distribute module assets with your module distribution, you must place them in the
Format / Lint source-code
The Titanium SDK uses clang-format to have a unified code-style in its source-code (clang-format for iOS and Android, ESLint for the CLI). You can do the same by following the following few steps:
- Copy the
.clang-formatfile from here to the "
ios/" directory of your module project, e.g.
- Install the clang-format CLI:
npm install -g clang-format
Optional: Ensure that you have your module project in Git to be able to restore the old files in case you do not like the predefined format
- Format your source with:
clang-format -style=file -i Classes/*
- Thats it! All native files have been formatted.
Now that you have a format, you can also extend your .clang-format with more formatting rules or adjust existing ones to match your own code style.
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 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.mdfile 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.