magic-embed 0.2.5

Proc-macro to embed a compiled magic database
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110

[![Crates.io Version](https://img.shields.io/crates/v/magic-embed?style=for-the-badge)](https://crates.io/crates/magic-embed)
[![docs.rs](https://img.shields.io/docsrs/magic-embed?style=for-the-badge)](https://docs.rs/magic-embed)

<!-- cargo-rdme start -->

# `magic-embed`: Compile-time Magic Database Embedding

A procedural macro crate for embedding compiled [`pure_magic`](https://crates.io/crates/pure-magic) databases directly into your Rust binary.
This crate provides a convenient way to bundle file type detection rules with your application,
eliminating the need for external rule files at runtime.

## Features

* **Compile-time Embedding**: Magic rule files are compiled and embedded during build
* **Zero Runtime Dependencies**: No need to distribute separate rule files
* **Flexible Configuration**: Include/exclude specific rule files or directories
* **Seamless Integration**: Works with the [`pure_magic`](https://crates.io/crates/pure-magic)

## Installation

Add `magic-embed` to your `Cargo.toml`:

```toml
[dependencies]
magic-embed = "0.1"  # Replace with the latest version
pure-magic = "0.1"     # Required peer dependency
```

## Usage

Apply the `#[magic_embed]` attribute to a struct to embed a compiled magic database:

```rust
use magic_embed::magic_embed;
use pure_magic::MagicDb;

#[magic_embed(include=["../../magic-db/src/magdir"], exclude=["../../magic-db/src/magdir/der"])]
struct MyMagicDb;

fn main() -> Result<(), pure_magic::Error> {
    let db = MyMagicDb::open()?;
    // Use the database as you would with pure_magic
    Ok(())
}
```

## Attributes

| Attribute | Type       | Required | Description |
|-----------|------------|----------|-------------|
| `include` | String[]   | Yes      | Paths to include in the database (files or directories) |
| `exclude` | String[]   | No       | Paths to exclude from the database |

## Complete Example

```rust
use magic_embed::magic_embed;
use pure_magic::MagicDb;
use std::fs::File;
use std::env::current_exe;

#[magic_embed(
    include=["../../magic-db/src/magdir"],
    exclude=["../../magic-db/src/magdir/der"]
)]
struct AppMagicDb;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Open the embedded database
    let db = AppMagicDb::open()?;

    // Use it to detect file types
    let mut file = File::open(current_exe()?)?;
    let magic = db.first_magic(&mut file, None)?;

    println!("Detected: {} (MIME: {})", magic.message(), magic.mime_type());
    Ok(())
}
```

## Build Configuration

To ensure your database is rebuilt when rule files change, create a `build.rs` file:

```rust
// build.rs
fn main() {
    println!("cargo:rerun-if-changed=magic/rules/");
}
```

Replace `magic/rules/` with the path to your actual rule files.

## How It Works

1. **Compile Time**: The macro compiles all specified magic rule files into a binary database
2. **Embedding**: The compiled database is embedded in your binary as a byte array
3. **Runtime**: The `open()` method deserializes the embedded database

## Performance Considerations

- The database is compiled only when source files change
- Embedded databases increase binary size but eliminate runtime file I/O
- Database deserialization happens once at runtime when `open()` is called

## License

This project is licensed under the **GPL-3.0 License**.

<!-- cargo-rdme end -->