tz.cpp.
These sources are located at the github repository
https://github.com/HowardHinnant/date.
-The source
-tz.cpp
-contains the following string near the top:
-
-
-
-static std::string install{"~/Downloads/tzdata"}; // "%homedrive%\%homepath%\downloads\tzdata" on Windows
-
-You should set this such that install points to the directory where your
-library or application can find the downloaded and uncompressed IANA Time Zone Database -- tzdataYYYYv.tar.gz
-(or where you want the software to install it for you if you compile with
-AUTO_DOWNLOAD == 1). On Windows a utility such as
-7-zip can be used to decompress the database.
-There are three configuration macros that can be defined on the command line during
-compilation, or you can ignore them and they will take on default values.
+Compile tz.cpp
+along with your other sources while providing pointers to your compiler for the location
+of the header files (i.e. tz.h).
+
+You can also customize the build by defining macros (e.g. on the command line) as follows:
-+-
-- -- HAS_REMOTE_APIDefaults to 1 on Linux and OS X, and to 0 on Windows -- -- AUTO_DOWNLOADDefaults to -HAS_REMOTE_API- -- LAZY_INITDefaults to 1 -
INSTALL
+This is the location of your uncompressed
+IANA Time Zone Database -- tzdataYYYYv.tar.gz
+(or where you want the software to install it for you if you compile with
+AUTO_DOWNLOAD == 1).
+
+If specified, "/tzdata" will be appended to whatever you supply
+("\tzdata" on Windows).
+
+Default: "~/Downloads/tzdata"
+("%homedrive%\%homepath%\downloads\tzdata" on Windows).
+
+Example: Put the database in the current directory: +
+++-DINSTALL=. +
+Warning: When coupled with AUTO_DOWNLOAD=1, this will overwrite
+everthing at INSTALL/tzdata if it already exists. Set with care.
+
HAS_REMOTE_API
If HAS_REMOTE_API is 1 then the remote API exists,
else it doesn't:
@@ -2974,16 +2979,89 @@ bool remote_install(const std::string& version);
The remote API requires linking against libcurl
(https://curl.haxx.se/libcurl).
-On OS X and Linux this is done with -lcurl.
-libcurl comes pre-installed on OS X and Linux, but not on Windows.
+On macOS and Linux this is done with -lcurl.
+libcurl comes pre-installed on macOS and Linux, but not on Windows.
However one can download it for Windows.
+Default: 1 on Linux and macOS, 0 on Windows.
+
+Example: Disable the remote API: +
+++-DHAS_REMOTE_API=0 +
AUTO_DOWNLOAD
+If AUTO_DOWNLOAD is 1 then first access to the
+timezone database will install it if it hasn't been installed, and if it has,
+will use the remote API to install the latest version if not already installed.
+
+If AUTO_DOWNLOAD is not enabled, you are responsible for keeping your
+IANA Time Zone Database up to date. New
+versions of it are released several times a year. This library is not bundled with a
+specific version of the database already installed, nor is any specific version of the
+database blessed.
+
-If AUTO_DOWNLOAD is 1 then first access to the timezone database will install
-it if it hasn't been installed, and if it has, will use the remote API to install the
-latest version if not already installed.
+If AUTO_DOWNLOAD is 1 then HAS_REMOTE_API
+must be 1, else a compile-time error will be emitted.
+Default: Equal to HAS_REMOTE_API.
+
+Example: Disable automatic downloading of the timezone database: +
+++-DAUTO_DOWNLOAD=0 +
+Warning: This will overwrite everthing at INSTALL/tzdata if
+it already exists.
+
USE_SHELL_API
+If USE_SHELL_API is 1 then std::system is used
+to execute commands for downloading the timezone database. This may be useful (for
+example) if your tar utility is installed in some place other than
+/usr/bin/tar.
+
+If USE_SHELL_API is 0 then fork is used
+to execute commands for downloading the timezone database (CreateProcess
+on Windows).
+
+Default: 0.
+
+Example: Enable the use of the shell API: +
+++-DUSE_SHELL_API=1 +
+Example compile command I commonly use on macOS: +
+ ++clang++ -std=c++14 test.cpp -I../date ../date/tz.cpp -O3 -lcurl +
HAS_REMOTE_API and let AUTO_DOWNLOAD default to 1.
-
-To enable HAS_REMOTE_API you can either edit tz.h, adding:
-
- --#define HAS_REMOTE_API 1 -
-Or you can put /DHAS_REMOTE_API=1 on the command line. When
-HAS_REMOTE_API == 1, AUTO_DOWNLOAD defaults to 1.
-
mingw users: -lpthread is required.
-If LAZY_INIT is on, the Zones are not fully compiled upon first
-access to the database. As each Zone is accessed individaully by the
-programmer (when they are used), they are fully compiled at that point. However, this
-further Zone compilation does not involve any access to the local copy of the
-tz database files.
-
-If LAZY_INIT is off, every Zone is fully compiled upon first
-access to the database.
-
-LAZY_INIT speeds up the initialization of the database, but slows down the
-first use of any individual Zone. If you are only using a few
-Zones then LAZY_INIT is a clear win. If you are immediately
-using all of the Zones (say for some database analysis) then
-LAZY_INIT is not a win.
-
-If LAZY_INIT is off, and you are on multi-core hardware, and your application
-has other unrelated initialization it has to take care of, spinning off timezone
-initialization into a detached thread can be an attractive option:
-
-int
-main()
-{
- std::thread(date::get_tzdb).detach();
- // other initialization ...
-}
--By the time your application actually needs to use the timezone database, it is likely to -be fully initialized and ready to go. And if it is not, C++11 threadsafe function local -statics ensure there is no race condition on the initialization. -
- --If you would like to trade off functionality for size, you can reduce the size of the -database in two ways: -
- --You can limit geography by removing one or more of the files in this list: -
- -
-const std::vector<const std::string> files =
-{
- "africa", "antarctica", "asia", "australasia", "backward", "etcetera", "europe",
- "pacificnew", "northamerica", "southamerica", "systemv", "leapseconds"
-};
-
-You can limit history by setting min_year to something more recent such as:
-
- --CONSTDATA auto min_year = 2015_y; -
-When you do so, if you ask to convert a date prior to min_year, an exception
-will be thrown.
-
-The entire database consumes about 859Kb. -
- -
-Compile
-tz.cpp
-in with the rest of your library or application.
-
-If AUTO_DOWNLOAD is not enabled, you are responsible for keeping your
-IANA Time Zone Database up to date. New
-versions of it are released several times a year. This library is not bundled with a
-specific version of the database already installed, nor is any specific version of the
-database blessed.
-
-There is no preprocessing of the -IANA Time Zone Database required. This -library efficiently initializes itself directly from the files of the -IANA Time Zone Database. -
-