From b8575f2d2b1e05c20812215759b29bf2d0f7a708 Mon Sep 17 00:00:00 2001 From: Yann Collet Date: Wed, 10 May 2017 13:26:04 -0700 Subject: updated Makefile to automatically build manual files with make all --- Makefile | 81 ++++++++++++++++++++----------------------- contrib/gen_manual/.gitignore | 2 ++ contrib/gen_manual/Makefile | 26 +++++++++++--- doc/lz4_manual.html | 18 +++++----- doc/lz4frame_manual.html | 75 +++++++++++++++++++++++++++------------ lib/Makefile | 13 +++---- lib/lz4frame.h | 2 +- programs/Makefile | 26 ++++++-------- 8 files changed, 140 insertions(+), 103 deletions(-) create mode 100644 contrib/gen_manual/.gitignore diff --git a/Makefile b/Makefile index 1f5165d..24328d5 100644 --- a/Makefile +++ b/Makefile @@ -52,36 +52,36 @@ EXT = endif -.PHONY: default all lib lz4 clean test versionsTest examples +.PHONY: default +default: lib lz4-release -default: - @$(MAKE) -C $(LZ4DIR) - @$(MAKE) -C $(PRGDIR) - @cp $(PRGDIR)/lz4$(EXT) . - -all: - @$(MAKE) -C $(LZ4DIR) $@ - @$(MAKE) -C $(PRGDIR) $@ - @$(MAKE) -C $(TESTDIR) $@ - @$(MAKE) -C $(EXDIR) $@ +.PHONY: all +all: default examples manuals +.PHONY: lib lib: @$(MAKE) -C $(LZ4DIR) -lz4: +.PHONY: lz4 lz4-release +lz4 lz4-release: lib @$(MAKE) -C $(PRGDIR) $@ @cp $(PRGDIR)/lz4$(EXT) . -lz4-release: - @$(MAKE) -C $(PRGDIR) - @cp $(PRGDIR)/lz4$(EXT) . +.PHONY: examples +examples: lib lz4-release + $(MAKE) -C $(EXDIR) test +.PHONY: manuals +manuals: + @$(MAKE) -C contrib/gen_manual $@ + +.PHONY: clean clean: + @$(MAKE) -C $(LZ4DIR) $@ > $(VOID) @$(MAKE) -C $(PRGDIR) $@ > $(VOID) @$(MAKE) -C $(TESTDIR) $@ > $(VOID) - @$(MAKE) -C $(LZ4DIR) $@ > $(VOID) @$(MAKE) -C $(EXDIR) $@ > $(VOID) - @$(MAKE) -C examples $@ > $(VOID) + @$(MAKE) -C contrib/gen_manual $@ @$(RM) lz4$(EXT) @echo Cleaning completed @@ -92,17 +92,31 @@ clean: ifneq (,$(filter $(shell uname),Linux Darwin GNU/kFreeBSD GNU OpenBSD FreeBSD NetBSD DragonFly SunOS)) HOST_OS = POSIX -install: - @$(MAKE) -C $(LZ4DIR) $@ - @$(MAKE) -C $(PRGDIR) $@ - -uninstall: +install uninstall: @$(MAKE) -C $(LZ4DIR) $@ @$(MAKE) -C $(PRGDIR) $@ travis-install: $(MAKE) -j1 install PREFIX=~/install_test_dir +cmake: + @cd contrib/cmake_unofficial; cmake $(CMAKE_PARAMS) CMakeLists.txt; $(MAKE) + +endif + + +ifneq (,$(filter MSYS%,$(shell uname))) +HOST_OS = MSYS +CMAKE_PARAMS = -G"MSYS Makefiles" +endif + + +#------------------------------------------------------------------------ +#make tests validated only for MSYS, Linux, OSX, kFreeBSD and Hurd targets +#------------------------------------------------------------------------ +ifneq (,$(filter $(HOST_OS),MSYS POSIX)) + +.PHONY: test test: $(MAKE) -C $(TESTDIR) $@ @@ -135,31 +149,10 @@ platformTest: clean CFLAGS="-O3 -Werror -static" $(MAKE) -C $(TESTDIR) all $(MAKE) -C $(TESTDIR) test-platform +.PHONY: versionsTest versionsTest: clean $(MAKE) -C $(TESTDIR) $@ -examples: - $(MAKE) -C $(LZ4DIR) - $(MAKE) -C $(PRGDIR) lz4 - $(MAKE) -C examples test - -endif - - -ifneq (,$(filter MSYS%,$(shell uname))) -HOST_OS = MSYS -CMAKE_PARAMS = -G"MSYS Makefiles" -endif - - -#------------------------------------------------------------------------ -#make tests validated only for MSYS, Linux, OSX, kFreeBSD and Hurd targets -#------------------------------------------------------------------------ -ifneq (,$(filter $(HOST_OS),MSYS POSIX)) - -cmake: - @cd contrib/cmake_unofficial; cmake $(CMAKE_PARAMS) CMakeLists.txt; $(MAKE) - gpptest: clean g++ -v CC=g++ $(MAKE) -C $(LZ4DIR) all CFLAGS="-O3 -Wall -Wextra -Wundef -Wshadow -Wcast-align -Werror" diff --git a/contrib/gen_manual/.gitignore b/contrib/gen_manual/.gitignore new file mode 100644 index 0000000..6ea967f --- /dev/null +++ b/contrib/gen_manual/.gitignore @@ -0,0 +1,2 @@ +# build artefact +gen_manual diff --git a/contrib/gen_manual/Makefile b/contrib/gen_manual/Makefile index adbcca2..9fbe858 100644 --- a/contrib/gen_manual/Makefile +++ b/contrib/gen_manual/Makefile @@ -35,7 +35,15 @@ CFLAGS += -Wall -Wextra -Wcast-qual -Wcast-align -Wshadow -Wstrict-aliasing=1 -W CFLAGS += $(MOREFLAGS) FLAGS = $(CPPFLAGS) $(CFLAGS) $(LDFLAGS) - +LZ4API = ../../lib/lz4.h +LZ4MANUAL = ../../doc/lz4_manual.html +LZ4FAPI = ../../lib/lz4frame.h +LZ4FMANUAL = ../../doc/lz4frame_manual.html +LIBVER_MAJOR_SCRIPT:=`sed -n '/define LZ4_VERSION_MAJOR/s/.*[[:blank:]]\([0-9][0-9]*\).*/\1/p' < $(LZ4API)` +LIBVER_MINOR_SCRIPT:=`sed -n '/define LZ4_VERSION_MINOR/s/.*[[:blank:]]\([0-9][0-9]*\).*/\1/p' < $(LZ4API)` +LIBVER_PATCH_SCRIPT:=`sed -n '/define LZ4_VERSION_RELEASE/s/.*[[:blank:]]\([0-9][0-9]*\).*/\1/p' < $(LZ4API)` +LIBVER_SCRIPT:= $(LIBVER_MAJOR_SCRIPT).$(LIBVER_MINOR_SCRIPT).$(LIBVER_PATCH_SCRIPT) +LZ4VER := $(shell echo $(LIBVER_SCRIPT)) # Define *.exe as extension for Windows systems ifneq (,$(filter Windows%,$(OS))) @@ -45,14 +53,24 @@ EXT = endif -.PHONY: default gen_manual - +.PHONY: default default: gen_manual gen_manual: gen_manual.cpp - $(CXX) $(FLAGS) $^ -o $@$(EXT) + $(CXX) $(FLAGS) $^ -o $@$(EXT) + +$(LZ4MANUAL) : gen_manual $(LZ4API) + echo "Update lz4 manual in /doc" + ./gen_manual $(LZ4VER) $(LZ4API) $@ + +$(LZ4FMANUAL) : gen_manual $(LZ4FAPI) + echo "Update lz4frame manual in /doc" + ./gen_manual $(LZ4VER) $(LZ4FAPI) $@ +.PHONY: manuals +manuals: gen_manual $(LZ4MANUAL) $(LZ4FMANUAL) +.PHONY: clean clean: @$(RM) gen_manual$(EXT) @echo Cleaning completed diff --git a/doc/lz4_manual.html b/doc/lz4_manual.html index ff6e149..4c4174d 100644 --- a/doc/lz4_manual.html +++ b/doc/lz4_manual.html @@ -1,10 +1,10 @@ -lz4 1.7.5 Manual +1.7.6 Manual -

