Libx LZ4 ドキュメント

    LZ4: ライブラリファイル

    /libディレクトリには多数のファイルがありますが、プロジェクトの目的によっては、すべてが必要なわけではありません。制限のあるシステムでは、バイナリーサイズと依存関係を減らすため、組み込むソースファイルの数を減らしたい場合があります。

    機能は、以下に説明する「レベル」単位で追加します。

    レベル1: 最小限のLZ4ビルド

    最低限必要なのは lz4.c と lz4.h で、高速な圧縮・展開アルゴリズムを提供します。LZ4ブロック形式でデータを生成・展開します。

    レベル2: 高圧縮版

    圧縮速度と引き換えに圧縮率を上げるため、lz4hc という高圧縮版を利用できます。lz4hc.c と lz4hc.h を追加してください。この版もLZ4ブロック形式を使って圧縮し、通常のlib/lz4.*ソースファイルに依存します。

    レベル3: 相互運用のためのフレーム対応

    lz4コマンドラインユーティリティと互換性のある圧縮データを生成するには、公式の相互運用可能なフレーム形式を使う必要があります。lz4frame ライブラリが、この形式を自動的に生成・展開します。公開APIはlib/lz4frame.hに記述されています。正しく動作するため、lz4frameには、lz4、lz4hcに加え xxhash も含め、/libにある他のすべてのモジュールが必要です。そのため、xxhash.cとxxhash.hも組み込む必要があります。

    レベル4: ファイル圧縮操作

    ファイル操作の補助として、ライブラリには最近lz4file.cとlz4file.hが追加されました（執筆時点では、まだ実験的とみなされています）。これらは、透過的なLZ4圧縮・展開を使って、ファイルを開く・読む・書く・閉じる操作を可能にします。その結果、lz4fileを使うと<stdio.h>への依存関係が増えます。

    lz4fileは、LZ4フレーム形式仕様に準拠する圧縮データを生成するため、lz4frameに依存します。したがって、この機能を有効にするには、lib/ディレクトリのすべての*.cと*.hファイルを組み込む必要があります。

    高度なAPI・実験的API

    将来のバージョンで安定性が保証されない定義は、LZ4_STATIC_LINKING_ONLYなどのマクロで保護されています。名前が示すとおり、これらの定義は静的リンクの文脈で のみ 使うべきです。それ以外では、依存するアプリケーションが、将来のAPIまたはABIの互換性破壊により動作しなくなる可能性があります。関連するシンボルも、既定では動的ライブラリから公開されません。それでも必要な場合は、ビルドマクロLZ4_PUBLISH_STATIC_FUNCTIONSとLZ4F_PUBLISH_STATIC_FUNCTIONSを使い、公開を強制できます。

    ビルドマクロ

    次のビルドマクロを選び、コンパイル時のソースコードの動作を調整できます。

    • LZ4_FAST_DEC_LOOP: 速度を最適化した展開ループを有効にします。現代のCPUでは、より効果的です。このループはx86、x64、aarch64のCPUでよく動作し、これらでは自動的に有効になります。プリプロセッサーにLZ4_FAST_DEC_LOOP=1または0を渡して、手動で有効・無効を切り替えることもできます。例えば、gccでは-DLZ4_FAST_DEC_LOOP=1、makeではCPPFLAGS+=-DLZ4_FAST_DEC_LOOP=1 make lz4です。

    • LZ4_DISTANCE_MAX: 圧縮器が許容する最大オフセットを制御します。既定値は65535で、lz4形式がサポートする最大値です。最大距離を減らすと、LZ4が一致を見つける機会が減り、圧縮率は悪化します。小さな最大距離を設定することで、メモリの制約がある特定の展開器との互換性を確保できる場合があります。このビルドマクロが影響するのは、圧縮器の圧縮出力だけです。

    • LZ4_DISABLE_DEPRECATE_WARNINGS: 非推奨の関数を呼ぶと、コンパイラーが警告を出します。これは、利用者にソースコードの更新を促すためです。問題になる場合は、通常、コンパイラーに警告を無視させることができます。例えば、gccの-Wno-deprecated-declarationsや、Visual Studioの_CRT_SECURE_NO_WARNINGSです。このビルドマクロは、プロジェクト固有の別の方法を提供します。LZ4のヘッダーファイルを組み込む前に、LZ4_DISABLE_DEPRECATE_WARNINGSを定義します。

    • LZ4_FORCE_SW_BITCOUNT: 既定では、圧縮アルゴリズムはビットカウント命令を使って長さを求めようとします。この命令は、多くのCPUで高速な単一命令として実装されています。対象CPUが対応しない場合、コンパイラーの組み込み関数が動作しない場合、または性能が悪い場合は、代わりに最適化したソフトウェア処理を使えます。このビルドマクロを設定して実現します。ほとんどの場合、必要になるとは考えられませんが、一般的でないプラットフォームでは検討する妥当な理由があります。

    • LZ4_ALIGN_TEST: 圧縮状態として使うために引数で渡したメモリ領域が、適切にアラインされていることを、アラインメントテストで確認します。テストが不安定だと分かった場合は、値を0に設定して無効にできます。

    • LZ4_USER_MEMORY_FUNCTIONS: <stdlib.h>のmalloc()、calloc()、free()の呼び出しを、利用者定義の関数に置き換えます。関数名はLZ4_malloc()、LZ4_calloc()、LZ4_free()でなければなりません。利用者の関数は、リンク時に利用可能でなければなりません。

    • LZ4_STATIC_LINKING_ONLY_DISABLE_MEMORY_ALLOCATION: 動的メモリ確保のサポートを取り除きます。詳しくは、lib/lz4.cにある、このマクロの説明を参照してください。

    • LZ4_STATIC_LINKING_ONLY_ENDIANNESS_INDEPENDENT_OUTPUT: 異なるエンディアン（リトルエンディアンとビッグエンディアン）のプラットフォームで、同じ圧縮出力を生成するための実験的機能です。リトルエンディアンの出力は変わらず、ビッグエンディアンではリトルエンディアンと同じ出力を生成するようになります。後方互換性と前方互換性には、いかなる影響もないと見込まれています。

    • LZ4_FREESTANDING: このビルドマクロを1に設定すると、LZ4/HCはC標準ライブラリへの依存関係を取り除きます。メモリ確保関数と、memmove()、memcpy()、memset()も対象です。組み込み環境、ブートローダーなど、制限のある環境でLZ4/HCを使いやすくするためのマクロです。詳しくは、lib/lz4.hにある、このマクロの説明を参照してください。

    • LZ4_HEAPMODE: LZ4_compress_default()などの状態を持たない圧縮関数が、ハッシュテーブルのメモリを確保する方法を選びます。スタック（0: 既定、最速）か、ヒープ（1: malloc()が必要）です。

    • LZ4HC_HEAPMODE: LZ4_compress_HC()などの状態を持たないHC圧縮関数が、作業領域のメモリを確保する方法を選びます。スタック（0）か、ヒープ（1: 既定）です。作業領域はかなり大きく、スタックでは不便な場合があるため、ヒープモードを推奨します。

    • LZ4F_HEAPMODE: LZ4F_compressFrame()が圧縮状態を確保する方法を、スタック（既定、値0）か、ヒープメモリ（値1）から選びます。

    Makefile変数

    次のMakefile変数を選び、生成するバイナリーの構成を変更できます。

    • BUILD_SHARED: liblz4動的ライブラリを生成します（既定で有効）。
    • BUILD_STATIC: liblz4静的ライブラリを生成します（既定で有効）。

    単一ファイルへの統合

    lz4のソースコードは、単一ファイルに統合できます。次のコマンドで、すべてのソースコードをlz4_all.cにまとめられます。

    cat lz4.c lz4hc.c lz4frame.c > lz4_all.c

    （catのファイル順序が重要です。）その後、lz4_all.cをコンパイルします。lz4_all.cのコンパイルには、/lib内のすべての*.hファイルが引き続き必要です。

    Windows: MinGW+MSYSでDLLを作る

    MinGW+MSYSでmake liblz4コマンドを使い、DLLを作れます。このコマンドは、dll\liblz4.dllと、インポートライブラリdll\liblz4.libを生成します。Linux上でクロスコンパイルするときにdlltoolコマンドを変更するには、DLLTOOL変数を設定するだけです。Linux上でmingw-w64の64ビット向けにクロスコンパイルする例:

    make BUILD_STATIC=no CC=x86_64-w64-mingw32-gcc DLLTOOL=x86_64-w64-mingw32-dlltool OS=Windows_NT

    インポートライブラリが必要なのは、Visual C++の場合だけです。gcc/MinGWでプロジェクトをコンパイルするには、ヘッダーファイルlz4.h、lz4hc.h、lz4frame.hと、動的ライブラリdll\liblz4.dllが必要です。動的ライブラリはリンクオプションに追加しなければなりません。つまり、LZ4を使うプロジェクトが単一のtest-dll.cファイルからなる場合は、dll\liblz4.dllとリンクすべきです。例:

        $(CC) $(CFLAGS) -Iinclude/ test-dll.c -o test-dll dll\liblz4.dll

    コンパイルした実行可能ファイルには、dll\liblz4.dllにあるLZ4 DLLが必要です。

    その他

    ディレクトリ内のその他のファイルは、ソースコードではありません。次のファイルです。

    • LICENSE: BSDライセンスの本文を含みます。
    • Makefile: lz4ライブラリ（静的・動的）をコンパイル・インストールするmakeスクリプト。
    • liblz4.pc.in: pkg-config用です（make installで使います）。
    • README.md: このファイルです。

    ライセンス

    lib ディレクトリ内のすべてのソース素材は、BSD 2-Clauseライセンスです。詳しくはLICENSEを参照してください。各ソースファイルの先頭にもライセンスを記載しています。