better respect GNU standard Makefile conventions

supports lowercase directory variables
add an "Installation" section in README.md
added an INSTALL file

6 files changed, 102 insertions, 63 deletions

diff --git a/INSTALL b/INSTALL
new file mode 100644
index 0000000..8f61221
--- /dev/null
+++ b/INSTALL
@@ -0,0 +1,13 @@
+Installation
+=============
+
+`make`
+`make install`     # this command may require root access
+
+LZ4's `Makefile` supports standard [Makefile conventions],
+including [staged installs], [directory redirection], or [command redefinition].
+
+[Makefile conventions]: https://www.gnu.org/prep/standards/html_node/Makefile-Conventions.html
+[staged installs]: https://www.gnu.org/prep/standards/html_node/DESTDIR.html
+[directory redirection]: https://www.gnu.org/prep/standards/html_node/Directory-Variables.html
+[command redefinition]: https://www.gnu.org/prep/standards/html_node/Utilities-in-Makefiles.html
diff --git a/Makefile b/Makefile
index b31ebd0..972d0b2 100644
--- a/Makefile
+++ b/Makefile
@@ -32,12 +32,6 @@
 #  - LZ4 forum froup : https://groups.google.com/forum/#!forum/lz4c
 # ################################################################
 
-DESTDIR ?=
-PREFIX  ?= /usr/local
-VOID    := /dev/null
-
-LIBDIR ?= $(PREFIX)/lib
-INCLUDEDIR=$(PREFIX)/include
 LZ4DIR  = lib
 PRGDIR  = programs
 TESTDIR = tests
@@ -46,14 +40,16 @@ EXDIR   = examples
 
 # Define nul output
 ifneq (,$(filter Windows%,$(OS)))
-EXT = .exe
+EXT  = .exe
+VOID = nul
 else
-EXT =
+EXT  =
+VOID = /dev/null
 endif
 
 
 .PHONY: default
-default: lib lz4-release
+default: lib-release lz4-release
 
 .PHONY: all
 all: allmost manuals
@@ -61,9 +57,9 @@ all: allmost manuals
 .PHONY: allmost
 allmost: lib lz4 examples
 
-.PHONY: lib
-lib:
-	@$(MAKE) -C $(LZ4DIR)
+.PHONY: lib lib-release
+lib lib-release:
+	@$(MAKE) -C $(LZ4DIR) $@
 
 .PHONY: lz4 lz4-release
 lz4 lz4-release: lib
@@ -100,7 +96,7 @@ install uninstall:
 	@$(MAKE) -C $(PRGDIR) $@
 
 travis-install:
-	$(MAKE) -j1 install PREFIX=~/install_test_dir
+	$(MAKE) -j1 install DESTDIR=~/install_test_dir
 
 cmake:
 	@cd contrib/cmake_unofficial; cmake $(CMAKE_PARAMS) CMakeLists.txt; $(MAKE)
diff --git a/README.md b/README.md
index 950e4c4..0e469c8 100644
--- a/README.md
+++ b/README.md
@@ -69,7 +69,22 @@ in single-thread mode.
 [zlib]: http://www.zlib.net/
 [Zstandard]: http://www.zstd.net/
 
-LZ4 is also compatible and well optimized for x32 mode, for which it provides +10% speed performance.
+LZ4 is also compatible and well optimized for x32 mode, for which it provides an additional +10% speed performance.
+
+
+Installation
+-------------------------
+
+`make`
+`make install`     # this command may require root access
+
+LZ4's `Makefile` supports standard [Makefile conventions],
+including [staged installs], [directory redirection], or [command redefinition].
+
+[Makefile conventions]: https://www.gnu.org/prep/standards/html_node/Makefile-Conventions.html
+[staged installs]: https://www.gnu.org/prep/standards/html_node/DESTDIR.html
+[directory redirection]: https://www.gnu.org/prep/standards/html_node/Directory-Variables.html
+[command redefinition]: https://www.gnu.org/prep/standards/html_node/Utilities-in-Makefiles.html
 
 
 Documentation
