# iOS Module Project

# Introduction

This guide covers how to manage your module project as well as how to add third-party frameworks and bundle assets with your module.

# Prerequisite

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.

# Project structure

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.

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

The 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.

• TITANIUM_BASE_SDK3: Path to the Titanium SDK iOS JavaScriptCore 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_VERSION and 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. (opens new window)

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 $(inherited).

OTHER_LDFLAGS=$(inherited) -framework CoreML

# Manifest file

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:

# CLI tasks

# Create a new module project

To create a new module project, run the following Titanium CLI command:

appc new -d /PATH/TO/WORKSPACE -n <MODULE_NAME> --id <MODULE_ID>
### when prompted for the project type, select "Titanium Module"

### Example
$ appc new -p ios -n test --id com.example.test
Appcelerator Command-Line Interface, version 7.0.2
Copyright (c) 2014-2018, Appcelerator, Inc.  All Rights Reserved.
? What type of project are you creating?
  Native App
  Arrow App
❯ Titanium Module
  Apple Watch App

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 ios directory.

cd /<PATH_TO_MODULE_PROJECT>/<MODULE_NAME>/ios
ti build -p ios --build-only

After the build completes, you should have a ZIP file in the iphone directory and see the following message in the console:

** BUILD SUCCEEDED **

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

# Studio tasks

# Create a new module project

1. From the menu, select File > New > Mobile Module Project to open the New Mobile Module Project dialog.

2. In the Project name field, enter a name for the module.

3. In the Module Id field, enter a module ID for the module.

4. In Deployment Targets, select iOS.

5. Click Next.

6. 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 manifest file later.

7. Click Finish.

# Build and package the module

1. Select your module folder in the Project Explorer view.

2. Verify Package and iOS Module are displayed in Launch Mode and Launch Target, respectively.

3. Click the Package icon to open the Package iOS Module dialog.

4. In Output Location, select either

   1. Titanium SDK to install the module in the Titanium SDK home path to be accessed by any Titanium application

   2. Mobile App Project and choose an application to install the module locally that can be accessed by one that Titanium application

   3. Location and enter a path to copy the ZIP file to for distribution

5. Click Finish.

# Test the module

To test a module:

1. Create a new Titanium Classic or Alloy project.

2. Install the module to either the Titanium SDK home directory or in the project.

3. Add the module as a dependency to the project.

4. 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.

1. Close the module project if it is open in Xcode.

2. Open the test application's Xcode project (PROJECT_NAME/build/iphone/PROJECT_NAME.xcodeproj).

3. Expand the Frameworks folder, right-click the module library (lib<MODULE_ID>.a) and select Delete.

4. Click Remove Reference.

5. Right-click the project name and select Add Files to PROJECT_NAME...

6. In the dialog:

   1. Locate your module's Xcode project and select it.

   2. Uncheck Copy item if needed if it is checked.

   3. Select all targets under Add to targets.

   4. Click Add.

7. In the project's Build Phases:

   1. Under Target Dependencies, click the Add button, then select the module and click Add.

   2. Under Link Binaries with Libraries, click the Add button, then select the module library (lib<MODULE_ID>.a) and click Add.

8. 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.

1. Copy the framework to the module project's ios/platform directory.

2. Open the module project (ios/<PROJECT_NAME>.xcodeproj)in Xcode.

3. Add the framework to the project: Right-click the project name and select Add File to PROJECT_NAME...

# Bundle module assets

To distribute module assets with your module distribution, you must place them in the assets directory of your project. Any assets within this folder (with the exception of JavaScript files) will be distributed and copied into the folder pattern module/<moduleid> in the application bundle. You can then load them using this relative path from your Objective-C code. For example, assuming you had a module image named "foo.png". You could load that using the following example:

NSString *path = [NSString stringWithFormat:@"modules/%@/foo.png",[self moduleId]];
NSURL *url = [TiUtils toURL:path proxy:self];
UIImage *image = [TiUtils image:url proxy:self];

# 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:

1. Copy the .clang-format file from here (opens new window) to the "ios/" directory of your module project, e.g. <module-root>/ios/.clang-format

2. Install the clang-format CLI (opens new window): npm install -g clang-format

3. 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

4. Format your source with: clang-format -style=file -i Classes/*

5. 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.