Inspect and Extract ICU Data Packages with icupkg

icupkg lets you list what is inside an ICU .dat package, pull out selected items, and write a separate output package without touching the original. The examples use icupkg 74.2 from the Ubuntu icu-devtools package, version 74.2-1ubuntu3.1.

Allow about fifteen minutes. You need a shell, the ICU development tools, and an ICU data package to look at. None of the commands below need sudo. Work on a copy when the package belongs to a running application: an invalid or incomplete data file can stop ICU consumers from starting at all.

1. Confirm the installed command

Start by checking which executable will run and which package supplied it. These are ordinary, read-only commands:

$ command -v icupkg
/usr/bin/icupkg
$ dpkg-query -W -f='${Package} ${Version}\n' icu-devtools
icu-devtools 74.2-1ubuntu3.1
$ icupkg --help
usage: icupkg [-h|-?|--help ] [-tl|-tb|-te] ...

The installed --help output is the most reliable contract for this binary. The local icupkg(8) manpage is older and covers the core options: --list, --extract, --add, --remove, --sourcedir and --destdir. ICU 74.2 also prints newer options such as --ignore-deps, --toc_prefix and --outlist. Treat those as version-specific and check --help again before using them on another host.

2. List a package without changing it

Set a clear placeholder for the package you want to inspect. Use an absolute path if the file is not in your current directory:

$ PACKAGE=/path/to/icudt74l.dat
$ test -r "$PACKAGE" && echo "readable: $PACKAGE"
readable: /path/to/icudt74l.dat
$ icupkg --list "$PACKAGE"
root.res
coll/ucadata.icu
...

The exact item names depend on the package. The list prints after any requested modifications, so a plain --list is always a safe inventory operation. Do not confuse an item name with a filesystem path: package entries are relative to the package and can contain directories of their own.

No package to hand? You can still prove the tool works by creating an empty one in a temporary, disposable directory:

$ mkdir -p "$HOME/tmp/icupkg-check"
$ icupkg new "$HOME/tmp/icupkg-check/empty.dat"
$ icupkg --list "$HOME/tmp/icupkg-check/empty.dat"
$ echo "exit status: $?"
exit status: 0

An empty listing is exactly what you should see. Keep this test package well away from any real ICU files.

3. Extract selected items to a directory

Pick an item from the listing, then pull it out with --extract. The destination directory gets prepended to item names; the package filename itself does not:

$ WORK=/path/to/icupkg-work
$ mkdir -p "$WORK/extracted"
$ ITEM='coll/ucadata.icu'
$ icupkg --extract "$ITEM" --destdir "$WORK/extracted" "$PACKAGE" "$WORK/unchanged-copy.dat"
$ find "$WORK/extracted" -type f -print
/path/to/icupkg-work/extracted/coll/ucadata.icu

Give a different output filename and icupkg writes a package as well as extracting the item. Leave the output filename off and the utility invents one from the input name whenever it needs to write a result. An explicit output path is easier to review and stops you guessing which file just got generated.

4. Use a list file for several items

A list file holds whitespace-separated item names. Blank lines and lines starting with # are ignored. Paths inside it are relative to the package:

$ cat > "$WORK/extract-items.txt" <<'EOF'
# Resources needed for this inspection
root.res
coll/ucadata.icu
EOF
$ icupkg --extract "$WORK/extract-items.txt" \
    --destdir "$WORK/extracted-many" "$PACKAGE" "$WORK/many-copy.dat"
$ find "$WORK/extracted-many" -type f -print

For removal and extraction, one item name may carry a single * wildcard, and by default it can match the slash separator too. Add --matchmode noslash when the wildcard needs to stay inside one path component. Start with an explicit item or a short list; a broad wildcard can sweep up more data than you meant.

5. Create a modified package safely

--remove and --add change the package contents. The tool processes removals, then additions, then extraction and listing, in that order. Write to a new file first so the original stays available for recovery:

$ icupkg --remove "$WORK/remove-items.txt" \
    "$PACKAGE" "$WORK/reduced.dat"
$ icupkg --list "$WORK/reduced.dat" > "$WORK/reduced-list.txt"
$ sed -n '1,12p' "$WORK/reduced-list.txt"

The list passed to --remove follows the same syntax as an extraction list. An added item has to be a genuine ICU data item, not an arbitrary text file. The source directory given with --sourcedir gets prepended to item filenames while adding; it is never prepended to the list-file or package filename.

6. Swap a package or single data file for another platform

The type options pick the output platform family: --type l is little-endian with an ASCII charset family, --type b is big-endian with ASCII, and --type e is big-endian with EBCDIC. The input type sticks unless you ask for another one.

$ icupkg --type l --writepkg \
    "$PACKAGE" "$WORK/platform-copy.dat"
$ file "$WORK/platform-copy.dat"
$ icupkg --list "$WORK/platform-copy.dat" > "$WORK/platform-list.txt"
$ diff -u <(icupkg --list "$PACKAGE") "$WORK/platform-list.txt"

--writepkg matters when the operation would otherwise only inspect or swap data without adding or removing items. The same mode can handle a non-package ICU data file, but only the type, write, source-directory and destination-directory options are allowed there. Do not combine it with package item operations.

7. Diagnose failures without guessing

For a missing item, rerun the list command and compare the exact relative name character by character. For dependency failures, read the diagnostic before reaching for ICU 74.2's --ignore-deps: that option deliberately allows unresolved resources through, and can hand you a package an application cannot actually use.

$ icupkg --extract 'name-from-the-list' \
    --destdir "$WORK/extracted" "$PACKAGE" "$WORK/test.dat"
icupkg: ...
$ echo "exit status: $?"
exit status: 1

The wording and the numeric status can both vary with the failure. A non-zero status is the signal that matters. Keep the original package and the command output together when you report a problem.