diff --git a/doc/lz4frame_manual.html b/doc/lz4frame_manual.html
index 87750a1..b82dfe5 100644
--- a/doc/lz4frame_manual.html
+++ b/doc/lz4frame_manual.html
@@ -186,15 +186,15 @@ LZ4F_errorCode_t LZ4F_freeCompressionContext(LZ4F_cctx* cctx);
 <a name="Chapter9"></a><h2>Decompression functions</h2><pre></pre>
 
 <pre><b>typedef struct {
-  unsigned stableDst;       </b>/* guarantee that decompressed data will still be there on next function calls (avoid storage into tmp buffers) */<b>
+  unsigned stableDst;    </b>/* pledge that at least 64KB+64Bytes of previously decompressed data remain unmodifed where it was decoded. This optimization skips storage operations in tmp buffers */<b>
   unsigned reserved[3];
 } LZ4F_decompressOptions_t;
 </b></pre><BR>
 <pre><b>LZ4F_errorCode_t LZ4F_createDecompressionContext(LZ4F_dctx** dctxPtr, unsigned version);
 LZ4F_errorCode_t LZ4F_freeDecompressionContext(LZ4F_dctx* dctx);
-</b><p> Create an LZ4F_decompressionContext_t object, which will be used to track all decompression operations.
- The version provided MUST be LZ4F_VERSION. It is intended to track potential breaking differences between different versions.
- The function will provide a pointer to a fully allocated and initialized LZ4F_decompressionContext_t object.
+</b><p> Create an LZ4F_dctx object, to track all decompression operations.
+ The version provided MUST be LZ4F_VERSION.
+ The function provides a pointer to an allocated and initialized LZ4F_dctx object.
  The result is an errorCode, which can be tested using LZ4F_isError().
  dctx memory can be released using LZ4F_freeDecompressionContext();
  The result of LZ4F_freeDecompressionContext() is indicative of the current state of decompressionContext when being released.
@@ -208,20 +208,22 @@ LZ4F_errorCode_t LZ4F_freeDecompressionContext(LZ4F_dctx* dctx);
                                      LZ4F_frameInfo_t* frameInfoPtr,
                                      const void* srcBuffer, size_t* srcSizePtr);
 </b><p> This function extracts frame parameters (such as max blockSize, frame checksum, etc.).
- Its usage is optional. Extracted information can be useful for allocation purposes, typically.
+ Its usage is optional.
+ Extracted information can typically be useful for allocation purposes.
  This function works in 2 situations :
-   - At the beginning of a new frame, in which case it will decode this information from `srcBuffer`, and start the decoding process.
+   - At the beginning of a new frame, in which case
+     it will decode information from `srcBuffer`, starting the decoding process.
      Input size must be large enough to successfully decode the entire frame header.
      Frame header size is variable, but is guaranteed to be <= LZ4F_HEADER_SIZE_MAX bytes.
      It's allowed to provide more input data than this minimum.
    - After decoding has been started.
      In which case, no input is read, frame parameters are extracted from dctx.
-     If decoding has just started, but not yet extracted information from header, LZ4F_getFrameInfo() will fail.
+   - If decoding has barely started, but not yet extracted information from header, LZ4F_getFrameInfo() will fail.
  The number of bytes consumed from srcBuffer will be updated within *srcSizePtr (necessarily <= original value).
  Decompression must resume from (srcBuffer + *srcSizePtr).
  @return : an hint about how many srcSize bytes LZ4F_decompress() expects for next call,
            or an error code which can be tested using LZ4F_isError()
- note 1 : in case of error, dctx is not modified. Decoding operations can resume from where they stopped.
+ note 1 : in case of error, dctx is not modified. Decoding operation can resume safely.
  note 2 : frame parameters are *copied into* an already allocated LZ4F_frameInfo_t structure.
  
 </p></pre><BR>
@@ -230,18 +232,18 @@ LZ4F_errorCode_t LZ4F_freeDecompressionContext(LZ4F_dctx* dctx);
                                    void* dstBuffer, size_t* dstSizePtr,
                                    const void* srcBuffer, size_t* srcSizePtr,
                                    const LZ4F_decompressOptions_t* dOptPtr);
