Merge pull request #30 from bxparks/develop

merge 0.7.0 into master

.github/workflows/aunit_tests.yml

@@ -22,15 +22,9 @@ jobs:
     - name: Verify examples
       run: |
         make -C examples
-        make -C libraries/EpoxyFS/examples
-        make -C libraries/EpoxyPromEsp/examples
-        make -C libraries/EpoxyPromAvr/examples
+        make -C libraries
 
     - name: Verify tests
       run: |
-        make -C libraries/EpoxyFS/tests
-        make -C libraries/EpoxyFS/tests runtests
-        make -C libraries/EpoxyPromEsp/tests
-        make -C libraries/EpoxyPromEsp/tests runtests
-        make -C libraries/EpoxyPromAvr/tests
-        make -C libraries/EpoxyPromAvr/tests runtests
+        make -C libraries tests
+        make -C libraries runtests

.gitignore

@@ -35,4 +35,4 @@
 epoxyfsdata
 
 # Root file of EpoxyPromAvr and EpoxyPromEsp
-epoxypromdata
+epoxyeepromdata

CHANGELOG.md

@@ -1,6 +1,21 @@
 # Changelog
 
 * Unreleased
+* 0.7 (2021-04-28)
+    * Add `libraries/EpoxyMockDigitalWriteFast`, a simple mock library for
+      `digitalWriteFast` (https://github.com/NicksonYap/digitalWriteFast) to
+      allow code using these functions (e.g. `digitalWriteFast()`) to compile
+      under EpoxyDuino.
+    * Rename `EpoxyPromAvr` to `EpoxyEepromAvr`, and `EpoxyPromEsp` to
+      `EpoxyEepromEsp`, for consistency and better self-description.
+    * Add `EPOXY_CORE` and `EPOXY_CORE_PATH` variables to allow alternate
+      Arduino Core files to be specified. Move current Core files from top-level
+      into `./cores/epoxy/` subdirectory.
+    * Add `memcpy_P()` and `vsnprintf_P()` (Thanks pmp-p@, #28).
+    * Add `EXTRA_CXXFLAGS` to allow additional c++ flags to be specified.
+    * Add `-Wextra` (in addition to `-Wall`) because some Arduino platforms
+      enable both when "warnings" are enabled, so it's convenient to catch those
+      warnings on the desktop when using EpoxyDuino.
 * 0.6.2 (2021-03-15)
     * Add more stubs for Arduino API functions: `pulseIn()`, `pulseInLong()`,
       `shiftOut()`, `shiftIn()`, I2C and SPI pins (SS, MOSI, MISO, SCK, SDA,

EpoxyDuino.mk

@@ -19,16 +19,19 @@
 # Optional parameters are:
 #
 #	* ARDUINO_LIB_DIRS: List of additional locations of Arduino libs, for
-#	  example, $(ARDUINO_IDE_DIR)/libraries,
-#	  $(ARDUINO_IDE_DIR)/hardware/arduino/avr/libraries,
-#	  $(ARDUINO_IDE_DIR)/portable/packages/arduino/hardware/avr/1.8.2/libraries.
-#	  (The $(ARDUINO_IDE_DIR) is an example temporary variable containing the
+#	  example, $(arduino_ide_dir)/libraries,
+#	  $(arduino_ide_dir)/hardware/arduino/avr/libraries,
+#	  $(arduino_ide_dir)/portable/packages/arduino/hardware/avr/1.8.2/libraries.
+#	  (The $(arduino_ide_dir) is an example temporary variable containing the
 #	  install location of the Arduino IDE. It is not used by EpoxyDuino.mk.)
 #   * OBJS: Additional object (*.o) files needed by the binary
 #   * GENERATED: A list of files which are generated by a script, and therefore
 #     can be deleted by 'make clean'
 #	* MORE_CLEAN: Optional user-supplied make-target that performs
-#	  additional cleanup (i.e. removing generated directories).
+#	  additional cleanup (i.e. removing generated files or directories).
+#	* EPOXY_CORE: Select an alternate Arduino Core. Default 'epoxy'.
+#	* EPOXY_CORE_PATH: Select the alternate Core given by this full path.
+#	  Default: $(EPOXY_DUINO_DIR)/cores/$(EPOXY_CORE).
 #
 # Type 'make -n' to verify.
 #
@@ -44,72 +47,137 @@ EPOXY_DUINO_DIR := $(abspath $(dir $(lastword $(MAKEFILE_LIST))))
 # Look for libraries under ./EpoxyDuino/libraries/
 EPOXY_DUINO_LIB_DIR := $(abspath $(EPOXY_DUINO_DIR)/libraries)
 # Look for libraries which are siblings to ./EpoxyDuino/
-EPOXY_DUINO_SIBLING_DIR := $(abspath $(EPOXY_DUINO_DIR)/..)
+EPOXY_DUINO_PARENT_DIR := $(abspath $(EPOXY_DUINO_DIR)/..)
 
 # List of Arduino IDE library folders, both built-in to the Arduino IDE
 # and those downloaded later, e.g. in the portable/ directory or .arduino15/
 # directory.
 ARDUINO_LIB_DIRS ?=
 
-# Default modules which are automatically linked in: EpoxyDuino/
-DEFAULT_MODULES := $(EPOXY_DUINO_DIR)
-
-# Look for libraries under EPOXY_DUINO_LIB_DIR, EPOXY_DUINO_SIBLING_DIR, and
-# each of the directories listed in ARDUINO_LIB_DIRS.
-APP_MODULES := $(foreach lib,$(ARDUINO_LIBS),${EPOXY_DUINO_LIB_DIR}/${lib})
-APP_MODULES += $(foreach lib,$(ARDUINO_LIBS),${EPOXY_DUINO_SIBLING_DIR}/${lib})
-APP_MODULES += \
+# Define the module that contains <Arduino.h> and other core API files. By
+# default, the "epoxy" core is used which is based on the AVR core, with some
+# extensions. The <Arduion.h> file lives in $(EPOXY_DUINO_DIR/cores/epoxy.
+#
+# Currently, only "epoxy" Core has been implemented. If additional predefined
+# cores become supported in EpoxyDuino in $(EPOXY_DUINO_DIR)/cores/, then
+# end-user can override EPOXY_CORE with another predefined core. For example,
+# if I decide to implement a version of the Core that tries to emulate the
+# ESP8266 and create the implementation files under
+# $(EPOXY_DUINO_DIR)/cores/esp8266, then this variable could be set to
+# "esp8266".
+EPOXY_CORE ?= epoxy
+
+# This variable provides a big hammer that can override the Arduino Core
+# supplied by EpoxyDuino with an externally provided Core that compatible with
+# EpoxyDuino (e.g. EPOXY_CORE_PATH =
+# $(EPOXY_DUINO_DIR)/../EspMock/cores/esp8266).
+EPOXY_CORE_PATH ?= $(EPOXY_DUINO_DIR)/cores/$(EPOXY_CORE)
+
+# Find the directory paths of the libraries listed in ARDUINO_LIBS by looking
+# under directory given by EPOXY_DUINO_LIB_DIR, the directory given by
+# EPOXY_DUINO_PARENT_DIR to look for siblings, and each directory listed in
+# ARDUINO_LIB_DIRS.
+EPOXY_MODULES := $(foreach lib,$(ARDUINO_LIBS),${EPOXY_DUINO_LIB_DIR}/${lib})
+EPOXY_MODULES += $(foreach lib,$(ARDUINO_LIBS),${EPOXY_DUINO_PARENT_DIR}/${lib})
+EPOXY_MODULES += \
 	$(foreach lib_dir,$(ARDUINO_LIB_DIRS),\
 		$(foreach lib,$(ARDUINO_LIBS),\
 			${lib_dir}/${lib}\
 		)\
 	)
 
-# All dependent modules.
-ALL_MODULES := $(DEFAULT_MODULES) $(APP_MODULES)
-
-# Compiler and settings
+# Compiler settings that depend on the OS (Linux, MacOS, FreeBSD). I'm not 100%
+# sure that these flags are correct, but they seem to work. Previously, I was
+# using just -Wall to catch the warnings, but some Arduino compilers seem to
+# enable -Wextra when "enable warnings" is enabled. So let's add -Wextra in
+# EpoxyDuino to help catch warnings on desktop machines as well.
+#
+# The difference between -stdlib=libstdc++ and -stdlib=libc++ seems to be that
+# libstdc++ was created by the GNU team and libc++ was created by the LLVM
+# team. Apple no longer distributes the latest version of the libstdc++, so we
+# are forced to use libc++ on Macs.
+#
+# The Linux g++ flags came from looking at the verbose compiler output of the
+# Arduino IDE. The g++ compiler automatically uses -stdlib=libstdc++. I copied
+# the -fno-exceptions, -fno-threadsafe-statics, and -flto flags from the
+# Arduino compiler output. But I'm not entirely sure that those flags are
+# actually doing the right without linking to a version of the libstdc++ that
+# was also compiled with the same flag. I don't know, things seem to work for
+# now.
+#
+# The Mac clang++ flags came from... I can't remember. Some trial and error,
+# and maybe this StackOverflow https://stackoverflow.com/questions/19774778).
+# It looks like the clang++ compiler supports the -std=gnu++11 flag, but I
+# suspect that it requires using the latest libstdc++ library, which isn't
+# available on Macs. So I'll be conservative and use just -std=c++11.
+#
+# The FreeBSD clang++ flags came from copying the Mac version, since it seems
+# like c++ on FreeBSD is actualy clang++. It's possible that FreeBSD has the
+# latest GNU version of libstdc++, but I'm not sure.
+#
+# I added EXTRA_CXXFLAGS to allow end-user Makefiles to specify additional
+# CXXFLAGs.
 ifeq ($(UNAME), Linux)
 CXX ?= g++
-CXXFLAGS ?= -Wall -std=gnu++11 -fno-exceptions -fno-threadsafe-statics -flto
+CXXFLAGS ?= -Wextra -Wall -std=gnu++11 -fno-exceptions -fno-threadsafe-statics -flto
 else ifeq ($(UNAME), Darwin)
 CXX ?= clang++
-CXXFLAGS ?= -std=c++11 -stdlib=libc++ # -Weverything
+CXXFLAGS ?= -Wextra -Wall -std=c++11 -stdlib=libc++
+else ifeq ($(UNAME), FreeBSD)
+CXX ?= clang++
+CXXFLAGS ?= -Wextra -Wall -std=c++11 -stdlib=libc++
 endif
+CXXFLAGS += $(EXTRA_CXXFLAGS)
 
-# pre-processor (-I, -D, etc)
-CPPFLAGS_EXPANSION = -I$(module) -I$(module)/src
+# Pre-processor flags (-I, -D, etc), mostly for header files.
 CPPFLAGS ?=
-CPPFLAGS += $(foreach module,$(ALL_MODULES),$(CPPFLAGS_EXPANSION))
-
 # Define a macro to indicate that EpoxyDuino is being used. Defined here
 # instead of Arduino.h so that files like 'compat.h' can determine the
 # compile-time environment without having to include <Arduino.h>.
 # Also define UNIX_HOST_DUINO for backwards compatibility.
-CPPFLAGS += -DUNIX_HOST_DUINO -DEPOXY_DUINO
+CPPFLAGS += -D UNIX_HOST_DUINO -D EPOXY_DUINO
+# Add the header files for the Core files.
+CPPFLAGS += -I$(EPOXY_CORE_PATH)
+# Add the header files for libraries. Old Arduino libraries place the header
+# and source files right at the top. New Arduino libraries tend to use the
+# ./src/ subdirectory. We need to support both.
+CPPFLAGS_EXPANSION = -I$(module) -I$(module)/src
+CPPFLAGS += $(foreach module,$(EPOXY_MODULES),$(CPPFLAGS_EXPANSION))
 
-# linker settings (e.g. -lm)
+# Linker settings (e.g. -lm).
 LDFLAGS ?=
 
-# C++ srcs. Old Arduino libraries place the source files at the top level.
-# Later Arduino libraries put the source files under the src/ directory.
-# Support subdirectory expansions up to 3 levels below 'src/'.
-# (There might be a better way to do this using GNU Make but I can't find a
-# mechanism that doesn't barf when the 'src/' directory doesn't exist.)
-SRCS_EXPANSION = $(wildcard $(module)/*.cpp) \
+# Generate list of C++ srcs to compile.
+#
+# 1) Add the source files in the Core directory. Support subdirectory
+# expansions up to 3 levels below the given target. (There might be a better
+# way to do this using GNU Make but I can't find a mechanism that doesn't barf
+# when the 'src/' directory doesn't exist.)
+EPOXY_SRCS := $(wildcard $(EPOXY_CORE_PATH)/*.cpp) \
+	$(wildcard $(EPOXY_CORE_PATH)/*/*.cpp) \
+	$(wildcard $(EPOXY_CORE_PATH)/*/*/*.cpp) \
+	$(wildcard $(EPOXY_CORE_PATH)/*/*/*/*.cpp)
+# 2) Add the source files of the libraries. Old Arduino libraries place the
+# source files at the top level. Later Arduino libraries put the source files
+# under the src/ directory. Also support 3 levels of subdirectories.
+MODULE_EXPANSION = $(wildcard $(module)/*.cpp) \
 	$(wildcard $(module)/src/*.cpp) \
 	$(wildcard $(module)/src/*/*.cpp) \
 	$(wildcard $(module)/src/*/*/*.cpp) \
 	$(wildcard $(module)/src/*/*/*/*.cpp)
-SRCS := $(foreach module,$(ALL_MODULES),$(SRCS_EXPANSION))
-SRCS := ${SRCS} $(wildcard *.cpp) $(wildcard */*.cpp)
+EPOXY_SRCS += $(foreach module,$(EPOXY_MODULES),$(MODULE_EXPANSION))
+# 3) Add the source files in the application directory, also 3 levels down.
+EPOXY_SRCS += $(wildcard *.cpp) $(wildcard */*.cpp) $(wildcard */*/*.cpp) \
+	$(wildcard */*/*/*.cpp)
 
 # Objects including *.o from *.ino
-OBJS += $(SRCS:%.cpp=%.o) $(APP_NAME).o
+OBJS += $(EPOXY_SRCS:%.cpp=%.o) $(APP_NAME).o
 
+# Finally, the rule to generate the binary for the application.
 $(APP_NAME).out: $(OBJS)
 	$(CXX) $(CPPFLAGS) $(CXXFLAGS) -o $@ $^ $(LDFLAGS)
 
+# We need to add a rule to treat .ino file as just a  normal .cpp.
 $(APP_NAME).o: $(APP_NAME).ino
 	$(CXX) $(CPPFLAGS) $(CXXFLAGS) -x c++ -c $<