Skip to content

Commit 40d2d9c

Browse files
Dana-Maria04Dana-Maria04
committed
Introduce Lua 5.4 application
Add Lua 5.4 application Add `lua/` directory: - `Config.uk`: application configuration - `Makefile`: for building the application - `Makefile.uk`: empty placeholder required by the build system - `README.md`: instructions - `setup.sh`: script to initialize and populate the root filesystem - `rootfs/helloworld.lua`: the Lua Hello program - `fc.x86_64.json` / `fc.arm64.json`: Firecracker configurations for x86_64 and ARM64 - `xen.x86_64.cfg` / `xen.arm64.cfg`: Xen configurations for x86_64 and ARM64 - `.gitignore`: ignore generated files Signed-off-by: Dana Caruntu <caruntudana@yahoo.com>
1 parent 3c8ca01 commit 40d2d9c

File tree

12 files changed

+400
-0
lines changed

12 files changed

+400
-0
lines changed

‎lua/.gitignore‎

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

‎lua/Config.uk‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
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+
12+
# Select the application’s main function entrypoint (Lua interpreter)
13+
select LIBLUA_MAIN_FUNCTION
14+
15+
# Select filesystem core components:
16+
# vfscore + automount, CPIO support, ramfs, devfs.
17+
# These provide an in-memory filesystem and device nodes.
18+
select LIBVFSCORE
19+
select LIBVFSCORE_AUTOMOUNT_UP
20+
select LIBUKCPIO
21+
select LIBRAMFS
22+
select LIBDEVFS
23+
select LIBDEVFS_AUTOMOUNT
24+
select LIBDEVFS_DEVSTDOUT
25+
26+
# Select POSIX environment support for getenv/putenv.
27+
select LIBPOSIX_ENVIRON
28+
29+
# Use library-parameter parsing for environment variables.
30+
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: 276 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,276 @@
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 the commands below:
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+
test -d ./rootfs/ || docker build -o ./rootfs -f Dockerfile .
27+
test -f initrd.cpio || ./workdir/unikraft/support/scripts/mkcpio initrd.cpio ./rootfs/
28+
./workdir/unikraft/support/scripts/mkcpio initrd.cpio ./rootfs/
29+
qemu-system-x86_64 \
30+
-nographic \
31+
-m 32 \
32+
-cpu max \
33+
-kernel workdir/build/lua_qemu-x86_64 \
34+
-append "lua_qemu-x86_64 vfs.fstab=[\"initrd0:/:extract::ramfs=1:\"] -- /helloworld.lua" \
35+
-initrd ./initrd.cpio
36+
```
37+
38+
This will configure, build and run the Helloworld Lua app, printing "Hello, World!".
39+
40+
To do the same for AArch64, run:
41+
42+
```console
43+
make distclean
44+
wget -O /tmp/defconfig \
45+
https://raw.githubusercontent.com/unikraft/catalog-core/refs/heads/scripts/lua/scripts/defconfig/qemu.arm64
46+
UK_DEFCONFIG=/tmp/defconfig make defconfig
47+
make -j $(nproc)
48+
test -d ./rootfs/ || docker build -o ./rootfs -f Dockerfile .
49+
test -f initrd.cpio || ./workdir/unikraft/support/scripts/mkcpio initrd.cpio ./rootfs/
50+
qemu-system-aarch64 \
51+
-machine virt \
52+
-nographic \
53+
-m 128 \
54+
-cpu max \
55+
-kernel workdir/build/lua_qemu-arm64 \
56+
-append "lua_qemu-arm64 vfs.fstab=[\"initrd0:/:extract::ramfs=1:\\"] -- /helloworld.lua" \
57+
-initrd ./initrd.cpio
58+
```
59+
60+
Similar to the x86_64 build, this will print "Hello, World!" on ARM64.
61+
62+
Information about every step and other build types is detailed below.
63+
64+
## Set Up
65+
66+
Set up the required repositories.
67+
You have two options:
68+
69+
Use the setup.sh script:
70+
71+
```console
72+
./setup.sh
73+
```
74+
75+
It will clone/link `lib-lua` and any other needed libs under `repos/libs/.`
76+
77+
Manual setup:
78+
79+
```console
80+
test -d repos/libs/lua || \
81+
git clone https://github.com/unikraft/lib-lua repos/libs/lua
82+
```
83+
84+
## Clean
85+
86+
While not strictly required, it is safest to clean previous build artifacts:
87+
88+
```console
89+
make distclean
90+
```
91+
92+
## Configure
93+
94+
To configure the kernel, use:
95+
96+
```console
97+
make menuconfig
98+
```
99+
100+
Select the Architecture (`x86_64` or `ARM64`), then platform (`QEMU`, `Firecracker`, `Xen`), and save to produce the `.config` file.
101+
102+
## Build
103+
104+
Build the application for the current configuration:
105+
106+
```console
107+
make -j $(nproc)
108+
```
109+
110+
This results in the creation of the `workdir/build/` directory storing the build artifacts.
111+
112+
This produces the unikernel at `workdir/build/lua_<plat>-<arch>`, where `<plat>` is the platform name (`qemu`, `fc`, `xen`), and `<arch>` is the architecture (`x86_64` or `arm64`).
113+
114+
### Use a Different Compiler
115+
116+
If you want to use a different compiler, such as a Clang or a different GCC version, pass the `CC` variable to `make`.
117+
118+
To build with Clang, use the commands below:
119+
120+
```console
121+
make properclean
122+
make CC=clang -j $(nproc)
123+
```
124+
125+
Note that Clang >= 14 is required to build Unikraft.
126+
127+
To build with another GCC version, use the commands below:
128+
129+
```console
130+
make properclean
131+
make CC=gcc-<version> -j $(nproc)
132+
```
133+
134+
where `<version>` is the GCC version, such as `11`, `12`.
135+
136+
Note that GCC >= 8 is required to build Unikraft.
137+
138+
### Build the Filesystem
139+
140+
The filesystem is to be packed into `initrd.cpio`, an initial ramdisk CPIO file.
141+
Use the command below for that:
142+
143+
```console
144+
rm -f initrd.cpio
145+
./workdir/unikraft/support/scripts/mkcpio initrd.cpio ./rootfs/
146+
```
147+
148+
## Run
149+
150+
Run the resulting image using the corresponding platform tool.
151+
Firecracker requires KVM support.
152+
Xen requires a system with Xen installed.
153+
154+
A successful run will show a message such as the one below:
155+
156+
```text
157+
en1: Added
158+
en1: Interface is up
159+
Powered by
160+
o. .o _ _ __ _
161+
Oo Oo ___ (_) | __ __ __ _ ' _) :_
162+
oO oO ' _ `| | |/ / _)' _` | |_| _)
163+
oOo oOO| | | | | (| | | (_) | _) :_
164+
OoOoO ._, ._:_:_,\_._, .__,_:_, \___)
165+
Calypso 0.17.0~5d38d108
166+
```
167+
168+
This means that Lua runs on Unikraft and waiting for connections.
169+
170+
### Run on QEMU/x86_64
171+
172+
To set up networking, use the command below:
173+
174+
```console
175+
qemu-system-x86_64 \
176+
-nographic \
177+
-m 32 \
178+
-cpu max \
179+
-kernel workdir/build/lua_qemu-x86_64 \
180+
-append "lua_qemu-x86_64 vfs.fstab=[\"initrd0:/:extract::ramfs=1:\"] -- /helloworld.lua" \
181+
-initrd ./initrd.cpio
182+
```
183+
184+
### Run on QEMU/ARM64
185+
186+
To set up networking, use the command below:
187+
188+
```console
189+
qemu-system-aarch64 \
190+
-machine virt \
191+
-nographic \
192+
-m 128 \
193+
-cpu max \
194+
-kernel workdir/build/lua_qemu-arm64 \
195+
-append "lua_qemu-arm64 vfs.fstab=[\"initrd0:/:extract::ramfs=1:\\"] -- /helloworld.lua" \
196+
-initrd ./initrd.cpio
197+
```
198+
199+
### Run on Firecracker/x86_64
200+
201+
To set up networking, use the command below:
202+
203+
```console
204+
rm -f firecracker.socket
205+
firecracker-x86_64 --config-file fc.x86_64.json --api-sock firecracker.socket
206+
```
207+
208+
### Run on Firecracker/ARM64
209+
210+
To set up networking, use the command below:
211+
212+
```console
213+
rm -f firecracker.socket
214+
firecracker-aarch64 --config-file fc.arm64.json --api-sock firecracker.socket
215+
```
216+
217+
### Run on Xen/x86_64
218+
219+
To set up networking, use the command below:
220+
221+
```console
222+
sudo xl create -c xen.x86_64.cfg
223+
```
224+
225+
You need use `sudo` or the `root` account to run Xen.
226+
227+
### Run on Xen/ARM64
228+
229+
To set up networking, use the commands below:
230+
231+
```console
232+
sudo xl create -c xen.arm64.cfg
233+
```
234+
235+
You need use `sudo` or the `root` account to run Xen.
236+
237+
## Clean Up
238+
239+
To remove build artifacts only:
240+
241+
```console
242+
make clean
243+
```
244+
245+
To remove fetched files and the entire `workdir/build/` directory:
246+
247+
```console
248+
make properclean
249+
```
250+
251+
To remove the generated `.config` file as well:
252+
253+
```console
254+
make distclean
255+
```
256+
257+
## Customize
258+
259+
### Customize the Filesystem Contents
260+
261+
The Lua example’s filesystem is under `rootfs/`.
262+
You can update scripts or add files here:
263+
264+
```text
265+
rootfs/
266+
`-- helloworld.lua
267+
```
268+
269+
After modifying `rootfs/`, rebuild just the filesystem:
270+
271+
```console
272+
rm -f initrd.cpio
273+
./workdir/unikraft/support/scripts/mkcpio initrd.cpio ./rootfs/
274+
```
275+
276+
No unikernel rebuild is needed.

‎lua/fc.arm64.json‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
{
2+
"boot-source": {
3+
"kernel_image_path": "workdir/build/lua_fc-arm64",
4+
"boot_args": "lua_fc-arm64 vfs.fstab=[ \"initrd0:/:extract::ramfs=1:\" ] -- /helloworld.lua",
5+
"initrd_path": "initrd.cpio"
6+
},
7+
"drives": [],
8+
"machine-config": {
9+
"vcpu_count": 1,
10+
"mem_size_mib": 8,
11+
"smt": false,
12+
"track_dirty_pages": false
13+
}
14+
}

‎lua/fc.x86_64.json‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
{
2+
"boot-source": {
3+
"kernel_image_path": "workdir/build/lua_fc-x86_64",
4+
"boot_args": "lua_fc-x86_64 vfs.fstab=[ \"initrd0:/:extract::ramfs=1:\" ] -- /helloworld.lua",
5+
"initrd_path": "initrd.cpio"
6+
},
7+
"drives": [],
8+
"machine-config": {
9+
"vcpu_count": 1,
10+
"mem_size_mib": 8,
11+
"smt": false,
12+
"track_dirty_pages": false
13+
}
14+
}

‎lua/rootfs/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)