AuroraMiddleware/zstd
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Improved documentation

Browse Source
This commit is contained in:
Carl Woffenden 2020-04-07 13:19:52 +02:00
parent a93fadfcd9
commit 59812afac7
1 changed files with 20 additions and 13 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

33
contrib/single_file_decoder/README.md
View File

@ -1,26 +1,33 @@
# Single File Zstandard Decompression Library
# Single File Zstandard Libraries
The script `combine.sh` creates an _amalgamated_ source file that can be used with or without `zstd.h`. This isn't a _header-only_ file but it does offer a similar level of simplicity when integrating into a project.
All it now takes to support Zstd in your own projects is the addition of a single file, two if using the header, with no configuration or further build steps.
Decompressor
------------
This is the most common use case. The decompression library is small, adding, for example, 26kB to an Emscripten compiled WebAssembly project. Native implementations add a little more, 40-70kB depending on the compiler and platform.
Create `zstddeclib.c` from the Zstd source using:
```
cd zstd/contrib/single_file_decoder
cd zstd/contrib/single_file_libs
./combine.sh -r ../../lib -r ../../lib/common -r ../../lib/decompress -o zstddeclib.c zstddeclib-in.c
```
Then add the resulting file to your project (see the [example files](examples)).
`create_single_file_decoder.sh` will run the above script, creating file `zstddeclib.c`.
`build_decoder_test.sh` will create the decoder, then compile and test the library.
`create_single_file_decoder.sh` will run the above script, creating the file `zstddeclib.c` (`build_decoder_test.sh` will also create `zstddeclib.c`, then compile and test the result).
Why?
----
Full Library
------------
Because all it now takes to support decompressing Zstd is the addition of a single file, two if using the header, with no configuration or further build steps. The library is small, adding, for example, 26kB to an Emscripten compiled WebAssembly project. Native implementations add a little more, 40-70kB depending on the compiler and platform.
The same tool can amalgamate the entire Zstd library for ease of adding both compression and decompression to a project. The [roundtrip example](examples/roundtrip.c) uses the original `zstd.h` with the remaining source files combined into `zstd.c` (currently just over 1MB) created from `zstd-in.c`. As with the standalone decoder the most useful compile flags have already been rolled-in and the resulting file can be added to a project as-is.
Optional Full Library
---------------------
Create `zstd.c` from the Zstd source using:
```
cd zstd/contrib/single_file_libs
combine.sh -r ../../lib -r ../../lib/common -r ../../lib/compress -r ../../lib/decompress -k zstd.h -o zstd.c zstd-in.c
```
It's possible to create a compressor-only library but since the decompressor is so small in comparison this doesn't bring much of a gain (but for the curious, simply remove the files in the _decompress_ section at the end of `zstd-in.c`).
The same tool can amalgamate the entire Zstd library for ease of adding both compression and decompression to a project. The [roundtrip example](examples/roundtrip.c) uses the original `zstd.h` with the remaining source files combined into `zstd.c` (currently just over 1MB) created from `zstd-in.c`. As with the standalone decoder the most useful compile flags have already been rolled-in and the resulting files can be added to a project as-is.
`create_single_file_library.sh` will run the script to create `zstd.c`.
`build_library_test.sh` will create the library, then compile and test the result.
`create_single_file_library.sh` will run the script to create `zstd.c` (`build_library_test.sh` will also create `zstd.c`, then compile and test the result).