Feature - Setting the binary tzdb directory path at runtime

[DavisVaughan]

Closes #626
A step towards #564

This PR allows for setting the time zone database directory path at runtime. It does so through a new helper, set_tz_dir(), which must be called before the tzdb is initialized if the user has declared that they are going to manually set the path at runtime.

Because the binary tzdb parser does not yet work on Windows, this PR does not enable the runtime setting of the path on Windows. That said, the eventual goal to resolve #564 is to fix the binary tzdb parser on Windows, and then to enable runtime setting of the directory path there. That should bring really nice performance improvements to Windows.

There is a new option, USE_BINARY_TZDB. USE_OS_TZDB can be thought of as a subset of this. If USE_BINARY_TZDB is turned on, but USE_OS_TZDB is not, then the client is required to call set_tz_dir() before initializing the tzdb, otherwise a runtime error is thrown. If USE_OS_TZDB is on, then the automatic detection of the OS tzdb is done instead, and set_tz_dir() is not exposed.

If USE_BINARY_TZDB is not defined, then it is set to USE_OS_TZDB to be compatible with all previous versions of date.

---

There are two additional changes that I felt had to be made to merge this PR.

Previously, discover_tz_dir() and get_tz_dir() were always defined if on a non-Windows platform, even if USE_OS_TZDB was not defined. I considered this a bug. discover_tz_dir() is now only defined when USE_OS_TZDB is on (otherwise you don't need to discover it), and get_tz_dir() is defined if either USE_OS_TZDB or USE_BINARY_TZDB is defined. It is required for get_tz_dir() to be implemented this way to eventually add support for USE_BINARY_TZDB on Windows (i.e. we can't just turn off support for it when on Windows, as is currently done).

I have changed the non-Windows implementation of current_zone() to only call get_tz_dir() when USE_OS_TZDB is on. This is a direct result of the previously mentioned change. It seems like current_zone() only calls get_tz_dir() in embedded systems and is related to a symlink to an OS tzdb path, so it really feels like USE_OS_TZDB should have to be active for this to work properly anyways. It would not be sufficient for USE_BINARY_TZDB to be on, but USE_OS_TZDB to be off, because this could be a custom location that the symlink probably won't point to.

---

To make sure this is working, I turned it on over in the project I am working on. It seems to work nicely for me on my Mac r-lib/clock#49

I'm not very familiar with C++ testing, so feel free to make changes against this PR as you see fit if you'd like to accept it.

[pitrou]

@DavisVaughan Can you explain what you mean with "the binary tzdb parser does not yet work on Windows"?

[DavisVaughan]

On Windows only the text version of the tzdb is allowed. On non-Windows you can choose to either use the text tzdb or the binary tzdb, and there are parsers for both, with the binary one typically being much faster.

But the binary parser hasn't been extended to support Windows yet, i.e.:
#564 (comment)

No one has yet modified tz.cpp to read the binary form of the tzdb on a Windows system, though that certainly seems doable

[pitrou]

I see, so I am right in interpreting that on Windows, one can use set_install to point to an existing location of the text form of the IANA database?

But the binary parser hasn't been extended to support Windows yet

Does it mean that it is known not to work, or just it hasn't been made available?

[HowardHinnant]

Hasn't been made available.

Also in the mix: The latest VS tools implement this library as part of C++20: https://gcc.godbolt.org/z/da3YKeKa8 This includes the IANA database.

[DavisVaughan]

I see, so I am right in interpreting that on Windows, one can use set_install to point to an existing location of the text form of the IANA database?

Right, and that is what I do here, which ends up pointing at a text version of the tzdb that I ship with this R package
https://github.com/r-lib/tzdb/blob/acb04d177fc7344ad09b2c275b950264fea6c194/src/path.cpp#L21

With these compilation flags set:
https://github.com/r-lib/tzdb/blob/main/src/Makevars.win