Merge pull request #81 from bxparks/develop

merge v1.8.1 into master

Author: bxparks

.github/workflows/aunit_tests.yml

@@ -26,6 +26,7 @@ jobs:
     - name: Verify examples
       run: |
         make -C examples
+        make -C examples/MemoryBenchmark epoxy
 
     - name: Verify tests
       run: |

CHANGELOG.md

@@ -1,6 +1,9 @@
 # Changelog
 
 * Unreleased
+* 1.8.1 (2021-10-18, TZDB 2021d)
+    * Add `make -C examples/MemoryBenchmark epoxy` to GitHub actions.
+    * Upgrade to TZDB 2021d.
 * 1.8.0 (2021-10-15, TZDB 2021c)
     * **Breaking Change**: Move clock classes under `ace_time::clock` and
       implementation classes under `ace_time::hw` to the new

DEVELOPER.md

@@ -565,31 +565,52 @@ available.
         * `$ make clean`
         * `$ make`
         * `$ ./BasicHinnantDateTest.out | grep failed`
-        * There should be no failures: `TestRunner summary: 268 passed, 0
-          failed, 0 skipped, 0 timed out, out of 268 test(s).`
+        * There should be no failures.
     * ExtendedHinnantDateTest
         * `$ cd .../AceTimeValidation/ExtendedHinnantDateTest`
         * Update the `TZ_VERSION` variable in the `Makefile` with the commit tag
           of the new TZDB version. (e.g. `TZ_VERSION = 2020c`).
         * `$ make clean`
         * `$ make`
         * `$ ./ExtendedHinnantDateTest.out | grep failed`