lz4 1.7.5 Manual

+

1.7.6 Manual

Contents

    @@ -170,21 +170,21 @@ int LZ4_freeStream (LZ4_stream_t* streamPtr);


    -
    int LZ4_compress_fast_continue (LZ4_stream_t* streamPtr, const char* src, char* dst, int srcSize, int maxDstSize, int acceleration);
+
    int LZ4_compress_fast_continue (LZ4_stream_t* streamPtr, const char* src, char* dst, int srcSize, int dstCapacity, int acceleration);
 
      Compress buffer content 'src', using data from previously compressed blocks as dictionary to improve compression ratio.
-  Important : Previous data blocks are assumed to still be present and unmodified !
+  Important : Previous data blocks are assumed to remain present and unmodified !
   'dst' buffer must be already allocated.
-  If maxDstSize >= LZ4_compressBound(srcSize), compression is guaranteed to succeed, and runs faster.
+  If dstCapacity >= LZ4_compressBound(srcSize), compression is guaranteed to succeed, and runs faster.
   If not, and if compressed data cannot fit into 'dst' buffer size, compression stops, and function returns a zero.
+  After an error, the stream status is invalid, and it can only be reset or freed.
  
 

    
 
 
    int LZ4_saveDict (LZ4_stream_t* streamPtr, char* safeBuffer, int dictSize);
