What is liblzma/XZ ?
XZ is a container for compressed archives. It is among the best compressors out there according to several benchmarks:
- Gzip vs Bzip2 vs LZMA vs XZ vs LZ4 vs LZO
- Large Text Compression Benchmark
- Linux Compression Comparison (GZIP vs BZIP2 vs LZMA vs ZIP vs Compress)
It has a good balance between compression time/ratio and decompression time/memory.
About this project
This project aims towards providing:
A quick and easy way to play with XZ compression: Quick and easy as it conforms to zlib API, so that switching from zlib/deflate to xz might be as easy as a string search/replace in your code editor
Complete integration with XZ sources/binaries: You can either use system packages or download a specific version and compile it! See installation below.
Only LZMA2 is supported for compression output. But the library can open and read any LZMA1 or LZMA2 compressed file.
What's new ?
It has been quite some time since I first published this package. In the meantime, N-API eventually became the de facto standard to provide stable ABI API for NodeJS Native Modules.
It therefore replaces good ol' nan !
It supports all NodeJS versions >= 12 and lots has been done to change CICD pipelines and testing.
It has been tested and works on:
- Linux x64 (Ubuntu)
- OSX (
- Raspberry Pi 2/3/4 (both on 32-bit and 64-bit architectures)
- Windows (
windows-2022are part of GitHub CI)
- For Windows There is no "global" installation of the LZMA library on the Windows machine provisionned by GitHub, so it is pointless to build with this config
Several prebuilt versions are bundled within the package.
- Windows x86_64
- Linux x86_64
- MacOS x86_64 / Arm64
If your OS/architecture matches, you will use this version which has been compiled using the following default flags:
|Flag||Description||Default value||Possible values|
|USE_GLOBAL||Should the library use the system provided DLL/.so library ?||
|RUNTIME_LINK||Should the library be linked statically or use the shared LZMA library ?||
|ENABLE_THREAD_SUPPORT||Does the LZMA library support threads ?||
node-gyp will automagically start compiling stuff according to the environment variables set, or the default values above.
If you want to change compilation flags, please read on here.
Thanks to the community, there are several choices out there:
- node-xz Node binding of XZ library
- lzma-native A very complete implementation of XZ library bindings
- Others are also available but they fork "xz" process in the background.
var lzma = require('node-liblzma');
|gzip||xz||(buf, [options], callback)|
|gunzip||unxz||(buf, [options], callback)|
options is an
Object with the following possible attributes:
|filters||Array||LZMA2 (added by default)|
For further information about each of these flags, you will find reference at XZ SDK.
Well, as simple as this one-liner:
$ npm i node-liblzma --save
$ yarn add node-liblzma
If you want to recompile the source, for example to disable threading support in the module, then you have to opt out with:
$ ENABLE_THREAD_SUPPORT=no npm install node-liblzma --build-from-source
Note: Enabling thread support in the library will NOT work if the LZMA library itself has been built without such support.
To build the module, you have the following options:
- Using system development libraries
- Ask the build system to download
xzand build it
node-liblzma, and have it use it after
Using system dev libraries to compile
You need to have the development package installed on your system. If you have Debian based distro:
# apt-get install liblzma-dev
Automatic download and compilation to statically link
If you do not plan on having a local install, you can ask for automatic download and build of whatever version of
xz you want.
$ npm install node-liblzma --build-from-source
When no option is given in the commandline arguments, it will build with default values.
Local install of
xz sources (outside
So you did install
xz somewhere outside the module and want the module to use it.
For that, you need to set the include directory and library directory search paths as GCC environment variables.
$ export CPATH=$HOME/path/to/headers $ export LIBRARY_PATH=$HOME/path/to/lib $ export LD_LIBRARY_PATH=$HOME/path/to/lib:$LD_LIBRARY_PATH
The latest is needed for tests to be run right after.
Once done, this should suffice:
$ npm install
You can run tests with:
$ npm test
It will build and launch tests suite with Mocha.
As the API is very close to NodeJS Zlib, you will probably find a good reference there.
Otherwise examples can be found as part of the test suite, so feel free to use them! They are written in CoffeeScript.
If you find one, feel free to contribute and post a new issue! PR are accepted as well :)
Kudos goes to addaleax for helping me out with C++ stuff !
If you compile with threads, you may see a bunch of warnings about
This is normal and does not prevent threading from being active and working.
I did not yet figure how to fix this except by masking the warning..
This software is released under LGPL3.0+