Skip to content

Commit c9cd4c7

Browse files
Dana-Maria04Dana-Maria04
committed
Introduce Lua 5.4 application and add .gitignore
- Add `lua/` directory: - `Config.uk`: application configuration with Nginx-style comments - `Makefile`: flatten rules under all/clean/% targets, remove commented lines - `Makefile.uk`: placeholder required by the build system - `README.md`: clean formatting (one sentence per line, inline code, tabs) - `fc.arm64.json`: Firecracker configuration for ARM64 target - Add `.gitignore` for `lua/` directory to: - Ignore workdir/build artifacts - Ignore Kconfig-generated files and editor junk Signed-off-by: Dana-Maria04 <caruntudana@yahoo.com>
1 parent 3c8ca01 commit c9cd4c7

File tree

12 files changed

+400
-0
lines changed

12 files changed

+400
-0
lines changed

‎lua/.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
/rootfs/
2+
/workdir/
3+
initrd.cpio

‎lua/Config.uk‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# Configure Lua Hello example
2+
# A minimal Unikraft unikernel that runs a Lua script.
3+
# Enable core Lua runtime, filesystem and POSIX environment support.
4+
5+
config APPLUA
6+
bool "Lua Hello example"
7+
default y
8+
9+
# Select the core Lua runtime library.
10+
select LIBLUA
11+
# Select the application’s main function entrypoint (Lua interpreter)
12+
select LIBLUA_MAIN_FUNCTION
13+
# Select filesystem core components:
14+
# vfscore + automount, CPIO support, ramfs, devfs.
15+
# These provide an in-memory filesystem and device nodes.
16+
select LIBVFSCORE
17+
select LIBVFSCORE_AUTOMOUNT_UP
18+
select LIBUKCPIO
19+
select LIBRAMFS
20+
select LIBDEVFS
21+
select LIBDEVFS_AUTOMOUNT
22+
select LIBDEVFS_DEVSTDOUT
23+
24+
# Select POSIX environment support for getenv/putenv.
25+
select LIBPOSIX_ENVIRON
26+
# Use library-parameter parsing for environment variables.
27+
select LIBPOSIX_ENVIRON_LIBPARAM

‎lua/Makefile‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
UK_ROOT ?= $(PWD)/../repos/unikraft
2+
UK_BUILD ?= $(PWD)/workdir/build
3+
UK_APP ?= $(PWD)
4+
LIBS_BASE := $(PWD)/../repos/libs
5+
6+
UK_LIBS ?= $(LIBS_BASE)/musl:$(LIBS_BASE)/lua
7+
8+
.PHONY: all clean run
9+
10+
all:
11+
@$(MAKE) -C $(UK_ROOT) L=$(UK_LIBS) A=$(UK_APP) O=$(UK_BUILD)
12+
13+
clean:
14+
@$(MAKE) -C $(UK_ROOT) L=$(UK_LIBS) A=$(UK_APP) O=$(UK_BUILD) properclean
15+
@rm -rf $(UK_BUILD)
16+
17+
%:
18+
@$(MAKE) -C $(UK_ROOT) L=$(UK_LIBS) A=$(UK_APP) O=$(UK_BUILD) $@

‎lua/Makefile.uk‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
$(eval $(call addlib,applua))

‎lua/README.md‎

