ICU timezone data

The ICU timezone data in Fuchsia is provided dynamically through the ICU data files (icudtl.dat). These are loaded on demand by programs, provided that the program's package is configured to make the file available to the program at runtime.

Section below shows how to do that.

Making the ICU data available to packages

In order for the ICU data files to be visible to a program in Fuchsia, it first needs to be made available in the package that contains the program. This is an example use from the wisdom server.

test_package("intl_wisdom_server_rust_tests") {
  deps = [
    # This target is implicitly generated by the target
    # ":intl_wisdom_server_rust" above, when it has the setting
    # "with_unit_tests=true".
    ":intl_wisdom_server_rust_test",
  ]
  tests = [
    {
      # The binary corresponding to this test has been generated implicilty by
      # the target ":intl_wisdom_server_rust" when it has the setting
      # "with_unit_tests=true".
      # This implicilty requires a file meta/intl_wisdom_server_rust_bin_test.cmx
      # to be present under this directory.
      name = "intl_wisdom_server_rust_bin_test"
      dest = "intl_wisdom_server_rust_bin_test"
      environments = basic_envs
    },
  ]

  resources = [
    {
      # Fuchsia's ICU does not have libicudata.so, and the locale data MUST
      # be loaded from a file instead.
      path = rebase_path("//third_party/icu/common/icudtl.dat")
      dest = "icudtl.dat"
    },
  ]

}

Note the section that adds a resource for icudtl.dat.

resources = [
  {
    # Fuchsia's ICU does not have libicudata.so, and the locale data MUST
    # be loaded from a file instead.
    path = rebase_path("//third_party/icu/common/icudtl.dat")
    dest = "icudtl.dat"
  },
]

Since the library's footprint can be large, we do not simply import it as a public dependency on any rust program that uses ICU.

Modifying the time zone information on a system

In development you may need to check or set the time zone ID. The program setui_client allows you to do exactly this. See more information about setui_client by running run setui_client.cmx intl --help on a target.

Using the ICU data

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

The APIs to load the code made available are different per language, so please refer to the pages below for specific examples:

Rust example

In Rust, you should use the icu_data::Loader, which will automatically do the right thing. Here is an example from the ICU data tests showing this approach.

Note that at least one instance of icu_data::Loader must be kept alive for as long as your code needs ICU data. Since it is difficult to predict when this data is needed, and the ICU liveness rules are a bit confusing, it is probably best to simplify things and keep an icu_data::Loader handy for the lifetime of the program.

#[test]
fn initialization() {
    let _loader = Loader::new().expect("loader is constructed with success");
    let _loader2 = Loader::new().expect("loader is just fine with a second initialization");
    let tz: String = uenum::open_time_zones().unwrap().take(1).map(|e| e.unwrap()).collect();
    assert_eq!(tz, "ACT");
    // The library will be cleaned up after the last of the loaders goes out of scope.
}

#[test]
fn you_can_also_clone_loaders() {
    let _loader = Loader::new().expect("loader is constructed with success");
    let _loader2 = Loader::new().expect("loader is just fine with a second initialization");
    let _loader3 = _loader2.clone();
    let tz: String = uenum::open_time_zones().unwrap().take(1).map(|e| e.unwrap()).collect();
    assert_eq!(tz, "ACT");
}

#[test]
fn two_initializations_in_a_row() {
    {
        let _loader = Loader::new().expect("loader is constructed with success");
        let tz: String =
            uenum::open_time_zones().unwrap().take(1).map(|e| e.unwrap()).collect();
        assert_eq!(tz, "ACT");
    }
    {
        let _loader2 = Loader::new().expect("loader is just fine with a second initialization");
        let tz: String =
            uenum::open_time_zones().unwrap().take(1).map(|e| e.unwrap()).collect();
        assert_eq!(tz, "ACT");
    }
}

In code, this amounts to instantiating a icu_data::Loader and keeping at least one instance of it alive for the lifetime of the program. The Loader can be cloned at will and copied around: the ICU data will be loaded before the first time it is needed, it will be unloaded when it is not needed, and will be reloaded again if needed again.

fn main() -> Result<(), Error> {
    // Force the loading of ICU data at the beginning of the program.  Since
    // Fuchsia's ICU does not have `libicudata.so`, we must load the data here
    // so that locales could be used in the server.
    let _loader = icu_data::Loader::new()?;

    let mut executor = fasync::Executor::new().context("error creating executor")?;
    let mut fs = server::ServiceFs::new_local();
    fs.dir("svc").add_fidl_service(move |stream| {
        fasync::spawn_local(async move {
            run_service(stream).await.expect("failed to run service");
        });
    });
    fs.take_and_serve_directory_handle()?;
    executor.run_singlethreaded(fs.collect::<()>());
    Ok(())
}

Perhaps a more robust approach to maintaining a live icu_data::Loader is to pass a possibly cloned instance of a Loader into whatever struct requires ICU data. This will ensure that even in face of code refactors, the code that needs live ICU data always has it available:

/// A client implementation that connects to the Wisdom server.
pub struct Client {
    // The proxy for calling into the Wisdom service.
    wisdom: fwisdom::IntlWisdomServer_Proxy,
    // Client requires the ICU data to be loaded for TZ parsing, so we keep
    // a reference to the data alive, even though we don't "use" the code.
    #[allow(dead_code)]
    icu_data_loader: icu_data::Loader,
}

See also

code