# API

## tarToExt2

Convert a tar archive into an ext2 image written to `output`. The archive is a path or its bytes; gzipped archives are inflated transparently. Resolves with the diagnostics the tool produced.

```ts twoslash
import { tarToExt2 } from "@deroll/genext2fs";

const result = await tarToExt2("rootfs.tar", "rootfs.ext2", {
    blockSize: 4096,
    volumeLabel: "rootfs",
    faketime: true,
});
console.log(result.stderr); // copying from tar archive rootfs.tar
```

The archive can equally be passed as bytes, gzipped or not:

```ts twoslash
import { tarToExt2 } from "@deroll/genext2fs";
import { readFile } from "node:fs/promises";

await tarToExt2(await readFile("rootfs.tar.gz"), "rootfs.ext2", {
    blockSize: 4096,
});
```

## createImage

The general form, for images assembled from more than one source. Layers are applied in order, each optionally at a path inside the image.

```ts twoslash
import { createImage } from "@deroll/genext2fs";

await createImage("rootfs.ext2", {
    blockSize: 4096,
    layers: [
        { type: "tarball", path: "rootfs.tar" },
        { type: "directory", path: "./overlay", target: "/opt" },
        { type: "devtable", path: "./device_table.txt" },
    ],
});
```

| Layer type  | Flag | Meaning                                            |
| ----------- | ---- | -------------------------------------------------- |
| `tarball`   | `-a` | add the contents of an archive                     |
| `directory` | `-d` | add a directory and its contents                   |
| `devtable`  | `-D` | create or fix up inodes from a device table file   |

## Blocking variants

`tarToExt2Sync` and `createImageSync` do the same work on the calling thread.

## No escape hatch

Between [Options](/genext2fs/options) and the layer types, every xgenext2fs flag is covered except `--help` and `--version` — the latter being the exported `version` — so there is no raw-argv entry point to fall back to.

## Errors

Failures reject (or throw) with the tool's own diagnostic, carrying `status`, `stdout` and `stderr`.

```ts twoslash
import { type Genext2fsError, tarToExt2 } from "@deroll/genext2fs";

try {
    await tarToExt2("rootfs.tar", "rootfs.ext2", { sizeInBlocks: 8 });
} catch (e) {
    const error = e as Genext2fsError;
    console.error(error.message); // couldn't allocate a block (no free space)
    console.error(error.stderr); // everything the run printed
}
```

## version

The version of the vendored xgenext2fs the addon was built against.

```ts twoslash
import { version } from "@deroll/genext2fs";

console.log(version); // "1.5.6"
```