-
      If previously compressed data block is not guaranteed to remain available at its memory location,
+
      If previously compressed data block is not guaranteed to remain available at its current memory location,
   save it into a safer place (char* safeBuffer).
-  Note : you don't need to call LZ4_loadDict() afterwards,
-         dictionary is immediately usable, you can therefore call LZ4_compress_fast_continue().
-  Return : saved dictionary size in bytes (necessarily <= dictSize), or 0 if error.
+  Note : it's not necessary to call LZ4_loadDict() after LZ4_saveDict(), dictionary is immediately usable.
+  @return : saved dictionary size in bytes (necessarily <= dictSize), or 0 if error.
  
 

    
 
diff --git a/doc/lz4frame_manual.html b/doc/lz4frame_manual.html
index f76ec3d..5d553ed 100644
--- a/doc/lz4frame_manual.html
+++ b/doc/lz4frame_manual.html
@@ -1,19 +1,23 @@
 
 
 
-lz4frame 1.7.5 Manual
+1.7.6 Manual
 
 
-
    lz4frame 1.7.5 Manual
    
+
    1.7.6 Manual
    
 
    
 
    Contents
    
 
      
 
    1. Introduction
      2. 
-
    2. Error management
      3. 
-
    3. Frame compression types
      4. 
-
    4. Simple compression function
      5. 
-
    5. Advanced compression functions
      6. 
-
    6. Decompression functions
      7. 
+
    7. Compiler specifics
      8. 
+
    8. Error management
      9. 
+
    9. Frame compression types
      10. 
+
    10. Simple compression function
      11. 
+
    11. Advanced compression functions
      12. 
+
    12. Resource Management
      13. 
+
    13. Compression
      14. 
+
    14. Decompression functions
      15. 
+
    15. Streaming decompression functions
      16. 
 
    
 
    
 
    Introduction
    @@ -22,13 +26,15 @@
   of encoding standard metadata alongside LZ4-compressed blocks.
 
    
 
-
    Error management
    
+
    Compiler specifics
    
