Merge branch 'unikraft:scripts' into scripts

Author: NDragos

.gitignore

@@ -38,3 +38,7 @@ out/
 *.zip
 *.Z
 *.7z
+
+# Test output files
+log.build.*
+log.run.*

README.md

@@ -1,16 +1,18 @@
 # Catalog Core
 
-This is a catalog of applications that are set up, configured, built and run using first principles tools: Make, GCC, Clang, Kconfig, QEMU, Firecracker, Xen.
+This is a catalog of Unikraft applications that are set up, configured, built and run using first principles tools: Make, GCC, Clang, Kconfig, QEMU, Firecracker, Xen.
 Each directory belongs to a given application and it typically consists of source code, `Makefile`, `Makefile.uk`, filesystem and a `README.md` file with instructions.
 
-This catalog is targeted towards core developers (i.e. developers of [`unikraft` core repository](https://github.com/unikraft/unikraft) or [library repositories](https://github.com/search?q=topic%3Alibrary+org%3Aunikraft&type=Repositories)), maintainers, testers and those who want to learn about the [internals of Unikraft](https://unikraft.org/docs/internals).
+This catalog is targeted towards Unikraft core developers (i.e. developers of [`unikraft` core repository](https://github.com/unikraft/unikraft) or [library repositories](https://github.com/search?q=topic%3Alibrary+org%3Aunikraft&type=Repositories)), maintainers, testers and those who want to learn about the [internals of Unikraft](https://unikraft.org/docs/internals).
 Application and tooling developers and general users should use the [official `catalog` repository](https://github.com/unikraft/catalog).
 
-In order to use this catalog, clone this repository and enter the preferred application directory:
+In order to use this catalog, clone this repository, run the `setup.sh` script and enter the preferred application directory:
 
 ```console
 git clone https://github.com/unikraft/catalog-core
-cd catalog-core/<application-directory>
+cd catalog-core/
+./setup.sh
+cd <application-directory>
 ```
 
 Inside the directory, follow the instructions in the application `README.md`.
@@ -22,40 +24,75 @@ Before and while you are using this catalog, read about the [internals of Unikra
 In order to set up, configure, build and run applications on Unikraft using first principles, the following packages are required:
 
 * `build-essential` / `base-devel` / `@development-tools` (the meta-package that includes `make`, `gcc` and other development-related packages)
+* `g++`
 * `sudo`
 * `flex`
 * `bison`
 * `git`
 * `wget`
+* `curl`
 * `uuid-runtime`
 * `qemu-system-x86`
 * `qemu-system-arm`
 * `qemu-kvm`
 * `sgabios`
 * `gcc-aarch64-linux-gnu`
+* `g++-aarch64-linux-gnu`
+* `bsdcpio`
 
 GCC >= 8 is required to build Unikraft.
 
 On Ubuntu/Debian or other `apt`-based distributions, use the following command to install the requirements:
 
 ```console
+sudo apt -y update
 sudo apt install -y --no-install-recommends \
   build-essential \
   sudo \
   gcc-aarch64-linux-gnu \
+  g++-aarch64-linux-gnu \
   libncurses-dev \
   libyaml-dev \
   flex \
   bison \
   git \
   wget \
+  curl \
   uuid-runtime \
   qemu-kvm \
   qemu-system-x86 \
   qemu-system-arm \
-  sgabios
+  sgabios \
+  libarchive-tools
 ```
 
+### QEMU
+
+For running applications with QEMU bridged networking, use the command below:
+
+```console
+test -d /etc/qemu || sudo mkdir /etc/qemu
+echo "allow all" | sudo tee /etc/qemu/bridge.conf
+```
+
+It enables QEMU bridged networking.
+
+### Docker
+
+Certain applications require [Docker](https://www.docker.com/) to build the application and / or the application filesystem.
+
+To install Docker, follow the [official instructions](https://docs.docker.com/engine/install/).
+Also follow the [post-install instructions](https://docs.docker.com/engine/install/linux-postinstall/).
+The post-install instructions are required to run Docker as a non-root user.
+
+Validate you have a correct Docker installation by running, as an ordinary user (i.e. not `root`):
+
+```console
+docker run hello-world
+```
+
+In case of a correct Docker installation, the above command will print out a longer "Hello, World!"-like message.
+
 ### Clang
 
 Unikraft supports Clang.
@@ -77,7 +114,7 @@ To install Firecracker, use the commands below in a downloads or packages direct
 ```console
 release_url="https://github.com/firecracker-microvm/firecracker/releases"
 latest=v1.7.0
-curl -L ${release_url}/download/${latest}/firecracker-${latest}-${arch}.tgz | tar -xz
+curl -L ${release_url}/download/${latest}/firecracker-${latest}-$(uname -m).tgz | tar -xz
 sudo cp release-${latest}-$(uname -m)/firecracker-${latest}-$(uname -m) /usr/local/bin/firecracker-${latest}-$(uname -m)
 sudo ln -sfn /usr/local/bin/firecracker-${latest}-$(uname -m) /usr/local/bin/firecracker-$(uname -m)
 ```
@@ -104,3 +141,42 @@ On Ubuntu/Debian or other `apt`-based distributions, use the following command t
 ```console
 sudo apt install -y xen-utils
 ```
+
+## Scripted Runs and Testing
+
+To make it easy to quickly build, run and test Unikraft applications, you may use pre-created scripts.
+
+### Scripted Runs
+
+For scripted runs, switch to the `scripts` branch of the repository:
+
+```console
+git checkout -b scripts origin/scripts
+```
+
+Then use the scripts in the `scripts/` directory of each application.
+The build scripts are in the `scripts/build/` directory and the run scripts are in the `scripts/run/` directory.
+
+See instructions in the `scripts/README.md` file about running scripts.
+As noted in `scripts/README.md` file, scripts are run from the application directory.
+
+### Testing
+
+To test applications, switch to the `test` branch of the repository:
+
+```console
+git checkout -b test origin/test
+```
+
+Test all applications by running:
+
+```console
+./test.overall.sh
+```
+
+To test individual applications, navigate to each application directory and run the scripts in the `scripts/test/` directory.
+
+Build and run logs from running tests are stored in the `scripts/test/log/` directory.
+
+See instructions in the `scripts/test/README.md` file about running scripts.
+As noted in the `scripts/test/README.md` file, scripts are run from the application directory.

c-fs/.gitignore

@@ -0,0 +1 @@
+/workdir/

c-fs/Config.uk

@@ -0,0 +1,13 @@
+# Configure C application that prints file contents.
+# This is useful to understand and test filesystem support in Unikraft.
+# Enable initrd / CPIO-related core components and configurations.
+
+config APPCFS
+bool "Configure C filesystem application with initrd as rootfs"
+default y
+
+	# Select filesystem core components: vfscore, cpio, ramfs.
+	select LIBVFSCORE
+	select LIBVFSCORE_AUTOMOUNT_UP
+	select LIBRAMFS
+	select LIBUKCPIO

c-fs/Makefile

@@ -0,0 +1,13 @@
+UK_ROOT ?= $(PWD)/workdir/unikraft
+UK_BUILD ?= $(PWD)/workdir/build
+UK_APP ?= $(PWD)
+LIBS_BASE = $(PWD)/workdir/libs
+UK_LIBS ?=
+
+.PHONY: all
+
+all:
+	@$(MAKE) -C $(UK_ROOT) L=$(UK_LIBS) A=$(UK_APP) O=$(UK_BUILD)
+
+$(MAKECMDGOALS):
+	@$(MAKE) -C $(UK_ROOT) L=$(UK_LIBS) A=$(UK_APP) O=$(UK_BUILD) $(MAKECMDGOALS)

c-fs/Makefile.uk

@@ -0,0 +1,3 @@
+$(eval $(call addlib,appcfs))
+
+APPCFS_SRCS-y += $(APPCFS_BASE)/cat.c