Titanium SDK selection defaults to newest, breaking repeatable builds

Question

Symptom

When building a Titanium project with the CLI, the build process frequently picks the most recently installed SDK even though the project’s tiapp.xml specifies a different <sdk-version>. This leads to build failures on CI pipelines that expect a stable, pinned SDK.

Constraints & Uncertainties

The SDK Manager can install multiple SDKs, but project‑level selection defaults to the latest unless explicitly overridden.
The CLI’s --sdk flag works, yet the <sdk-version> tag is ignored when the flag is omitted.
Appcelerator Studio caches SDK paths in its preferences; after Studio updates or SDK reinstallations these paths can become stale, further confusing the selection.
No official lockfile or pinning mechanism exists; developers rely on manual configuration or environment variables.
The TI_SDK_HOME environment variable can override SDK selection, but its behavior varies across operating systems and is not consistently documented.

Goal

Determine a reliable method to pin a Titanium project to a specific SDK version so that builds are repeatable across local, CI, and Studio environments.

Unresolved Questions

Does the <sdk-version> tag in tiapp.xml enforce SDK selection when the CLI --sdk flag is omitted?
Is the TI_SDK_HOME environment variable consistently able to override Studio‑managed SDK paths on Windows, macOS, and Linux?
What mechanism, if any, can be introduced or leveraged to lock a project to a specific SDK version, ensuring repeatable builds?

Tasadduq Burney · Answer

Answer the exact question first

When the TI_SDK_HOME environment variable is unset and the CLI --sdk flag is omitted, the Titanium CLI honors the <sdk-version> tag in tiapp.xml. If TI_SDK_HOME is set or the --sdk flag is supplied, the CLI ignores tiapp.xml and picks the SDK specified by those mechanisms. Appcelerator Studio behaves the same way but also caches SDK paths in its preferences, which can override the tiapp.xml setting if not cleared.

Likely Explanation

By default the CLI chooses the newest installed SDK when TI_SDK_HOME is not defined. This is why builds on CI that have multiple SDKs installed frequently end up using the latest one, even if tiapp.xml requests an older version. Studio’s cached SDK preferences can also point to a newer SDK after an update, causing the same problem in IDE builds.

Confirmed Facts

Setting TI_SDK_HOME to the exact installation directory of the desired SDK forces both the CLI and Studio to use that SDK, overriding tiapp.xml and any cached preferences.
The --sdk CLI flag is a one‑shot override that works the same way as TI_SDK_HOME, but it must be specified on every build command.
Studio caches the SDK path in Window → Preferences → Titanium → SDK; clearing this cache or restarting Studio after changing TI_SDK_HOME is required for the IDE to pick up the new path.
On Windows, TI_SDK_HOME must use backslashes or quoted paths; otherwise the variable is ignored and the CLI falls back to the latest SDK.

Practical Steps for Repeatable Builds

Identify the exact SDK path
Run titanium sdk list to see the full installation directories. Pick the one that matches your desired <sdk-version>.

Export TI_SDK_HOME
On macOS/Linux:

export TI_SDK_HOME=/opt/appcelerator/titanium/mobilesdk/9.4.0.GA

On Windows (Command Prompt):

set TI_SDK_HOME=C:\Appcelerator\titanium\mobilesdk\9.4.0.GA

On Windows (PowerShell):

$env:TI_SDK_HOME = 'C:\Appcelerator\titanium\mobilesdk\9.4.0.GA'

Verify the variable
Before a build, echo the variable and check the CLI log for the line:
```
[INFO] Using SDK: /opt/appcelerator/titanium/mobilesdk/9.4.0.GA
```
Integrate into CI
Add the export step to your build script or CI job definition so that every build starts with the correct TI_SDK_HOME.
Clear Studio cache (if using the IDE)
After setting TI_SDK_HOME, open Window → Preferences → Titanium → SDK, remove any cached paths, and restart Studio. Verify that the project properties now show the same path as TI_SDK_HOME.
Optional wrapper script
Create a small wrapper (e.g., build.sh) that sets TI_SDK_HOME and then invokes titanium build. Commit this script to the repository so local developers automatically use the pinned SDK.

What to Ask Next

If you have multiple SDKs installed under different base directories, confirm that TI_SDK_HOME points to the exact version folder, not just the parent directory. This detail can change the recommendation because pointing to a parent will still let the CLI pick the newest sub‑version.

Summary

Pinning a Titanium project to a specific SDK is reliably achieved by exporting the TI_SDK_HOME environment variable to the full SDK installation path. This method works across the CLI, CI pipelines, and Appcelerator Studio, provided Studio’s cached preferences are cleared or restarted. The <sdk-version> tag in tiapp.xml is only respected when TI_SDK_HOME is unset and the --sdk flag is omitted.