-</b><p> Call this function repetitively to regenerate data compressed within `srcBuffer`.
+</b><p> Call this function repetitively to regenerate compressed data from `srcBuffer`.
  The function will attempt to decode up to *srcSizePtr bytes from srcBuffer, into dstBuffer of capacity *dstSizePtr.
 
- The number of bytes regenerated into dstBuffer will be provided within *dstSizePtr (necessarily <= original value).
+ The number of bytes regenerated into dstBuffer is provided within *dstSizePtr (necessarily <= original value).
 
- The number of bytes read from srcBuffer will be provided within *srcSizePtr (necessarily <= original value).
- Number of bytes read can be < number of bytes provided, meaning there is some more data to decode.
+ The number of bytes consumed from srcBuffer is provided within *srcSizePtr (necessarily <= original value).
+ Number of bytes consumed can be < number of bytes provided.
  It typically happens when dstBuffer is not large enough to contain all decoded data.
- Remaining data will have to be presented again in a subsequent invocation.
+ Unconsumed source data must be presented again in subsequent invocations.
 
  `dstBuffer` content is expected to be flushed between each invocation, as its content will be overwritten.
- `dstBuffer` can be changed at will between each consecutive function invocation.
+ `dstBuffer` itself can be changed at will between each consecutive function invocation.
 
  @return is an hint of how many `srcSize` bytes LZ4F_decompress() expects for next call.
  Schematically, it's the size of the current (or remaining) compressed block + header of next block.
@@ -259,7 +261,7 @@ LZ4F_errorCode_t LZ4F_freeDecompressionContext(LZ4F_dctx* dctx);
 </b><p>  In case of an error, the context is left in "undefined" state.
   In which case, it's necessary to reset it, before re-using it.
   This method can also be used to abruptly stop an unfinished decompression,
-  and start a new with the same context. 
+  and start a new one using the same context. 
 </p></pre><BR>
 
 </html>
diff --git a/lib/Makefile b/lib/Makefile
index de5c4ff..9abb699 100644
--- a/lib/Makefile
+++ b/lib/Makefile
@@ -60,7 +60,7 @@ ifeq ($(shell uname), Darwin)
 	SHARED_EXT = dylib
 	SHARED_EXT_MAJOR = $(LIBVER_MAJOR).$(SHARED_EXT)
 	SHARED_EXT_VER = $(LIBVER).$(SHARED_EXT)
-	SONAME_FLAGS = -install_name $(PREFIX)/lib/liblz4.$(SHARED_EXT_MAJOR) -compatibility_version $(LIBVER_MAJOR) -current_version $(LIBVER)
+	SONAME_FLAGS = -install_name $(LIBDIR)/liblz4.$(SHARED_EXT_MAJOR) -compatibility_version $(LIBVER_MAJOR) -current_version $(LIBVER)
 else
 	SONAME_FLAGS = -Wl,-soname=liblz4.$(SHARED_EXT).$(LIBVER_MAJOR)
 	SHARED_EXT = so
@@ -115,16 +115,16 @@ clean:
 #-----------------------------------------------------------------------------
 ifneq (,$(filter $(shell uname),Linux Darwin GNU/kFreeBSD GNU OpenBSD FreeBSD NetBSD DragonFly SunOS))
 
-ifneq (,$(filter $(shell uname),SunOS))
-INSTALL ?= ginstall
-else
-INSTALL ?= install
-endif
-
-PREFIX     ?= /usr/local
-DESTDIR    ?=
-LIBDIR     ?= $(PREFIX)/lib
-INCLUDEDIR ?= $(PREFIX)/include
+DESTDIR     ?=
+# directory variables : GNU convention prefers lowercase
+# support both lower and uppercase (BSD), use uppercase in script
+prefix      ?= /usr/local
+PREFIX      ?= $(prefix)
+exec_prefix ?= $(PREFIX)
+libdir      ?= $(exec_prefix)/lib
+LIBDIR      ?= $(libdir)
+includedir  ?= $(PREFIX)/include
+INCLUDEDIR  ?= $(includedir)
 
 ifneq (,$(filter $(shell uname),OpenBSD FreeBSD NetBSD DragonFly))
 PKGCONFIGDIR ?= $(PREFIX)/libdata/pkgconfig