Lines changed: 286 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,286 @@
1+
# Lua 5.4 on Unikraft
2+
3+
Build and run a Lua 5.4 program on Unikraft.
4+
Follow the instructions below to set up, configure, build and run Lua.
5+
Make sure you installed the [requirements](../README.md#requirements).
6+
7+
## Quick Setup (aka TLDR)
8+
9+
For a quick setup, run the commands below.
10+
Note that you still need to install the [requirements](../README.md#requirements).
11+
Before everything, make sure you run the top-level `setup.sh` script:
12+
13+
```console
14+
./setup.sh
15+
```
16+
17+
To build and run the application for x86_64, use:
18+
19+
```console
20+
./setup.sh
21+
make distclean
22+
wget -O /tmp/defconfig \
23+
https://raw.githubusercontent.com/unikraft/catalog-core/refs/heads/scripts/lua/scripts/defconfig/qemu.x86_64
24+
UK_DEFCONFIG=/tmp/defconfig make defconfig
25+
make -j $(nproc)
26+
./workdir/unikraft/support/scripts/mkcpio initrd.cpio ./rootfs/
27+
qemu-system-x86_64 \
28+
-nographic \
29+
-m 32 \
30+
-cpu max \
31+
-kernel workdir/build/lua_qemu-x86_64 \
32+
-append "lua_qemu-x86_64 vfs.fstab=[\"initrd0:/:extract::ramfs=1:\"] -- /helloworld.lua" \
33+
-initrd ./initrd.cpio
34+
```
35+
36+
This will configure, build and run the Helloworld Lua app, printing “Hello, World!”.
37+
38+
To do the same for AArch64, run:
39+
40+
```console
41+
make distclean
42+
wget -O /tmp/defconfig \
43+
https://raw.githubusercontent.com/unikraft/catalog-core/refs/heads/scripts/lua/scripts/defconfig/qemu.arm64
44+
UK_DEFCONFIG=/tmp/defconfig make defconfig
45+
make -j $(nproc)
46+
qemu-system-aarch64 -nographic -machine virt -m 128 -cpu max \
47+
-kernel workdir/build/lua_fc-arm64
48+
```
49+
50+
Similar to the x86_64 build, this will print “Hello, World!” on ARM64.
51+
52+
Information about every step and other build types is detailed below.
53+
54+
## Set Up
55+
56+
Set up the required repositories.
57+
You have two options:
58+
59+
Use the setup.sh script:
60+
61+
```console
62+
./setup.sh
63+
```
64+
65+
It will clone/link `lib-lua` and any other needed libs under `repos/libs/.`
66+
67+
Manual setup:
68+
69+
```console
70+
test -d repos/libs/lua || \
71+
git clone https://github.com/unikraft/lib-lua repos/libs/lua
72+
```
73+
74+
## Clean
75+
76+
While not strictly required, it is safest to clean previous build artifacts:
77+
78+
```console
79+
make distclean
80+
```
81+
82+
## Configure
83+
84+
To configure the kernel, use:
85+
86+
```console
87+
make menuconfig
88+
```
89+
90+
Select the Architecture (x86_64 or ARM64), then platform (QEMU, Firecracker, Xen), and save to produce the `.config` file.
91+
92+
## Build
93+
94+
Build the application for the current configuration:
95+
96+
```console
97+
make -j $(nproc)
98+
```
99+
100+
This produces the unikernel at `workdir/build/lua_<plat>-<arch>`.
101+
102+
## Run
103+
104+
Run the resulting image using the corresponding platform tool.
105+
106+
### QEMU/x86_64
107+
108+
```console
109+
qemu-system-x86_64 \
110+
-nographic \
111+
-m 32 \
112+
-cpu max \
113+
-kernel workdir/build/lua_qemu-x86_64 \
114+
-append "lua_qemu-x86_64 vfs.fstab=[\"initrd0:/:extract::ramfs=1:\"] -- /helloworld.lua" \
115+
-initrd ./initrd.cpio
116+
```
117+
118+
### QEMU/ARM64
119+
120+
```console
121+
qemu-system-aarch64 \
122+
-machine virt \
123+
-nographic \
124+
-m 128 \
125+
-cpu max \
126+
-kernel workdir/build/lua_qemu-arm64 \
127+
-append "lua_qemu-arm64 vfs.fstab=[\"initrd0:/:extract::ramfs=1:\\"] -- /helloworld.lua" \
128+
-initrd ./initrd.cpio
129+
```
130+
131+
### Firecracker/x86_64
132+
133+
```console
134+
rm -f firecracker.socket
135+
firecracker-x86_64 --config-file fc.x86_64.json --api-sock firecracker.socket
136+
```
137+
138+
### Firecracker/ARM64
139+
140+
```console
141+
rm -f firecracker.socket
142+
firecracker-aarch64 --config-file fc.arm64.json --api-sock firecracker.socket
143+
```
144+
145+
### Xen/x86_64
146+
147+
```console
148+
sudo xl create -c xen.x86_64.cfg
149+
```
150+
151+
### Run on Xen/x86_64
152+
153+
```console
154+
sudo xl create -c xen.x86_64.cfg
155+
```
156+
157+
You need use `sudo` or the `root` account to run Xen.
158+
159+
### Run on Xen/ARM64
160+
161+
```console
162+
sudo xl create -c xen.arm64.cfg
163+
```
164+
165+
You need use `sudo` or the `root` account to run Xen.
166+
## Close
167+
168+
As an application, the Lua unikernel will run until you close the virtual machine running it. Closing depends on the platform:
169+
170+
### Close QEMU
171+
172+
To close the QEMU VM, press:
173+
174+
```text
175+
Ctrl+a x
176+
```
177+
178+
—that is, hold `Ctrl`+`a`, then press `x`.
179+
180+
### Close Firecracker
181+
182+
In another console, run:
183+
184+
```console
185+
sudo pkill -f firecracker
186+
```
187+
188+
### Close Xen
189+
190+
In another console, run:
191+
192+
```console
193+
sudo xl destroy lua
194+
```
195+
196+
## Clean Up
197+
198+
To remove build artifacts only:
199+
200+
```console
201+
make clean
202+
```
203+
204+
To remove fetched files and the entire `workdir/build/` directory:
205+
206+
```console
207+
make properclean
208+
```
209+
210+
To remove the generated `.config` file as well:
211+
212+
```console
213+
make distclean
214+
```
215+
216+
## Customize
217+
218+
### Customize the Filesystem Contents
219+
220+
The Lua example’s filesystem is under `rootfs/`; you can update scripts or add files here:
221+
222+
```text
223+
rootfs/
224+
└── helloworld.lua
225+
```
226+
227+
After modifying `rootfs/`, rebuild just the filesystem:
228+
229+
```console
230+
rm -f initrd.cpio
231+
./workdir/unikraft/support/scripts/mkcpio initrd.cpio ./rootfs/
232+
```
233+
234+
No unikernel rebuild is needed.
235+
236+
### Use a Different Filesystem Type for QEMU (9pfs)
237+
238+
You can mount the filesystem via 9P instead of initrd. First, adjust `lua/Config.uk`:
239+
240+
```text
241+
config APPLUA
242+
bool "Lua Hello example"
243+
default y
244+
245+
select LIBLUA
246+
select LIBLUA_MAIN_FUNCTION
247+
select LIBVFSCORE
248+
select LIBVFSCORE_AUTOMOUNT_UP
249+
select LIBUKCPIO
250+
select LIBRAMFS
251+
select LIBDEVFS
252+
select LIBDEVFS_AUTOMOUNT
253+
select LIBDEVFS_DEVSTDOUT
254+
255+
select LIBPOSIX_ENVIRON
256+
select LIBPOSIX_ENVIRON_LIBPARAM
257+
```
258+
259+
—that is, replace:
260+
261+
```text
262+
select LIBRAMFS
263+
select LIBUKCPIO
264+
```
265+
266+
with the two `9pfs` selects.
267+
268+
Re-run **Configure** and **Build** steps, then after networking is up:
269+
270+
```console
271+
# Copy filesystem for 9pfs
272+
rm -fr 9pfs-rootfs
273+
cp -r rootfs 9pfs-rootfs
274+
275+
sudo qemu-system-x86_64 \
276+
-nographic \
277+
-m 32 \
278+
-cpu max \
279+
-netdev bridge,id=en0,br=virbr0 -device virtio-net-pci,netdev=en0 \
280+
-append "lua_qemu-x86_64 netdev.ip=172.44.0.2/24:172.44.0.1::: vfs.fstab=[\"fs0:/:9pfs:::\" ] -- /helloworld.lua" \
281+
-kernel workdir/build/lua_qemu-x86_64 \
282+
-fsdev local,id=myid,path=$(pwd)/9pfs-rootfs/,security_model=none \
283+
-device virtio-9p-pci,fsdev=myid,mount_tag=fs0
284+
```
285+
286+
For QEMU/ARM64, use a similar command with `qemu-system-aarch64` and `lua_qemu-arm64`.

‎lua/fc.arm64.json‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
{
2+
"boot-source": {
3+
"kernel_image_path": "workdir/build/lua_fc-arm64"
4+
},
5+
"drives": [],
6+
"machine-config": {
7+
"vcpu_count": 1,
8+
"mem_size_mib": 8,
9+
"smt": false,
10+
"track_dirty_pages": false
11+
}
12+
}

‎lua/fc.x86_64.json‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
{
2+
"boot-source": {
3+
"kernel_image_path": "workdir/build/lua_fc-x86_64"
4+
},
5+
"drives": [],
6+
"machine-config": {
7+
"vcpu_count": 1,
8+
"mem_size_mib": 8,
9+
"smt": false,
10+
"track_dirty_pages": false
11+
}
12+
}

‎lua/helloworld.lua‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
print("Hello, World!")

‎lua/setup.sh‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
#!/bin/sh
2+
3+
check_exists_and_create_symlink()
4+
{
5+
path="$1"
6+
7+
if [ ! -d workdir/"$path" ]; then
8+
if [ ! -d ../repos/"$path" ]; then
9+
echo "No directory ../repos/$path. Run the top-level setup.sh script first." >&2
10+
exit 1
11+
fi
12+
13+
depth=$(echo "$path" | awk -F/ '{ print NF }')
14+
if [ "$depth" -eq 1 ]; then
15+
ln -sfn ../../repos/"$path" workdir/"$path"
16+
elif [ "$depth" -eq 2 ]; then
17+
ln -sfn ../../../repos/"$path" workdir/"$path"
18+
else
19+
echo "Unknown depth of path $path." >&2
20+
exit 1
21+
fi
22+
fi
23+
}
24+
25+
test -d workdir || mkdir workdir
26+
test -d workdir/libs || mkdir workdir/libs
27+
28+
check_exists_and_create_symlink "unikraft"
29+
check_exists_and_create_symlink "libs/lua"

0 commit comments

Comments
 (0)