summaryrefslogtreecommitdiffstats
path: root/other-licenses/snappy/src/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'other-licenses/snappy/src/README.md')
-rw-r--r--other-licenses/snappy/src/README.md140
1 files changed, 140 insertions, 0 deletions
diff --git a/other-licenses/snappy/src/README.md b/other-licenses/snappy/src/README.md
new file mode 100644
index 0000000000..7917d1bf05
--- /dev/null
+++ b/other-licenses/snappy/src/README.md
@@ -0,0 +1,140 @@
+Snappy, a fast compressor/decompressor.
+
+[![Build Status](https://travis-ci.org/google/snappy.svg?branch=master)](https://travis-ci.org/google/snappy)
+[![Build status](https://ci.appveyor.com/api/projects/status/t9nubcqkwo8rw8yn/branch/master?svg=true)](https://ci.appveyor.com/project/pwnall/leveldb)
+
+Introduction
+============
+
+Snappy is a compression/decompression library. It does not aim for maximum
+compression, or compatibility with any other compression library; instead,
+it aims for very high speeds and reasonable compression. For instance,
+compared to the fastest mode of zlib, Snappy is an order of magnitude faster
+for most inputs, but the resulting compressed files are anywhere from 20% to
+100% bigger. (For more information, see "Performance", below.)
+
+Snappy has the following properties:
+
+ * Fast: Compression speeds at 250 MB/sec and beyond, with no assembler code.
+ See "Performance" below.
+ * Stable: Over the last few years, Snappy has compressed and decompressed
+ petabytes of data in Google's production environment. The Snappy bitstream
+ format is stable and will not change between versions.
+ * Robust: The Snappy decompressor is designed not to crash in the face of
+ corrupted or malicious input.
+ * Free and open source software: Snappy is licensed under a BSD-type license.
+ For more information, see the included COPYING file.
+
+Snappy has previously been called "Zippy" in some Google presentations
+and the like.
+
+
+Performance
+===========
+
+Snappy is intended to be fast. On a single core of a Core i7 processor
+in 64-bit mode, it compresses at about 250 MB/sec or more and decompresses at
+about 500 MB/sec or more. (These numbers are for the slowest inputs in our
+benchmark suite; others are much faster.) In our tests, Snappy usually
+is faster than algorithms in the same class (e.g. LZO, LZF, QuickLZ,
+etc.) while achieving comparable compression ratios.
+
+Typical compression ratios (based on the benchmark suite) are about 1.5-1.7x
+for plain text, about 2-4x for HTML, and of course 1.0x for JPEGs, PNGs and
+other already-compressed data. Similar numbers for zlib in its fastest mode
+are 2.6-2.8x, 3-7x and 1.0x, respectively. More sophisticated algorithms are
+capable of achieving yet higher compression rates, although usually at the
+expense of speed. Of course, compression ratio will vary significantly with
+the input.
+
+Although Snappy should be fairly portable, it is primarily optimized
+for 64-bit x86-compatible processors, and may run slower in other environments.
+In particular:
+
+ - Snappy uses 64-bit operations in several places to process more data at
+ once than would otherwise be possible.
+ - Snappy assumes unaligned 32 and 64-bit loads and stores are cheap.
+ On some platforms, these must be emulated with single-byte loads
+ and stores, which is much slower.
+ - Snappy assumes little-endian throughout, and needs to byte-swap data in
+ several places if running on a big-endian platform.
+
+Experience has shown that even heavily tuned code can be improved.
+Performance optimizations, whether for 64-bit x86 or other platforms,
+are of course most welcome; see "Contact", below.
+
+
+Building
+========
+
+You need the CMake version specified in [CMakeLists.txt](./CMakeLists.txt)
+or later to build:
+
+```bash
+git submodule update --init
+mkdir build
+cd build && cmake ../ && make
+```
+
+Usage
+=====
+
+Note that Snappy, both the implementation and the main interface,
+is written in C++. However, several third-party bindings to other languages
+are available; see the [home page](docs/README.md) for more information.
+Also, if you want to use Snappy from C code, you can use the included C
+bindings in snappy-c.h.
+
+To use Snappy from your own C++ program, include the file "snappy.h" from
+your calling file, and link against the compiled library.
+
+There are many ways to call Snappy, but the simplest possible is
+
+```c++
+snappy::Compress(input.data(), input.size(), &output);
+```
+
+and similarly
+
+```c++
+snappy::Uncompress(input.data(), input.size(), &output);
+```
+
+where "input" and "output" are both instances of std::string.
+
+There are other interfaces that are more flexible in various ways, including
+support for custom (non-array) input sources. See the header file for more
+information.
+
+
+Tests and benchmarks
+====================
+
+When you compile Snappy, the following binaries are compiled in addition to the
+library itself. You do not need them to use the compressor from your own
+library, but they are useful for Snappy development.
+
+* `snappy_benchmark` contains microbenchmarks used to tune compression and
+ decompression performance.
+* `snappy_unittests` contains unit tests, verifying correctness on your machine
+ in various scenarios.
+* `snappy_test_tool` can benchmark Snappy against a few other compression
+ libraries (zlib, LZO, LZF, and QuickLZ), if they were detected at configure
+ time. To benchmark using a given file, give the compression algorithm you want
+ to test Snappy against (e.g. --zlib) and then a list of one or more file names
+ on the command line.
+
+If you want to change or optimize Snappy, please run the tests and benchmarks to
+verify you have not broken anything.
+
+The testdata/ directory contains the files used by the microbenchmarks, which
+should provide a reasonably balanced starting point for benchmarking. (Note that
+baddata[1-3].snappy are not intended as benchmarks; they are used to verify
+correctness in the presence of corrupted data in the unit test.)
+
+
+Contact
+=======
+
+Snappy is distributed through GitHub. For the latest version and other
+information, see https://github.com/google/snappy.