This repository provides a universal build script for creating static ICU libraries for iOS, watchOS, tvOS, visionOS, macOS, and Mac Catalyst.

The ICU source code is taken from the official Unicode ICU repository: https://github.com/unicode-org/icu

Repository branches generally correspond to ICU maintenance branches. For example, the 78 branch corresponds to the maint/maint-78 branch in the ICU repository.

• 78.2
• 78.1
• 77.1
• 76.1
• 75.1
• 74.2
• 74.1
• 73.2
• 73.1
• 72.1
• 71.1
• 70.1
• 69.1
• 68.2
• 62.2

1. Xcode must be installed, as xcodebuild is used to create XCFrameworks.

2. xcode-select -p must point to the Xcode developer directory (for example, /Applications/Xcode.app/Contents/Developer).

   If it points to the CommandLineTools directory, run one of the following commands:

   sudo xcode-select --reset
   # or
   sudo xcode-select -s /Applications/Xcode.app/Contents/Developer

# Clone the repository
git clone https://github.com/apotocki/icu4c-iosx
    
# Build libraries
cd icu4c-iosx
scripts/build.sh

The resulting artifacts will be located in the product directory.

Running build.sh without arguments builds XCFrameworks for iOS and macOS, and also for watchOS, tvOS, and visionOS if their SDKs are installed. Simulator XCFrameworks are built for the current host architecture (arm64 or x86_64).

To build a specific set of platforms or architectures, use the -p option:

scripts/build.sh -p=ios,iossim-x86_64
# Builds XCFrameworks only for iOS and the iOS Simulator (x86_64)

macosx,macosx-arm64,macosx-x86_64,macosx-both,
ios,iossim,iossim-arm64,iossim-x86_64,iossim-both,
catalyst,catalyst-arm64,catalyst-x86_64,catalyst-both,
xros,xrossim,xrossim-arm64,xrossim-x86_64,xrossim-both,
tvos,tvossim,tvossim-arm64,tvossim-x86_64,tvossim-both,
watchos,watchossim,watchossim-arm64,watchossim-x86_64,watchossim-both

• The -both suffix builds XCFrameworks for both arm64 and x86_64.
• Platform names without an architecture suffix (for example, macosx, iossim) build only for the current host architecture.

The build.sh script builds the following XCFrameworks:

• icudata
• icui18n
• icuio
• icuuc

By default, icudata is built with --with-data-packaging=static (see the ICU data documentation). All ICU metadata (locales, tables, rules, etc.) is embedded directly into the icudata library, making it relatively large (~32 MB).

Because an XCFramework may include multiple platforms and architectures, this metadata is duplicated several times, increasing the overall size. ICU allows this data to be moved into a separate, platform-independent archive that is loaded at runtime.

To enable this option, use -d=archive:

scripts/build.sh -p=ios,iossim-x86_64 -d=archive
# Builds XCFrameworks for iOS and the iOS Simulator (x86_64)
# Data file path: product/share/icu/78.2/icudt78l.dat

During ICU initialization, you must specify the ICU data directory before calling u_init():

#include <unicode/putil.h>
#include <unicode/uclean.h>

// Specify the directory containing the ICU data file
u_setDataDirectory("PATH_TO_DIRECTORY_CONTAINING_icudt78l.dat");

UErrorCode errCode = U_ZERO_ERROR;
u_init(&errCode);
if (U_FAILURE(errCode)) {
    // Handle initialization error
    ...
}

// Use ICU API...

u_cleanup();  // Optional: release ICU resources

ICU metadata includes a large collection of locales, tables, and rules. In most applications, only a subset of this data is required.

You can reduce the size of icudata by applying a data filter using the -f option:

scripts/build.sh -p=ios,iossim-x86_64 -f=path_to_filter.json
# Builds XCFrameworks for iOS and the iOS Simulator (x86_64)

The filter format is described in the official ICU documentation: https://unicode-org.github.io/icu/userguide/icu_data/buildtool.html

To rebuild the libraries without using artifacts from previous builds, use the --rebuild option:

scripts/build.sh -p=ios,iossim-x86_64 --rebuild

Add the following to your Podfile:

use_frameworks!
pod 'icu4c-iosx'
    
# Or explicitly reference the repository
# pod 'icu4c-iosx', :git => 'https://github.com/apotocki/icu4c-iosx'

Install the dependency:

   pod install --verbose

The ICU libraries built by this project are used in my iOS application available on the App Store:

	PotoHEX HEX File Viewer & Editor

PotoHEX is designed for viewing and editing files at the byte or character level, calculating hashes, encoding/decoding data, and compressing/decompressing selected byte ranges.

If you find this project useful, you can support my open-source work by trying the App.

Feedback is welcome!