-        * There should be no failures: `TestRunner summary: 387 passed, 0
-          failed, 0 skipped, 0 timed out, out of 387 test(s).`
-* Update the various zone info files:
-    * `src/ace_time/zonedb`
+        * There should be no failures.
+* Verify that the `AceTime` library and the `AceTimePython` library agree with
+  each other using the same TZDB version. This requires going into the
+  [AceTimeValidation](https://github.com/bxparks/AceTimeValidation) project.
+    * BasicAcetzTest
+        * `$ cd .../AceTimeValidation/BasicAcetzTest`
+        * Update the `TZ_VERSION` variable in the `Makefile` with the commit tag
+          of the new TZDB version. (e.g. `TZ_VERSION = 2020c`).
+        * `$ make clean`
+        * `$ make`
+        * `$ ./BasicAcetzTest.out | grep failed`
+        * There should be no failures.
+    * ExtendedAcetzTest
+        * `$ cd .../AceTimeValidation/ExtendedAcetzTest`
+        * Update the `TZ_VERSION` variable in the `Makefile` with the commit tag
+          of the new TZDB version. (e.g. `TZ_VERSION = 2020c`).
+        * `$ make clean`
+        * `$ make`
+        * `$ ./ExtendedAcetzTest.out | grep failed`
+        * There should be no failures.
+* Update the various zoneinfo files for AceTime:
+    * `zonedb`
         * `$ cd src/ace_time/zonedb`
         * Edit the `Makefile` and update the `TZ_VERSION`.
         * `$ make`
-    * `src/ace_time/zonedbx`
+    * `zonedbx`
         * `$ cd src/ace_time/zonedbx`
         * Edit the `Makefile` and update the `TZ_VERSION`.
         * `$ make`
-    * `AceTimeTools/zonedbpy`
-        * `$ cd AceTimeTools/zonedbpy`
+* Update the zoneinfo files for AceTimePython:
+    * ``zonedbpy`
+        * `$ cd AceTimePython/src/acetime/zonedbpy`
         * Edit the `Makefile` and update the `TZ_VERSION`.
         * `$ make`
-* Update the CHANGELOG.md.
+* Update CHANGELOGs
+    * AceTime/CHANGELOG.md
+    * AceTimePython/CHANGELOG.md
+    * AceTimeValidation/CHANGELOG.md
 * Commit the changes to git
     * `$ git add ...`
     * `$ git commit -m "..."`
@@ -628,7 +649,7 @@ tests will fail until the underlying timezone database of the OS is updated.
     * Go to https://github.com/bxparks/AceTime.
     * Create a Pull Request from `develop` to `master`.
     * Approve and merge the PR.
-* Create a new Release.
+* Create a new Release of AceTime.
     * Go to https://github.com/bxparks/AceTime
     * Click on "Releases"
     * Click on "Draft a new release"
@@ -637,9 +658,19 @@ tests will fail until the underlying timezone database of the OS is updated.
     * Enter the release notes. I normally just copy and paste the latest changes
       from `CHANGELOG.md`.
     * Click Publish release.
+* Create a new Release of AceTimePython.
+    * Go to https://github.com/bxparks/AceTimePython
+    * Click on "Releases"
+    * Click on "Draft a new release"
+    * Enter a tag version (e.g. `v1.2`), targeting the `master` branch.
+    * Enter the release title.
+    * Enter the release notes. I normally just copy and paste the latest changes
+      from `CHANGELOG.md`.
+    * Click Publish release.
 * Add corresponding tags on AceTimeTools and AceTimeValidation for reference.
-    * Go to https://github.com/bxparks/AceTimeTools
-    * `$ git tag -a 'atX.Y.Z' -m 'AceTime vX.Y.Z'`
-    * `$ git push --tags`
-    * Go to https://github.com/bxparks/AceTimeValidation
-    * (Same as above)
+    * AceTimePython
+        * `$ git tag -a 'atX.Y.Z' -m 'AceTime vX.Y.Z'`
+        * `$ git push --tags`
+    * AceTimeValidation
+        * `$ git tag -a 'atX.Y.Z' -m 'AceTime vX.Y.Z'`
+        * `$ git push --tags`

MIGRATING.md

@@ -88,8 +88,8 @@ libraries](https://github.com/Testato/SoftwareWire/wiki/Arduino-I2C-libraries).
 The `<AceWire.h>` library solves this problem by using compile-time polymorphism
 through C++ templates.
 
-Here is the migration process. For all occurrences of the `DS3231Clock` class
-like this:
+Here is the migration process. For all occurrences of the old `DS3231Clock`
+class that look like this:
 
 ```C++
 #include <AceTimeClock.h>
@@ -99,7 +99,8 @@ using namespace ace_time::clock;
 DS3231Clock dsClock;
 ```
 
-Replace that with a template instance of the `DS3231Clock<T>` class:
+Replace that with a template instance of the `DS3231Clock<T>` class, and its I2C
+interface classes (`TwoWire` and `TwoWireInterface`):
 
 ```C++
 #include <AceTimeClock.h>
@@ -111,24 +112,42 @@ using namespace ace_time::clock;
 using WireInterface = ace_wire::TwoWireInterface<TwoWire>;
 WireInterface wireInterface(Wire);
 DS3231Clock<WireInterface> dsClock(wireInterface);
+
+void setup() {
+  ...
+  Wire.begin();
+  wireInterface.begin();
+  dsClock.setup();
+  ...
+}
 ```
 
-The new version requires more configuration. But in return, we gain more
-flexibility and potentially a large reduction of flash memory consumption. Here
-is another example where the `SimpleWireInterface` class is swapped in place of
-the `TwoWireInterface` class, without any changes to the `DS3231Clock` class:
+The new `DS3231Clock<T>` class requires more configuration. But in return, we
+gain more flexibility and potentially a large reduction of flash memory
+consumption if the pre-installed `<Wire.h>` is replaced with a different I2C
+implementation.  For example, here is a version of the `DS3231Clock` object
+where the `SimpleWireInterface` software I2C class replaces the hardware
+`TwoWireInterface` class, without any changes to the `DS3231Clock` class:
 
 ```C++
 #include <AceTimeClock.h>
 #include <AceWire.h>
 using namespace ace_time;
+using namespace ace_time::clock;
 
 const uint8_t SCL_PIN = SCL;
 const uint8_t SDA_PIN = SDA;
 const uint8_t DELAY_MICROS = 4;
 using WireInterface = ace_wire::SimpleWireInterface;
 WireInterface wireInterface(SDA_PIN, SCL_PIN, DELAY_MICROS);
 DS3231Clock<WireInterface> dsClock(wireInterface);
+
+void setup() {
+  ...
+  wireInterface.begin();
+  dsClock.setup();
+  ...
+}
 ```
 
 According to the benchmarks at

README.md

@@ -41,7 +41,7 @@ This library can be an alternative to the Arduino Time
 (https://github.com/PaulStoffregen/Time) and Arduino Timezone
 (https://github.com/JChristensen/Timezone) libraries.
 
-**Version**: 1.8.0 (2021-10-15, TZDB version 2021c)
+**Version**: 1.8.1 (2021-10-18, TZDB version 2021d)
 
 **Changelog**: [CHANGELOG.md](CHANGELOG.md)
 
@@ -87,17 +87,14 @@ This library can be an alternative to the Arduino Time
 
 The latest stable release is available in the Arduino Library Manager in the
 IDE. Search for "AceTime". Click install. The Library Manager should
-automatically install the dependent library:
-
-* AceCommon (https://github.com/bxparks/AceCommon)
-
-The development version can be installed by cloning the 2 git repos:
+automatically install AceTime and its the dependent library:
 
 * AceTime (https://github.com/bxparks/AceTime)
 * AceCommon (https://github.com/bxparks/AceCommon)
 
+The development version can be installed by cloning the above repos manually.
 You can copy over the contents to the `./libraries` directory used by the
-Arduino IDE. (The result is directories named `./libraries/AceTime` and
+Arduino IDE. (The result is a set of directories named `./libraries/AceTime` and
 `./libraries/AceCommon`). Or you can create symlinks from `./libraries` to these
 directories. Or you can `git clone` directly into the `./libraries` directory.
 

USER_GUIDE.md

@@ -4,7 +4,7 @@ The primary purpose of AceTime classes is to convert between an integer
 representing the number of seconds since Epoch (2000-01-01T00:00:00 UTC) to
 human-readable components in different timezones.
 
-**Version**: 1.8.0 (2021-10-15, TZDB 2021c)
+**Version**: 1.8.1 (2021-10-18, TZDB 2021d)
 
 **Related Documents**:
 

library.properties

@@ -1,5 +1,5 @@
 name=AceTime
-version=1.8.0
+version=1.8.1
 author=Brian T. Park <[email protected]>
 maintainer=Brian T. Park <[email protected]>
 sentence=Date, time, timezone classes for Arduino supporting the full IANA TZ Database to convert epoch seconds to date and time components in different time zones.

src/AceTime.h

@@ -67,7 +67,7 @@
 #include "ace_time/time_period_mutation.h"
 
 // Version format: xxyyzz == "xx.yy.zz"
-#define ACE_TIME_VERSION 10800
-#define ACE_TIME_VERSION_STRING "1.8.0"
+#define ACE_TIME_VERSION 10801
+#define ACE_TIME_VERSION_STRING "1.8.1"
 
 #endif

src/ace_time/zonedb/Makefile

@@ -2,7 +2,7 @@ TARGETS := zone_infos.cpp zone_infos.h zone_policies.cpp zone_policies.h
 
 TOOLS := $(abspath ../../../../AceTimeTools)
 
-TZ_VERSION := 2021c
+TZ_VERSION := 2021d
 START_YEAR := 2000
 UNTIL_YEAR := 2050
 

src/ace_time/zonedb/zone_infos.cpp

@@ -3,7 +3,7 @@
 //   $ /home/brian/src/AceTimeTools/src/acetimetools/tzcompiler.py
 //     --input_dir /home/brian/dev/tz
 //     --output_dir /home/brian/src/AceTime/src/ace_time/zonedb
-//     --tz_version 2021c
+//     --tz_version 2021d
 //     --action zonedb
 //     --language arduino
 //     --scope basic
@@ -22,7 +22,7 @@
 //   northamerica
 //   southamerica
 //
-// from https://github.com/eggert/tz/releases/tag/2021c
+// from https://github.com/eggert/tz/releases/tag/2021d
 //
 // Zones: 258
 // Links: 193
@@ -52,7 +52,7 @@ namespace zonedb {
 // ZoneContext (should not be in PROGMEM)
 //---------------------------------------------------------------------------
 
-const char kTzDatabaseVersion[] = "2021c";
+const char kTzDatabaseVersion[] = "2021d";
 
 const char* const kFragments[] = {
 /*\x00*/ nullptr,