tsiry-sandratraina.com
Simple script and config (type-safe) for building custom Linux kernels for Firecracker MicroVMs
docs: update README to enhance kernel configuration handling and clarify usage instructions
+63
-7
README.md
+63
-7
README.md
···
7
7
## ✨ Features
8
8
9
9
- Builds any stable Linux kernel version (e.g., `6.1`, `6.1.12`, `6.1.y`)
10
+
- Supports multiple architectures (x86_64, aarch64)
11
+
- Enhanced kernel configuration handling with customizable options
10
12
- Uses a custom `.config` for reproducible builds
11
-
- Outputs a ready-to-use `vmlinux-X.Y` file
13
+
- Outputs a ready-to-use `vmlinux-X.Y-[arch]` file
12
14
- Written in TypeScript with Deno for better type safety and cross-platform compatibility
13
15
- Colored output using Chalk for improved readability
14
16
- Easily integrated into CI pipelines (e.g., GitHub Actions)
···
18
20
### System Dependencies
19
21
20
22
Ensure you have the following dependencies installed:
23
+
21
24
```bash
22
25
sudo apt-get install -y git build-essential flex bison libncurses5-dev \
23
26
libssl-dev gcc bc libelf-dev pahole
···
36
39
## 🚀 Usage
37
40
38
41
```bash
42
+
# Build for x86_64 (default)
39
43
deno run -A jsr:@tsiry/vmlinux-builder 6.17.7
40
44
```
41
45
···
46
50
- `6.1.y` - Latest from maintenance branch
47
51
- `v6.1.12` - Version with 'v' prefix (automatically normalized)
48
52
53
+
### Kernel Configuration
54
+
55
+
The tool provides enhanced kernel configuration handling with:
56
+
57
+
- Support for TUN and TUN_VNET_CROSS_LE
58
+
- Various netfilter options enabled
59
+
- Customizable configuration through environment variables
60
+
- Reproducible builds with consistent config options
61
+
49
62
### Example output
50
-
```
51
-
Building vmlinux for Linux kernel 6.16
63
+
64
+
```sh
65
+
Building vmlinux for Linux kernel 6.16 (x86_64)
52
66
vmlinux built successfully!
53
67
You can find the vmlinux file in /path/to/linux-stable/vmlinux-6.16.x86_64
54
68
```
···
58
72
This repo includes a GitHub Actions workflow (`.github/workflows/ci.yml`) that:
59
73
60
74
- Triggers on tag push (e.g. `git tag 6.16.y && git push origin 6.16.y`)
61
-
- Builds the vmlinux for that version
62
-
- Publishes the resulting `vmlinux-X.Y` as a GitHub Release asset
75
+
- Builds the vmlinux for both x86_64 and aarch64 architectures
76
+
- Publishes the resulting `vmlinux-X.Y-[arch]` files as GitHub Release assets
77
+
- Includes SHA256 checksums for all released files
78
+
79
+
## 🧩 Config API Usage
80
+
81
+
The `config.ts` module provides a type-safe API for parsing, validating, extracting, and serializing Linux kernel `.config` files.
63
82
64
-
## 🔧 Development
83
+
### Parse a kernel config file
84
+
85
+
```ts
86
+
import { KernelConfigParser } from '@tsiry/vmlinux-builder';
87
+
const content = await Deno.readTextFile('path/to/.config');
88
+
const config = KernelConfigParser.parse(content);
89
+
```
90
+
91
+
### Extract config categories
92
+
93
+
```ts
94
+
import { KernelConfigParser } from '@tsiry/vmlinux-builder';
95
+
const processor = KernelConfigParser.extractProcessorConfig(config);
96
+
const security = KernelConfigParser.extractSecurityConfig(config);
97
+
const networking = KernelConfigParser.extractNetworkingConfig(config);
98
+
const filesystem = KernelConfigParser.extractFilesystemConfig(config);
99
+
```
100
+
101
+
### Serialize config to different formats
102
+
103
+
```ts
104
+
import { KernelConfigSerializer } from '@tsiry/vmlinux-builder';
105
+
const asConfig = KernelConfigSerializer.toConfig(config); // .config format
106
+
const asJSON = KernelConfigSerializer.toJSON(config);
107
+
const asTOML = KernelConfigSerializer.toTOML(config);
108
+
const asYAML = KernelConfigSerializer.toYAML(config);
109
+
```
110
+
111
+
### Validate a config
112
+
113
+
```ts
114
+
import { validateKernelConfig } from '@tsiry/vmlinux-builder';
115
+
const result = validateKernelConfig(config);
116
+
if (!result.success) {
117
+
throw new Error('Invalid kernel config');
118
+
}
119
+
```
120
+
121
+
See `config.ts` for more advanced usage and options.
65
122
66
123
The script is written in TypeScript and runs on Deno. Key features:
67
124
68
125
- **Type-safe**: Full TypeScript support with type checking
69
-
- **Cross-platform**: Works on Linux, macOS, and Windows (WSL)
70
126
- **Modern**: Uses Deno's native APIs for file operations and process management
71
127
- **Colored output**: Enhanced user experience with Chalk
72
128