+
+
    Error management
    
 
 
    unsigned    LZ4F_isError(LZ4F_errorCode_t code);   /**< tells if a `LZ4F_errorCode_t` function result is an error code */
 

    
 
    const char* LZ4F_getErrorName(LZ4F_errorCode_t code);   /**< return error code string; useful for debugging */
 

    
-
    Frame compression types
    
+
    Frame compression types
    
 
 
    typedef enum {
     LZ4F_default=0,
@@ -77,7 +83,7 @@
 
 
    typedef struct {
   LZ4F_frameInfo_t frameInfo;
-  int      compressionLevel;       /* 0 == default (fast mode); values above 16 count as 16; values below 0 count as 0 */
+  int      compressionLevel;       /* 0 == default (fast mode); values above LZ4HC_CLEVEL_MAX count as LZ4HC_CLEVEL_MAX; values below 0 trigger "fast acceleration", proportional to value */
   unsigned autoFlush;              /* 1 == always flush (reduce usage of tmp buffer) */
   unsigned reserved[4];            /* must be zero for forward compatibility */
 } LZ4F_preferences_t;
@@ -86,7 +92,7 @@
  All reserved fields must be set to zero. 
 

    
 
-
    Simple compression function
    
+
    Simple compression function
    
 
 
    size_t LZ4F_compressFrameBound(size_t srcSize, const LZ4F_preferences_t* preferencesPtr);
 
     Returns the maximum possible size of a frame compressed with LZ4F_compressFrame() given srcSize content and preferences.
@@ -105,17 +111,19 @@
  
 

    
 
-
    Advanced compression functions
    
+
    Advanced compression functions
    
 
 
    typedef struct {
   unsigned stableSrc;    /* 1 == src content will remain present on future calls to LZ4F_compress(); skip copying src content within tmp buffer */
   unsigned reserved[3];
 } LZ4F_compressOptions_t;
 

    
+
    Resource Management
    
+
 
    LZ4F_errorCode_t LZ4F_createCompressionContext(LZ4F_cctx** cctxPtr, unsigned version);
 LZ4F_errorCode_t LZ4F_freeCompressionContext(LZ4F_cctx* cctx);
 
     The first thing to do is to create a compressionContext object, which will be used in all compression operations.
- This is achieved using LZ4F_createCompressionContext(), which takes as argument a version and an LZ4F_preferences_t structure.
+ This is achieved using LZ4F_createCompressionContext(), which takes as argument a version.
  The version provided MUST be LZ4F_VERSION. It is intended to track potential version mismatch, notably when using DLL.
  The function will provide a pointer to a fully allocated LZ4F_cctx object.
  If @return != zero, there was an error during context creation.
@@ -123,6 +131,8 @@ LZ4F_errorCode_t LZ4F_freeCompressionContext(LZ4F_cctx* cctx);
  
 

    
 
+
    Compression
    
+
 
    size_t LZ4F_compressBegin(LZ4F_cctx* cctx, void* dstBuffer, size_t dstCapacity, const LZ4F_preferences_t* prefsPtr);
 
     will write the frame header into dstBuffer.
  dstCapacity must be large enough to store the header. Maximum header size is LZ4F_HEADER_SIZE_MAX bytes.
@@ -173,7 +183,7 @@ LZ4F_errorCode_t LZ4F_freeCompressionContext(LZ4F_cctx* cctx);
  
 

    
 
-
    Decompression functions
    
+
    Decompression functions
    
 
 
    typedef struct {
   unsigned stableDst;       /* guarantee that decompressed data will still be there on next function calls (avoid storage into tmp buffers) */
@@ -181,7 +191,7 @@ LZ4F_errorCode_t LZ4F_freeCompressionContext(LZ4F_cctx* cctx);
 } LZ4F_decompressOptions_t;
 

    
 
    LZ4F_errorCode_t LZ4F_createDecompressionContext(LZ4F_dctx** dctxPtr, unsigned version);
-LZ4F_errorCode_t LZ4F_freeDecompressionContext(LZ4F_dctx* const dctx);
+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.
@@ -192,19 +202,27 @@ LZ4F_errorCode_t LZ4F_freeDecompressionContext(LZ4F_dctx* const dctx);
  
 

    
 
+
    Streaming decompression functions
    
+
 
    size_t LZ4F_getFrameInfo(LZ4F_dctx* dctx,
                                      LZ4F_frameInfo_t* frameInfoPtr,
                                      const void* srcBuffer, size_t* srcSizePtr);
-
     This function decodes frame header information (such as max blockSize, frame checksum, etc.).
- Its usage is optional. The objective is to extract frame header information, typically for allocation purposes.
- A header size is variable and can length from 7 to 15 bytes. It's possible to provide more input bytes than that.
+
     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.
+ 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.
+     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.
  The number of bytes consumed from srcBuffer will be updated within *srcSizePtr (necessarily <= original value).
- Decompression must resume from this point (srcBuffer + *srcSizePtr).
- Note that LZ4F_getFrameInfo() can also be used anytime *after* decompression is started, in which case 0 input byte can be enough.
- Frame header info is *copied into* an already allocated LZ4F_frameInfo_t structure.
+ 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()
-           (typically, when there is not enough src bytes to fully decode the frame header)
+ note 1 : in case of error, dctx is not modified. Decoding operations can resume from where they stopped.
+ note 2 : frame parameters are *copied into* an already allocated LZ4F_frameInfo_t structure.
  
 

    
 
@@ -227,14 +245,25 @@ LZ4F_errorCode_t LZ4F_freeDecompressionContext(LZ4F_dctx* const dctx);
 
  @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.
- Respecting the hint provides some boost to performance, since it does skip intermediate buffers.
+ Respecting the hint provides some small speed benefit, because it skips intermediate buffers.
  This is just a hint though, it's always possible to provide any srcSize.
  When a frame is fully decoded, @return will be 0 (no more data expected).
  If decompression failed, @return is an error code, which can be tested using LZ4F_isError().
 
  After a frame is fully decoded, dctx can be used again to decompress another frame.
+ After a decompression error, use LZ4F_resetDecompressionContext() before re-using dctx, to return to clean state.
  
 

    
 
+
    LZ4F_errorCode_t LZ4F_resetDecompressionContext(LZ4F_dctx* dctx);
+
      When decompression ends successfully,
+  it's possible to start a new decompression immediately
+  re-using the same context.
+  However, 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 on the same context. 
+

    
+
 
 
diff --git a/lib/Makefile b/lib/Makefile
index 9a794b8..c6fd7b8 100644
--- a/lib/Makefile
+++ b/lib/Makefile
@@ -46,10 +46,10 @@ BUILD_STATIC:= yes
 
 CPPFLAGS+= -DXXH_NAMESPACE=LZ4_
 CFLAGS  ?= -O3
-DEBUGFLAGS:=-g -Wall -Wextra -Wcast-qual -Wcast-align -Wshadow \
+DEBUGFLAGS:= -Wall -Wextra -Wcast-qual -Wcast-align -Wshadow \
            -Wswitch-enum -Wdeclaration-after-statement -Wstrict-prototypes -Wundef \
            -Wpointer-arith -Wstrict-aliasing=1
-CFLAGS  += $(MOREFLAGS)
+CFLAGS  += $(DEBUGFLAGS) $(MOREFLAGS)
 FLAGS    = $(CPPFLAGS) $(CFLAGS) $(LDFLAGS)
 
 
@@ -70,12 +70,13 @@ endif
 
 LIBLZ4 = liblz4.$(SHARED_EXT_VER)
 
+.PHONY: default
 default: lib-release
 
-lib-release: liblz4.a liblz4
+lib-release: DEBUGFLAGS :=
+lib-release: lib
 
-lib: CFLAGS += $(DEBUGFLAGS)
-lib: lib-release
+lib: liblz4.a liblz4
 
 all: lib
 
@@ -83,7 +84,7 @@ all32: CFLAGS+=-m32
 all32: all
 
 liblz4.a: *.c
-ifeq ($(BUILD_STATIC),yes)
+ifeq ($(BUILD_STATIC),yes)  # can be disabled on command line
 	@echo compiling static library
 	@$(CC) $(CPPFLAGS) $(CFLAGS) -c $^
 	@$(AR) rcs $@ *.o
diff --git a/lib/lz4frame.h b/lib/lz4frame.h
index b61fe7f..9a2130a 100644
--- a/lib/lz4frame.h
+++ b/lib/lz4frame.h
@@ -363,7 +363,7 @@ LZ4FLIB_API size_t LZ4F_decompress(LZ4F_dctx* dctx,
                                    const LZ4F_decompressOptions_t* dOptPtr);
 
 
-/*! LZ4F_resetDecompressionContext() :
+/*! LZ4F_resetDecompressionContext() : v1.8.0
  *  When decompression ends successfully,
  *  it's possible to start a new decompression immediately
  *  re-using the same context.
diff --git a/programs/Makefile b/programs/Makefile
index 4a8103c..2e73780 100644
--- a/programs/Makefile
+++ b/programs/Makefile
@@ -51,7 +51,7 @@ CFLAGS  ?= -O3
 DEBUGFLAGS:=-g -Wall -Wextra -Wundef -Wcast-qual -Wcast-align -Wshadow \
            -Wswitch-enum -Wdeclaration-after-statement -Wstrict-prototypes \
            -Wpointer-arith -Wstrict-aliasing=1
-CFLAGS  += $(MOREFLAGS)
+CFLAGS  += $(DEBUGFLAGS) $(MOREFLAGS)
 FLAGS    = $(CFLAGS) $(CPPFLAGS) $(LDFLAGS)
 
 LZ4_VERSION=$(LIBVER)
@@ -75,28 +75,17 @@ all: lz4 lz4c
 all32: CFLAGS+=-m32
 all32: all
 
-lz4: CFLAGS += $(DEBUGFLAGS)
 lz4: $(OBJFILES)
 	$(CC) $(FLAGS) $^ -o $@$(EXT)
 
 lz4-release: DEBUGFLAGS=
 lz4-release: lz4
 
-lz4c  : CFLAGS += $(DEBUGFLAGS)
-lz4c  : $(SRCFILES)
-	$(CC) $(FLAGS) -DENABLE_LZ4C_LEGACY_OPTIONS $^ -o $@$(EXT)
-
-lz4c32: CFLAGS += -m32 $(DEBUGFLAGS)
-lz4c32: $(SRCFILES)
+lz4c32: CFLAGS += -m32
+lz4c: CPPFLAGS += -DENABLE_LZ4C_LEGACY_OPTIONS
+lz4c lz4c32 : $(SRCFILES)
 	$(CC) $(FLAGS) $^ -o $@$(EXT)
 
-clean:
-	@$(MAKE) -C $(LZ4DIR) $@ > $(VOID)
-	@$(RM) core *.o *.test tmp* \
-           lz4$(EXT) lz4c$(EXT) lz4c32$(EXT) unlz4 lz4cat
-	@echo Cleaning completed
-
-
 lz4.1: lz4.1.md
 	cat $^ | $(MD2ROFF) $(MD2ROFF_FLAGS) | sed -n '/^\.\\\".*/!p' > $@
 
@@ -108,6 +97,12 @@ clean-man:
 preview-man: clean-man man
 	man ./lz4.1
 
+clean:
+	@$(MAKE) -C $(LZ4DIR) $@ > $(VOID)
+	@$(RM) core *.o *.test tmp* \
+           lz4$(EXT) lz4c$(EXT) lz4c32$(EXT) unlz4 lz4cat
+	@echo Cleaning completed
+
 
 #-----------------------------------------------------------------------------
 # make install is validated only for Linux, OSX, BSD, Hurd and Solaris targets
@@ -120,7 +115,6 @@ unlz4: lz4
 lz4cat: lz4
 	ln -s lz4 lz4cat
 
-
 ifneq (,$(filter $(shell uname),SunOS))
 INSTALL ?= ginstall
 else
-- 
cgit v0.12