@@ -132,8 +132,14 @@ else
 PKGCONFIGDIR ?= $(LIBDIR)/pkgconfig
 endif
 
-INSTALL_LIB  ?= $(INSTALL) -m 755
-INSTALL_DATA ?= $(INSTALL) -m 644
+ifneq (,$(filter $(shell uname),SunOS))
+INSTALL ?= ginstall
+else
+INSTALL ?= install
+endif
+
+INSTALL_PROGRAM ?= $(INSTALL)
+INSTALL_DATA    ?= $(INSTALL) -m 644
 
 liblz4.pc: liblz4.pc.in Makefile
 	@echo creating pkgconfig
@@ -148,17 +154,17 @@ install: lib liblz4.pc
 	@$(INSTALL_DATA) liblz4.pc $(DESTDIR)$(PKGCONFIGDIR)/
 	@echo Installing libraries
 ifeq ($(BUILD_STATIC),yes)
-	@$(INSTALL_LIB) liblz4.a $(DESTDIR)$(LIBDIR)/liblz4.a
+	@$(INSTALL_DATA) liblz4.a $(DESTDIR)$(LIBDIR)/liblz4.a
 	@$(INSTALL_DATA) lz4frame_static.h $(DESTDIR)$(INCLUDEDIR)/lz4frame_static.h
 endif
-	@$(INSTALL_LIB) liblz4.$(SHARED_EXT_VER) $(DESTDIR)$(LIBDIR)
+	@$(INSTALL_PROGRAM) liblz4.$(SHARED_EXT_VER) $(DESTDIR)$(LIBDIR)
 	@ln -sf liblz4.$(SHARED_EXT_VER) $(DESTDIR)$(LIBDIR)/liblz4.$(SHARED_EXT_MAJOR)
 	@ln -sf liblz4.$(SHARED_EXT_VER) $(DESTDIR)$(LIBDIR)/liblz4.$(SHARED_EXT)
-	@echo Installing includes
+	@echo Installing headers in $(INCLUDEDIR)
 	@$(INSTALL_DATA) lz4.h $(DESTDIR)$(INCLUDEDIR)/lz4.h
 	@$(INSTALL_DATA) lz4hc.h $(DESTDIR)$(INCLUDEDIR)/lz4hc.h
 	@$(INSTALL_DATA) lz4frame.h $(DESTDIR)$(INCLUDEDIR)/lz4frame.h
-	@echo lz4 static and shared libraries installed
+	@echo lz4 libraries installed
 
 uninstall:
 	@$(RM) $(DESTDIR)$(LIBDIR)/pkgconfig/liblz4.pc
diff --git a/programs/Makefile b/programs/Makefile
index c484731..224b013 100644
--- a/programs/Makefile
+++ b/programs/Makefile
@@ -30,7 +30,8 @@
 # ##########################################################################
 
 # Version numbers
-LIBVER_SRC := ../lib/lz4.h
+LZ4DIR   := ../lib
+LIBVER_SRC := $(LZ4DIR)/lz4.h
 LIBVER_MAJOR_SCRIPT:=`sed -n '/define LZ4_VERSION_MAJOR/s/.*[[:blank:]]\([0-9][0-9]*\).*/\1/p' < $(LIBVER_SRC)`
 LIBVER_MINOR_SCRIPT:=`sed -n '/define LZ4_VERSION_MINOR/s/.*[[:blank:]]\([0-9][0-9]*\).*/\1/p' < $(LIBVER_SRC)`
 LIBVER_PATCH_SCRIPT:=`sed -n '/define LZ4_VERSION_RELEASE/s/.*[[:blank:]]\([0-9][0-9]*\).*/\1/p' < $(LIBVER_SRC)`
