![CI](https://github.com/ImNotAVirus/lzma_ex/actions/workflows/ci.yml/badge.svg)
[![Documentation](http://img.shields.io/badge/hex.pm-docs-green.svg?style=flat)](https://hexdocs.pm/lzma)
[![Package](https://img.shields.io/hexpm/v/lzma.svg)](https://hex.pm/packages/lzma)

<!-- MDOC -->

# LZMA

LZMA compression library for Elixir.

## Installation

Add `lzma` to your list of dependencies in `mix.exs`:

```elixir
def deps do
  [
    {:lzma, "~> 0.1"}
  ]
end
```

LZMA will download a precompiled version of its native code upon installation. You can force a local build by setting the environment variable `LZMA_EX_BUILD=1` and including `:rustler` as a dependency:

```elixir
  {:lzma, "~> 0.1", system_env: %{"LZMA_EX_BUILD" => "1"}},
  {:rustler, ">= 0.0.0"}
```

If necessary, clean up before rebuilding with `mix deps.clean lzma`.

## Usage

### XZ Format

```elixir
# Compress data
{:ok, compressed} = LZMA.xz_compress("Hello World")

# Decompress data
{:ok, original} = LZMA.xz_decompress(compressed)

# Bang versions (raise on error)
compressed = LZMA.xz_compress!("Hello World")
original = LZMA.xz_decompress!(compressed)
```

### LZMA Format

```elixir
# Compress data
{:ok, compressed} = LZMA.lzma_compress("Hello World")

# Decompress data
{:ok, original} = LZMA.lzma_decompress(compressed)

# Bang versions
compressed = LZMA.lzma_compress!("Hello World")
original = LZMA.lzma_decompress!(compressed)
```

### LZMA2 Format

```elixir
# Compress data
{:ok, compressed} = LZMA.lzma2_compress("Hello World")

# Decompress data
{:ok, original} = LZMA.lzma2_decompress(compressed)

# Bang versions
compressed = LZMA.lzma2_compress!("Hello World")
original = LZMA.lzma2_decompress!(compressed)
```

### Working with Binary Data

```elixir
# Compress binary data
binary_data = File.read!("large_file.txt")
{:ok, compressed} = LZMA.xz_compress(binary_data)

# Save compressed data
File.write!("large_file.txt.xz", compressed)

# Decompress later
compressed = File.read!("large_file.txt.xz")
{:ok, original} = LZMA.xz_decompress(compressed)
```

## Precompilation

LZMA ships with the NIF code precompiled for the most popular architectures out there.
We support the following:

- `aarch64-apple-darwin` - MacOS running on ARM 64 bits CPUs.
- `aarch64-unknown-linux-gnu` - Linux running on ARM 64 bits CPUs, compiled with GCC.
- `aarch64-unknown-linux-musl` - Linux running on ARM 64 bits CPUs, compiled with Musl.
- `x86_64-apple-darwin` - MacOS running on Intel/AMD 64 bits CPUs.
- `x86_64-pc-windows-msvc` - Windows running on Intel/AMD 64 bits CPUs, compiled with Visual C++.
- `x86_64-pc-windows-gnu` - Windows running on Intel/AMD 64 bits CPUs, compiled with GCC.
- `x86_64-unknown-linux-gnu` - Linux running on Intel/AMD 64 bits CPUs, compiled with GCC.
- `x86_64-unknown-linux-musl` - Linux running on Intel/AMD 64 bits CPUs, compiled with Musl.
- `x86_64-unknown-freebsd` - FreeBSD running on Intel/AMD 64 bits.

This means that LZMA is going to work without the need to compile it from source.

This currently **only works for Hex releases**. For more information on how it works, please
check the [RustlerPrecompiled project](https://hexdocs.pm/rustler_precompiled).

## Development

### Building Locally

```bash
# Install dependencies
mix deps.get

# Force local build
LZMA_EX_BUILD=1 mix compile

# Run tests
mix test

# Run all checks
mix ci.check
```

## License

MIT License - See [LICENSE](LICENSE) for details.