diff options
| -rw-r--r-- | .travis.yml | 7 | ||||
| -rw-r--r-- | lib/README.md | 25 | ||||
| -rw-r--r-- | tests/README.md | 48 |
3 files changed, 74 insertions, 6 deletions
diff --git a/.travis.yml b/.travis.yml index 3a314c6..e92b7fe 100644 --- a/.travis.yml +++ b/.travis.yml @@ -40,15 +40,18 @@ matrix: - libc6-dev-i386 - gcc-multilib - - env: Ubu=14.04 Cmd='make staticAnalyze sanitize' COMPILER=clang + - env: Ubu=14.04 Cmd='make sanitize' COMPILER=clang dist: trusty sudo: required addons: apt: packages: - valgrind - - clang + - env: Ubu=14.04 Cmd='make staticAnalyze' COMPILER=clang + dist: trusty + sudo: required + - env: Ubu=14.04 Cmd='make platformTest CC=arm-linux-gnueabi-gcc QEMU_SYS=qemu-arm-static && make platformTest CC=aarch64-linux-gnu-gcc QEMU_SYS=qemu-aarch64-static' COMPILER=arm-linux-gnueabi-gcc dist: trusty sudo: required diff --git a/lib/README.md b/lib/README.md index 209cac1..e4649aa 100644 --- a/lib/README.md +++ b/lib/README.md @@ -1,22 +1,26 @@ LZ4 - Library Files ================================ -All source material within __lib__ directory are BSD 2-Clause licensed. -See [LICENSE](LICENSE) for details. -The license is also repeated at the top of each source file. - The directory contains many files, but depending on project's objectives, not all of them are necessary. +#### Minimal LZ4 build + The minimum required is **`lz4.c`** and **`lz4.h`**, which will provide the fast compression and decompression algorithm. + +#### The High Compression variant od LZ4 + For more compression at the cost of compression speed, the High Compression variant **lz4hc** is available. It's necessary to add **`lz4hc.c`** and **`lz4hc.h`**. The variant still depends on regular `lz4` source files. In particular, the decompression is still provided by `lz4.c`. + +#### Compatibiliy issues + In order to produce files or streams compatible with `lz4` command line utility, it's necessary to encode lz4-compressed blocks using the [official interoperable frame format]. This format is generated and decoded automatically by the **lz4frame** library. @@ -26,10 +30,16 @@ which provides error detection. This is what `liblz4` does, to avoid symbol duplication in case a user program would link to several libraries containing xxhash symbols.) + +#### Advanced API + A more complex `lz4frame_static.h` is also provided. It contains definitions which are not guaranteed to remain stable within future versions. It must be used with static linking ***only***. + +#### Miscellaneous + Other files present in the directory are not source code. There are : - LICENSE : contains the BSD license text @@ -38,3 +48,10 @@ Other files present in the directory are not source code. There are : - README.md : this file [official interoperable frame format]: ../doc/lz4_Frame_format.md + + +#### License + +All source material within __lib__ directory are BSD 2-Clause licensed. +See [LICENSE](LICENSE) for details. +The license is also repeated at the top of each source file. diff --git a/tests/README.md b/tests/README.md index 9070317..75b7b9f 100644 --- a/tests/README.md +++ b/tests/README.md @@ -6,6 +6,7 @@ This directory contains the following programs and scripts: - `frametest` : Test tool that checks lz4frame integrity on target platform - `fullbench` : Precisely measure speed for each lz4 inner functions - `fuzzer` : Test tool, to check lz4 integrity on target platform +- `test-lz4-speed.py` : script for testing lz4 speed difference between commits - `test-lz4-versions.py` : compatibility test between lz4 versions stored on Github @@ -16,6 +17,53 @@ Then all taged (released) versions of lz4 are compiled. In the following step interoperability between lz4 versions is checked. +#### `test-lz4-speed.py` - script for testing lz4 speed difference between commits + +This script creates `speedTest` directory to which lz4 repository is cloned. +Then it compiles all branches of lz4 and performs a speed benchmark for a given list of files (the `testFileNames` parameter). +After `sleepTime` (an optional parameter, default 300 seconds) seconds the script checks repository for new commits. +If a new commit is found it is compiled and a speed benchmark for this commit is performed. +The results of the speed benchmark are compared to the previous results. +If compression or decompression speed for one of lz4 levels is lower than `lowerLimit` (an optional parameter, default 0.98) the speed benchmark is restarted. +If second results are also lower than `lowerLimit` the warning e-mail is send to recipients from the list (the `emails` parameter). + +Additional remarks: +- To be sure that speed results are accurate the script should be run on a "stable" target system with no other jobs running in parallel +- Using the script with virtual machines can lead to large variations of speed results +- The speed benchmark is not performed until computers' load average is lower than `maxLoadAvg` (an optional parameter, default 0.75) +- The script sends e-mails using `mutt`; if `mutt` is not available it sends e-mails without attachments using `mail`; if both are not available it only prints a warning + + +The example usage with two test files, one e-mail address, and with an additional message: +``` +./test-lz4-speed.py "silesia.tar calgary.tar" "email@gmail.com" --message "tested on my laptop" --sleepTime 60 +``` + +To run the script in background please use: +``` +nohup ./test-lz4-speed.py testFileNames emails & +``` + +The full list of parameters: +``` +positional arguments: + testFileNames file names list for speed benchmark + emails list of e-mail addresses to send warnings + +optional arguments: + -h, --help show this help message and exit + --message MESSAGE attach an additional message to e-mail + --lowerLimit LOWERLIMIT + send email if speed is lower than given limit + --maxLoadAvg MAXLOADAVG + maximum load average to start testing + --lastCLevel LASTCLEVEL + last compression level for testing + --sleepTime SLEEPTIME + frequency of repository checking in seconds +``` + + #### License All files in this directory are licensed under GPL-v2. |