From bddd8be2aa331e0ae853bb7451532d31feea255e Mon Sep 17 00:00:00 2001 From: Howard Hinnant Date: Sat, 6 Aug 2016 14:58:16 -0400 Subject: [PATCH] Document INSTALL, and reorganize Installation instructions. --- tz.html | 271 ++++++++++++++++++++++++-------------------------------- 1 file changed, 116 insertions(+), 155 deletions(-) diff --git a/tz.html b/tz.html index 5a71b34..dabf9cc 100644 --- a/tz.html +++ b/tz.html @@ -2920,46 +2920,51 @@ You will need the following four source files: 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
+

Windows specific:

@@ -3002,127 +3080,10 @@ http://unicode.org/repos/cldr/trunk/common/supplemental/windowsZones.xml int 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.

-

Optional installation tweaks

- -

-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. -

-

Acknowledgements