Cross-Compilation

Developers can cross-compile their Cangjie programs to run on different architecture platforms. Cangjie supports the following cross-compilation scenarios:

| Compilation Platform | Target Platform | Common Scenarios / Tools | Corresponding SDK Installation Package |
|-------------------------|-----------------------|-------------------------------|-------------------------------------------------|
| Windows (x64) | Android (aarch64) | Android physical devices | cangjie-sdk-windows-x64-android.x.y.z.zip (or .exe) |
| Linux (x64) | Android (aarch64) | Android physical devices | cangjie-sdk-linux-x64-android.x.y.z.tar.gz |
| macOS (aarch64/x64) | Android (aarch64) | Android physical devices and Android Studio Emulator | cangjie-sdk-mac-aarch64-android.x.y.z.tar.gz |
| macOS (aarch64) | iOS (aarch64) | iOS physical devices | cangjie-sdk-mac-aarch64-ios.x.y.z.tar.gz |
| macOS (aarch64) | iOS Simulator (aarch64/x86_64) |Xcode Simulator | cangjie-sdk-mac-aarch64-ios.x.y.z.tar.gz |

The Cangjie programming language now supports cross-compilation to Android API 26+ and iOS, enabling developers to build applications across different platforms.

Developers can use Cangjie installation packages that support cross-compilation for specific platforms (android-aarch64, android-x86_64). Cangjie provides installation packages for some cross-compilation supported platforms.

- cangjie-sdk-linux-x64-android.x.y.z.tar.gz
- cangjie-sdk-windows-x64-android.x.y.z.zip
- cangjie-sdk-windows-x64-android.x.y.z.exe
- cangjie-sdk-mac-aarch64-android.x.y.z.tar.gz

For example: To cross-compile to Android API 26+ on a linux x64 platform, download and install the cangjie-sdk-linux-x64-android.x.y.z.tar.gz package.

In addition to the cross-compilation supported Cangjie package, you also need to download the Android NDK supporting Android API 26+. Please download the latest NDK package from the official Android website.

Cross-compiling Cangjie to Android API 26+ requires the following two dependency directories:

1. sysroot directory, provided by Android NDK, typically located at /toolchains/llvm/prebuilt//sysroot.

2. Directory containing libclang_rt.builtins-aarch64-android.a, provided by Android NDK, typically located at /toolchains/llvm/prebuilt//lib64/clang//lib/linux.

When using cjc for cross-compilation, the following additional options must be specified (replace < > parts with actual directories):

- --target=aarch64-linux-android defaults to API 26 for cross-compilation; append the API level suffix explicitly for a higher version, e.g. --target=aarch64-linux-android31 for API 31.
- --sysroot= specifies the toolchain's root directory path
- -L specifies the directory containing libclang_rt.builtins-aarch64-android.a

Example command:

After compilation, the following files need to be pushed to the Android device:

- The executable and all its dependent dynamic libraries: e.g., main and its dependent .so files
- Cangjie runtime dependencies: $CANGJIE_HOME/runtime/lib/linux_android31_aarch64_cjnative/*.so

Use the Android Debug Bridge adb tool to push the executable and Cangjie libraries to the device. Example:

For detailed usage of the adb tool, please refer to the Android Debug Bridge (adb) documentation on the official Android website.

To run the Cangjie program main:

The Cangjie SDK that supports cross-compiling for iOS is provided as cangjie-sdk-mac-aarch64-ios.x.y.z.tar.gz .

To cross-compile to iOS on a macOS platform, download and install the package that matches your host architecture . The Cangjie runtime and standard libraries natively support iOS 11 and above (for exceptions, refer to the "Cangjie Programming Language Library API" manual).

In addition to the cross-compilation supported Cangjie package, you also need to download Xcode. After installation, install the iOS development components in Xcode. Refer to the "Downloading and installing additional Xcode components" section in the Xcode manual for specific steps.

Currently, Cangjie cross-compilation to iOS only supports compiling static libraries. When cross-compiling Cangjie code to iOS devices, specify the following additional options:

- --target=aarch64-apple-ios specifies the target platform ios for cross-compilation
- --output-type=staticlib specifies the output file type as a static library

> Notes：
>
> The version number specified by \ is recommended to align with the SDK version supported by the installed Xcode (e.g., 17.5).

Currently, Cangjie supports cross-compiling to the x86_64 architecture iOS simulator from an aarch64 architecture environment (the compiled product for this architecture requires Rosetta in Xcode to run).For running on iOS simulators, specify:

- --target=aarch64-apple-ios-simulator or --target=x86_64-apple-ios-simulator specifies the target platform ios-simulator for cross-compilation
- --output-type=staticlib specifies the output file type as a static library

The compilation output must be added to an Xcode project and built through Xcode to create an iOS application.

Example command to compile main.cj into libmain.a static library:

In addition to adding the Cangjie compilation output to the Xcode project, the following configurations are required when building with Xcode:

1. Select a directory based on the runtime target (device or simulator):

- For devices: $CANGJIE_HOME/lib/ios_aarch64_cjnative

- For simulators: $CANGJIE_HOME/lib/ios_simulator_aarch64_cjnative

Add all .a files from the corresponding directory to the Xcode project.

2. Configure the Build Settings > Other Linker Flags field in the Xcode project with the following values:

- $CANGJIE_HOME/lib/ios_aarch64_cjnative/section.o

- $CANGJIE_HOME/lib/ios_aarch64_cjnative/cjstart.o

- -lc++

Note: The linking options must be added in the exact order listed above. Replace $CANGJIE_HOME with the actual Cangjie installation directory. For simulator targets, replace ios_aarch64_cjnative with ios_simulator_aarch64_cjnative.

3. Set the Build Settings > Dead Code Stripping field in the Xcode project to No.

After configuration, build the project directly through Xcode.

Build and deploy to real devices or simulators through Xcode. Refer to the "Build and running an app" section in the Xcode manual for specific steps.