ICU timezone data

This document describes Fuchsia's support for loading ICU timezone data from ICU data files (icudtl.dat). Programs load timezone data dynamically based on the resources most appropriate for their application.

For more details on the general use of ICU APIs in Fuchsia, see International Components for Unicode use in Fuchsia

Make the ICU data available

In order for the system default ICU data files to be visible to a program in Fuchsia, you must include the resource dependency in your package:

"//src/intl:icudtl",

Timezone configuration data

To provide a specific version of the timezone data files to your component, request the appropriate directory capability in your component manifest:

// Capabilities used by this component.
use: [
    {
        directory: "tzdata-icu-44-le",
        rights: [ "r*" ],
        path: "/config/tzdata",
    },
],

Load the ICU data

You must load the ICU data in your program to make the locale data available. Otherwise, no locale data will be available and your ICU code will behave as if the set of i18n data is empty.

Include the ICU data library dependency in your BUILD.gn file:

C++

third_party_icu_headers("icu_headers") {
  headers = [
    "third_party/icu/source/common/unicode/utypes.h",
    "third_party/icu/source/i18n/unicode/timezone.h",
  ]
}

executable("bin") {
  testonly = true
  output_name = "tz_version_parrot_cpp"

  sources = [ "test.cc" ]

  deps = [
    ":icu_headers",
    "//sdk/lib/sys/cpp",
    "//sdk/lib/syslog/cpp",
    "//src/lib/files",
    "//src/lib/fxl/test:gtest_main",
    "//src/lib/icu_data/cpp",
    "//third_party/googletest:gtest",
  ]
}

Rust

deps = [ "//src/lib/icu_data/rust/icu_data" ]
non_rust_deps = [ "//src/lib/icu:lib" ]

Import the ICU data library into your source files:

C++

#include "src/lib/icu_data/cpp/icu_data.h"

Rust

use icu_data::Loader;

Initialize the ICU data loader:
C++
```
const auto result = icu_data::Initialize();
ASSERT_EQ(result, ZX_OK) << "icu_data::Initialize failed";
```
Rust
```
// Load the ICU data
let _loader = Loader::new().expect("loader constructed successfully");
```
Note: At least one instance of icu_data::Loader must be kept alive for as long as your code needs ICU data. To simplify things, consider keeping a reference to the instance for the lifetime of the program.

You are now ready to use ICU data in your program.

Load from tzdata directory

To load the ICU data, initialize the loader with the path to the data directory and revision file:

C++

// Default directory for timezone .res files
constexpr char kDefaultTzdataDir[] = "/config/tzdata";
// Path to file containing the expected time zone database revision ID.
constexpr char kDefaultTzRevisionFilePath[] = "/config/tzdata/revision.txt";
ASSERT_TRUE(files::IsDirectory(kDefaultTzdataDir))
    << "Error: tzdata directory \"" << kDefaultTzdataDir << "\" doesn't exist.";

const auto result = icu_data::InitializeWithTzResourceDirAndValidate(kDefaultTzdataDir,
                                                                     kDefaultTzRevisionFilePath);
ASSERT_EQ(result, ZX_OK) << "icu_data::InitializeWithTzResourceDirAndValidate failed";

Rust

const DEFAULT_TZDATA_DIR: &str = "/config/tzdata";
const DEFAULT_TZREVISION_FILE_PATH: &str = "/config/tzdata/revision.txt";

// Load the ICU data
let _loader = Loader::new_with_tz_resources_and_validation(
    DEFAULT_TZDATA_DIR,
    DEFAULT_TZREVISION_FILE_PATH,
)
.expect("loader constructed successfully");

Appendices

Modifying the system time zone information

During development, use the ffx setui plugin to check or set the current time zone ID on a Fuchsia target. For more information about the available options, run the following commands:

ffx config set setui true // only need to run once
ffx setui intl --help