@@ -38,32 +39,31 @@ LIBVER_SCRIPT:= $(LIBVER_MAJOR_SCRIPT).$(LIBVER_MINOR_SCRIPT).$(LIBVER_PATCH_SCR
 LIBVER_MAJOR := $(shell echo $(LIBVER_MAJOR_SCRIPT))
 LIBVER_MINOR := $(shell echo $(LIBVER_MINOR_SCRIPT))
 LIBVER_PATCH := $(shell echo $(LIBVER_PATCH_SCRIPT))
-LIBVER  := $(shell echo $(LIBVER_SCRIPT))
-
-LZ4DIR  := ../lib
+LIBVER   := $(shell echo $(LIBVER_SCRIPT))
 
 SRCFILES := $(wildcard $(LZ4DIR)/*.c) $(wildcard *.c)
 OBJFILES := $(patsubst %.c,%.o,$(SRCFILES))
-VOID := /dev/null
 
-CPPFLAGS+= -I$(LZ4DIR) -DXXH_NAMESPACE=LZ4_
-CFLAGS  ?= -O3
+CPPFLAGS += -I$(LZ4DIR) -DXXH_NAMESPACE=LZ4_
+CFLAGS   ?= -O3
 DEBUGFLAGS:=-Wall -Wextra -Wundef -Wcast-qual -Wcast-align -Wshadow \
            -Wswitch-enum -Wdeclaration-after-statement -Wstrict-prototypes \
            -Wpointer-arith -Wstrict-aliasing=1
-CFLAGS  += $(DEBUGFLAGS) $(MOREFLAGS)
-FLAGS    = $(CFLAGS) $(CPPFLAGS) $(LDFLAGS)
+CFLAGS   += $(DEBUGFLAGS) $(MOREFLAGS)
+FLAGS     = $(CFLAGS) $(CPPFLAGS) $(LDFLAGS)
 
 LZ4_VERSION=$(LIBVER)
-MD2ROFF  =ronn
-MD2ROFF_FLAGS  = --roff --warnings --manual="User Commands" --organization="lz4 $(LZ4_VERSION)"
+MD2ROFF   = ronn
+MD2ROFF_FLAGS = --roff --warnings --manual="User Commands" --organization="lz4 $(LZ4_VERSION)"
 
 
 # Define *.exe as extension for Windows systems
 ifneq (,$(filter Windows%,$(OS)))
 EXT  :=.exe
+VOID := nul
 else
 EXT  :=
+VOID := /dev/null
 endif
 
 
@@ -121,18 +121,25 @@ else
 INSTALL ?= install
 endif
 
-PREFIX  ?= /usr/local
-DESTDIR ?=
-BINDIR  ?= $(PREFIX)/bin
+DESTDIR     ?=
+# directory variables : GNU convention prefers lowercase
+# support both lower and uppercase (BSD), use uppercase in script
+prefix      ?= /usr/local
+PREFIX      ?= $(prefix)
+exec_prefix ?= $(PREFIX)
+bindir      ?= $(exec_prefix)/bin
+BINDIR      ?= $(bindir)
+datarootdir ?= $(PREFIX)/share
+mandir      ?= $(datarootdir)/man
 
 ifneq (,$(filter $(shell uname),OpenBSD FreeBSD NetBSD DragonFly SunOS))
 MANDIR  ?= $(PREFIX)/man/man1
 else
-MANDIR  ?= $(PREFIX)/share/man/man1
+MANDIR  ?= $(mandir)
 endif
 
 INSTALL_PROGRAM ?= $(INSTALL) -m 755
-INSTALL_MAN     ?= $(INSTALL) -m 644
+INSTALL_DATA    ?= $(INSTALL) -m 644
 
 
 install: lz4$(EXT) lz4c$(EXT)
@@ -143,7 +150,7 @@ install: lz4$(EXT) lz4c$(EXT)
 	@ln -sf lz4 $(DESTDIR)$(BINDIR)/unlz4
 	@$(INSTALL_PROGRAM) lz4c$(EXT) $(DESTDIR)$(BINDIR)/lz4c
 	@echo Installing man pages
-	@$(INSTALL_MAN) lz4.1 $(DESTDIR)$(MANDIR)/lz4.1
+	@$(INSTALL_DATA) lz4.1 $(DESTDIR)$(MANDIR)/lz4.1
 	@ln -sf lz4.1 $(DESTDIR)$(MANDIR)/lz4c.1
 	@ln -sf lz4.1 $(DESTDIR)$(MANDIR)/lz4cat.1
 	@ln -sf lz4.1 $(DESTDIR)$(MANDIR)/unlz4.1