add explanatory comments to Makefiles

Makefile

@@ -25,6 +25,13 @@ all: obj $(SHLIB) $(I2PD)
 obj:
 	mkdir -p obj
 
+## NOTE: The NEEDED_CXXFLAGS are here so that CXXFLAGS can be specified at build time
+## **without** overwriting the CXXFLAGS which we need in order to build.
+## For example, when adding 'hardening flags' to the build
+## (e.g. -fstack-protector-strong -Wformat -Werror=format-security), we do not want to remove
+## -std=c++11. If you want to remove this variable please do so in a way that allows setting
+## custom FLAGS to work at build-time.
+
 # weaker rule for building files without headers
 obj/%.o : %.cpp
 	$(CXX) $(CXXFLAGS) $(NEEDED_CXXFLAGS) $(INCFLAGS) $(CPU_FLAGS) -c -o $@ $<

Makefile.bsd

@@ -1,5 +1,11 @@
 CXX = g++
 CXXFLAGS = -O2
+## NOTE: NEEDED_CXXFLAGS is here so that custom CXXFLAGS can be specified at build time
+## **without** overwriting the CXXFLAGS which we need in order to build.
+## For example, when adding 'hardening flags' to the build
+## (e.g. -fstack-protector-strong -Wformat -Werror=format-security), we do not want to remove
+## -std=c++11. If you want to remove this variable please do so in a way that allows setting
+## custom FLAGS to work at build-time.
 NEEDED_CXXFLAGS = -std=c++11
 INCFLAGS = -I/usr/include/ -I/usr/local/include/
 LDFLAGS = -Wl,-rpath,/usr/local/lib -L/usr/local/lib

Makefile.linux

@@ -1,6 +1,13 @@
 CXXFLAGS = -g -Wall -fPIC
 INCFLAGS =
 
+## NOTE: The NEEDED_CXXFLAGS are here so that custom CXXFLAGS can be specified at build time
+## **without** overwriting the CXXFLAGS which we need in order to build.
+## For example, when adding 'hardening flags' to the build
+## (e.g. -fstack-protector-strong -Wformat -Werror=format-security), we do not want to remove
+## -std=c++11. If you want to remove this variable please do so in a way that allows setting
+## custom FLAGS to work at build-time.
+
 # detect proper flag for c++11 support by gcc
 CXXVER := $(shell $(CXX) -dumpversion)
 ifeq ($(shell expr match ${CXXVER} "4\.[0-9][0-9]"),4) # >= 4.10