README.md
1This directory contains Android's additions to timezone-boundary-builder
2project.
3
4Directories:
5
6`android_inputs/`
7 - Files downloaded from upstream to seed `android_downloads/`
8
9`android_downloads/`
10 - The .json files used to generate the output. Equivalent to upstream's
11 `downloads/` directory.
12
13`android_dist/`
14 - The generated output files. Equivalent to upstream's `dist/` directory.
15
16`tools/`
17 - Scripts used to execute the timezone-boundary-builder generation process.
18
19Android initially intends to use the time zone boundary file, `combined.json`,
20released by upstream. Therefore, this copy of timezone-boundary-builder may be
21unnecessary until / unless Android wants to make local modifications.
22
23-----
24
25The `combined.json` generation process:
26
27Execute `android/tools/host/clear_android_data_files.sh` to clear out most
28working files and reset the local environment.
29
30Before running the generation process, decide if you want to use the same input
31files as have been used by upstream.
32
33Upstream make the files used available in a file called `input-files.zip`, which
34can be downloaded and unpacked into the `android/android_downloads/` directory
35using `android/tools/host/download_input_files.sh`.
36
37When not using upstream's input files, the generation process will first
38download boundary data from OpenStreetMap, which is slow. Because OpenStreetMap
39is constantly evolving, the latest features downloaded will usually have issues
40that need to be fixed before proceeding. The script can be restarted multiple
41times and will usually restart downloads from where it failed last time.
42
43Local edits to input files may be necessary to make adjustments needed for
44Android in future.
45
46timezone-boundary-builder requires the nodejs runtime for execution with various
47dependencies, so Android's `android/tools/host/run_tzbb.sh` uses a Docker
48container to setup the runtime environment in a repeatable manner.
49
50Execute `android/tools/host/run_tzbb.sh --help` to see options.
51
52The following can be used to speed up generation times:
53
54```
55 --skip_analyze_diffs Skip analysis of diffs between versions [boolean]
56 --skip_shapefile Skip shapefile creation [boolean]
57 --skip_validation Skip validation [boolean]
58```
59
60After executing `android/tools/host/run_tzdbb.sh`, in `android/android_dist/`
61there will be many .json files alongside (a newly generated) `input-files.zip`
62and `combined.json` that constitute the main output files.
63
64The contents of `android/android_downloads/` and `android/android_dist/` can be
65committed to form a full record of how the latest output file was generated.
66
67The `combined.json` and `input-files.zip` can be passed to the new step of the
68reference data generation pipeline, which is held in a separate git project.
69
70