| # 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](icu.md) |
| |
| |
| ## 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: |
| |
| ```gn |
| {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/intl/tz_version_parrot/rust/BUILD.gn" region_tag="icudata_resource" adjust_indentation="auto" %} |
| ``` |
| |
| ### Timezone configuration data |
| |
| To provide a specific version of the timezone data files to your component, |
| request the appropriate [directory capability][directory-capability] |
| in your component manifest: |
| |
| ```json5 |
| {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/intl/tz_version_parrot/rust/meta/tz_version_parrot.cml" region_tag="tzdata-capability" adjust_indentation="auto" %} |
| ``` |
| |
| ## 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. |
| |
| 1. Include the ICU data library dependency in your `BUILD.gn` file: |
| |
| * {C++} |
| |
| ```gn |
| {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/intl/tz_version_parrot/cpp/BUILD.gn" region_tag="icudata_library" adjust_indentation="auto" %} |
| ``` |
| |
| Note: You can find the C++ library source at |
| [`//src/lib/icu_data/cpp`](/src/lib/icu_data/cpp) |
| |
| * {Rust} |
| |
| ```gn |
| {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/intl/tz_version_parrot/rust/BUILD.gn" region_tag="icudata_library" adjust_indentation="auto" %} |
| ``` |
| |
| Note: You can find the Rust library source at |
| [`//src/lib/icu_data/rust`](/src/lib/icu_data/rust) |
| |
| 1. Import the ICU data library into your source files: |
| |
| * {C++} |
| |
| ```cpp |
| {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/intl/tz_version_parrot/cpp/test.cc" region_tag="imports" adjust_indentation="auto" %} |
| ``` |
| |
| * {Rust} |
| |
| ```rust |
| {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/intl/tz_version_parrot/rust/src/lib.rs" region_tag="imports" adjust_indentation="auto" %} |
| ``` |
| |
| 1. Initialize the ICU data loader: |
| |
| * {C++} |
| |
| ```cpp |
| {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/intl/tz_version_parrot/cpp/test.cc" region_tag="loader_example" adjust_indentation="auto" %} |
| ``` |
| |
| * {Rust} |
| |
| ```rust |
| {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/intl/tz_version_parrot/rust/src/lib.rs" region_tag="loader_example" adjust_indentation="auto" %} |
| ``` |
| |
| 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++} |
| |
| ```cpp |
| {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/intl/tz_version_parrot/cpp/test.cc" region_tag="loader_config_example" adjust_indentation="auto" %} |
| ``` |
| |
| * {Rust} |
| |
| ```rust |
| {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/intl/tz_version_parrot/rust/src/lib.rs" region_tag="loader_config_example" adjust_indentation="auto" %} |
| ``` |
| |
| ## 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: |
| |
| ```posix-terminal |
| ffx config set setui true // only need to run once |
| ffx setui intl --help |
| ``` |
| |
| <!-- xrefs --> |
| [product-config]: /docs/development/components/configuration/config_data.md |
| [directory-capability]: /docs/concepts/components/v2/capabilities/directory.md |