From aea7d521aed2506270a14d8e901ea657d6a1faf4 Mon Sep 17 00:00:00 2001 From: Yann Collet Date: Mon, 14 Aug 2017 15:13:23 -0700 Subject: better respect GNU standard Makefile conventions supports lowercase directory variables add an "Installation" section in README.md added an INSTALL file --- INSTALL | 13 +++++++++++++ Makefile | 22 +++++++++------------- README.md | 17 ++++++++++++++++- doc/lz4frame_manual.html | 32 +++++++++++++++++--------------- lib/Makefile | 40 +++++++++++++++++++++++----------------- programs/Makefile | 41 ++++++++++++++++++++++++----------------- 6 files changed, 102 insertions(+), 63 deletions(-) create mode 100644 INSTALL 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);

Decompression functions


 
 
typedef struct {
-  unsigned stableDst;       /* guarantee that decompressed data will still be there on next function calls (avoid storage into tmp buffers) */
+  unsigned stableDst;    /* pledge that at least 64KB+64Bytes of previously decompressed data remain unmodifed where it was decoded. This optimization skips storage operations in tmp buffers */
   unsigned reserved[3];
 } LZ4F_decompressOptions_t;
 


 
LZ4F_errorCode_t LZ4F_createDecompressionContext(LZ4F_dctx** dctxPtr, unsigned version);
 LZ4F_errorCode_t LZ4F_freeDecompressionContext(LZ4F_dctx* dctx);
-
 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.
+
 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);
 
 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.
  
 


@@ -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);
-
 Call this function repetitively to regenerate data compressed within `srcBuffer`.
+
 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);
 
  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. 
 


 
 
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
-- 
cgit v0.12