include-fs 0.1.0

Embed folders in your binary
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

# include-fs

`include-fs` allows embedding entire directories into binaries at compile time, similar to how `include_bytes!` and `include_str!` work for single files. The library packages directories into an archive, embeds the archive using `include_bytes!`, and allows accessing the files by path at runtime.

## Usage

### Build Script (`build.rs`)

```rust
fn main() {
  include_fs::embed_fs("src/assets", "assets").unwrap();
}
```

### Runtime Usage

```rust
static ASSETS: IncludeFs = include_fs!("assets");

fn main() {
  let image_exists = ASSETS.exists("assets/image.jpg");
  let config_content = ASSETS.get("assets/config.toml").unwrap();
}
```

## Planned Features

- Improved API with better error messages
- Feature-flagged glob support
- Directory listing

## Archive Format

The archive uses a simple binary format:

### Layout Structure
```
[Header]
[File Data Section - concatenated file contents]
```

### Header Format
```
Magic Number:     4 bytes  (b"INFS")
File Count:       4 bytes  (u32, little-endian)

For each file:
  Path Length:    2 bytes  (u16, little-endian)
  Path:          variable  (UTF-8 string)
  File Size:      8 bytes  (u64, little-endian) 
  Data Offset:    8 bytes  (u64, little-endian)
```

### Design Decisions

- **No compression**: Keeps implementation simple and allows random access
- **No metadata**: Timestamps, permissions, etc. are not stored
- **Little-endian**: Standard for most target platforms
- **Lexicographic sorting**: Files are sorted by path for deterministic builds
- **8-byte sizes/offsets**: Supports files and archives up to 16 exabytes
- **2-byte path length**: Supports paths up to 65,535 bytes