Skip to content

Commit ea08759

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 Caruntu <[email protected]>
1 parent 3c8ca01 commit ea08759

File tree

12 files changed

+419
-0
lines changed

12 files changed

+419
-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: 303 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,303 @@
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+
This results in the creation of the `workdir/build/` directory storing the build artifacts.
110+
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`).
111+
112+
### Use a Different Compiler
113+
114+
If you want to use a different compiler, such as a Clang or a different GCC version, pass the `CC` variable to `make`.
115+
116+
To build with Clang, use the commands below:
117+
118+
```console
119+
make properclean
120+
make CC=clang -j $(nproc)
121+
```
122+
123+
Note that Clang >= 14 is required to build Unikraft.
124+
125+
To build with another GCC version, use the commands below:
126+
127+
```console
128+
make properclean
129+
make CC=gcc-<version> -j $(nproc)
130+
```
131+
132+
where `<version>` is the GCC version, such as `11`, `12`.
133+
134+
Note that GCC >= 8 is required to build Unikraft.
135+
136+
### Build the Filesystem
137+
138+
The filesystem is to be packed into `initrd.cpio`, an initial ramdisk CPIO file.
139+
Use the command below for that:
140+
141+
```console
142+
rm -f initrd.cpio
143+
./workdir/unikraft/support/scripts/mkcpio initrd.cpio ./rootfs/
144+
```
145+
146+
## Run
147+
148+
Run the resulting image using the corresponding platform tool.
149+
Firecracker requires KVM support.
150+
Xen requires a system with Xen installed.
151+
152+
A successful run will show a message such as the one below:
153+
154+
```text
155+
en1: Added
156+
en1: Interface is up
157+
Powered by
158+
o. .o _ _ __ _
159+
Oo Oo ___ (_) | __ __ __ _ ' _) :_
160+
oO oO ' _ `| | |/ / _)' _` | |_| _)
161+
oOo oOO| | | | | (| | | (_) | _) :_
162+
OoOoO ._, ._:_:_,\_._, .__,_:_, \___)
163+
Calypso 0.17.0~5d38d108
164+
```
165+
166+
This means that Lua runs on Unikraft and waiting for connections.
167+
168+
### Run on QEMU/x86_64
169+
170+
To set up networking, use the command below:
171+
172+
```console
173+
qemu-system-x86_64 \
174+
-nographic \
175+
-m 32 \
176+
-cpu max \
177+
-kernel workdir/build/lua_qemu-x86_64 \
178+
-append "lua_qemu-x86_64 vfs.fstab=[\"initrd0:/:extract::ramfs=1:\"] -- /helloworld.lua" \
179+
-initrd ./initrd.cpio
180+
```
181+
182+
### Run on QEMU/ARM64
183+
184+
To set up networking, use the command below:
185+
186+
```console
187+
qemu-system-aarch64 \
188+
-machine virt \
189+
-nographic \
190+
-m 128 \
191+
-cpu max \
192+
-kernel workdir/build/lua_qemu-arm64 \
193+
-append "lua_qemu-arm64 vfs.fstab=[\"initrd0:/:extract::ramfs=1:\\"] -- /helloworld.lua" \
194+
-initrd ./initrd.cpio
195+
```
196+
197+
### Run on Firecracker/x86_64
198+
199+
To set up networking, use the command below:
200+
201+
```console
202+
rm -f firecracker.socket
203+
firecracker-x86_64 --config-file fc.x86_64.json --api-sock firecracker.socket
204+
```
205+
206+
### Run on Firecracker/ARM64
207+
208+
To set up networking, use the command below:
209+
210+
```console
211+
rm -f firecracker.socket
212+
firecracker-aarch64 --config-file fc.arm64.json --api-sock firecracker.socket
213+
```
214+
215+
### Run on Xen/x86_64
216+
217+
To set up networking, use the command below:
218+
219+
```console
220+
sudo xl create -c xen.x86_64.cfg
221+
```
222+
223+
You need use `sudo` or the `root` account to run Xen.
224+
225+
### Run on Xen/ARM64
226+
227+
To set up networking, use the commands below:
228+
229+
```console
230+
sudo xl create -c xen.arm64.cfg
231+
```
232+
233+
You need use `sudo` or the `root` account to run Xen.
234+
235+
## Close
236+
237+
As an application, the Lua unikernel will run until you close the virtual machine running it. Closing depends on the platform:
238+
239+
### Close QEMU
240+
241+
To close the QEMU VM, press:
242+
243+
```text
244+
Ctrl+a x
245+
```
246+
247+
—that is, hold `Ctrl`+`a`, then press `x`.
248+
249+
### Close Firecracker
250+
251+
In another console, run:
252+
253+
```console
254+
sudo pkill -f firecracker
255+
```
256+
257+
### Close Xen
258+
259+
In another console, run:
260+
261+
```console
262+
sudo xl destroy lua
263+
```
264+
265+
## Clean Up
266+
267+
To remove build artifacts only:
268+
269+
```console
270+
make clean
271+
```
272+
273+
To remove fetched files and the entire `workdir/build/` directory:
274+
275+
```console
276+
make properclean
277+
```
278+
279+
To remove the generated `.config` file as well:
280+
281+
```console
282+
make distclean
283+
```
284+
285+
## Customize
286+
287+
### Customize the Filesystem Contents
288+
289+
The Lua example’s filesystem is under `rootfs/`; you can update scripts or add files here:
290+
291+
```text
292+
rootfs/
293+
└── helloworld.lua
294+
```
295+
296+
After modifying `rootfs/`, rebuild just the filesystem:
297+
298+
```console
299+
rm -f initrd.cpio
300+
./workdir/unikraft/support/scripts/mkcpio initrd.cpio ./rootfs/
301+
```
302+
303+
No unikernel rebuild is needed.

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

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

0 commit comments

Comments
 (0)