tutorial_20220107 - parke/vland GitHub Wiki

vland tutorials

Tutorial 1 - Install vland

Introduction

  • Tutorial 1 shows how to install vland.
  • vland is a Dash shell script.
  • At present, vland only supports x86_64 Linux systems.

Commands

$  wget     https://github.com/parke/vland/raw/main/vland
$  chmod    +x  ./vland
$  ./vland  --help

Commentary

  • Line 1 downloads the vland shell script.
  • Line 2 makes the script executable.
  • Line 3 prints out vland's help message.
  • Optional: You may copy vland into your PATH, if you wish.

Tutorial 2 - Run ./vland --self-test

Introduction

  • Tutorial 2 continues from the end of tutorial 1.
  • vland contains a built-in self-test.
  • Tutorial 2 is optional. Feel free to skip ahead to tutorial 3.
  • However, if vland seems to be having problems, you may wish to run the self-test, as described below.
  • The self-test will create the directory "$HOME/vland" and will write 901MB of files inside "$HOME/vland".

Commands

$  ./vland  --self-test

Commentary

vland's self test will attempt to do the following:

  • Install Alpine Linux into a userland named vland-self-test.
  • Install vland itself inside vland-self-test.
  • Run vland inside vland-self-test to install a nested Arch Linux userland inside the vland-self-test userland.
  • Then finally run ...
    • ... (on your host) a child vland process to run:
    • ... (in vland-self-test) a grandchild vland process to run:
    • ... (in the nested Arch userland) an interactive (simulated root) shell.

If vland's self test fails, please consider submitting a bug report on Github.

If the self-test works, you should see a bunch of output, and then, after (probably) 30 to 120 seconds, something like the below:



----------------------------------------------------------------
  vland  --self-test  now launching interactive root shell ...  
----------------------------------------------------------------


+  /bin/sh /home/user/vland vland-self-test -n -- vland arch -nr
+  exec lxroot /home/user/vland/land/vland-self-test /home/user/vland/over/vland-self-test -n -- vland arch -nr
+  exec /home/user/vland/dist/bin/lxroot-x86 /home/user/vland/land/arch /home/user/vland/over/arch -nr

root  -nr  ./arch  ~

Tutorial 3 - Use vland to install an Arch Linux guest userland

Introduction

  • Tutorial 3 continues from the end of tutorial 1.

Commands

$  ./vland  --create  arch
$  ./vland  arch  -nr
  #  pwd
  #  id
  #  cat    /etc/issue
  #  uname  -a
  #  exit

Commentary

  • Line 1 creates a userland named arch.
  • Line 1 also installs Arch Linux in the arch userland.
  • Typically, the userland will be created at $HOME/vland/land/arch.
  • Fyi, the full syntax of --create is: vland --create distro [userland] [overlay]
  • If lxroot and/or aria2c are not installed on the host, then vland will automatically download and use static builds of each.

Tutorial 4 - Install the Chromium browser inside the guest

Introduction

  • Tutorial 4 continues from the end of tutorial 3.

Commands

$  ./vland  arch  -nr  --  pacman  -Syu  chromium

Commentary

  • ./vland arch tells vland to run a command inside the arch guest
  • -n grants network access
  • -r simulates uid = 0 (root)
  • -- precedes the command
  • The command pacman -Syu chromium will be run inside the arch guest.

Tutorial 5 - Run Chromium inside the guest

Introduction

  • Tutorial 5 continues from the end of tutorial 4.

Commands

$  ./vland  arch  -nx  --  chromium

Commentary

  • ./vland arch tells vland to run a command inside the arch guest
  • -n grants network access
  • -x grants the guest access to the host's Xorg server
  • -- precedes the command
  • The command chromium will be run inside the arch guest.

Tutorial 6 - create a static build of aria2c

Introduction

  • For certain downloads, vland uses the aria2c download utility.
  • If aria2c is not installed on the host system, vland will download a static bulid of aria2c.
  • Tutorial 11 shows how I use vland to create a static build of aria2c.

Commands

$  wget     TODO
$  /bin/sh  aria2c-static.sh  --run
$  ls  -lh

Commentary

  • Line 1 downloads my aria2c-static.sh script.
  • Line 2 runs my aria2c-static.sh script. This script:
    • installs vland
    • installs a Void Linux userland
    • builds custom versions of key libraries
    • builds a static build of aria2c

See also: Lxroot tutorial

  • vland itself creates and configures guest userlands.
  • However, to actually execute a program inside a guest userland, vland uses a separate tool called Lxroot.
  • You may, if you wish, learn about Lxroot by reading the Lxroot tutorial.

January 2022 note

The below package building tutorials depend on features that are not available in the published version of vland. This is because: I am simultaneously developing the features and writing the below tutorials. Soon, I hope to publish an updated version of vland.

Alpine Linux - Lua - build

Introduction

  • Let's build a Lua package for Alpine Linux.
  • Lua is a compact, yet very flexible dynamic programming language.

Commands

$  ./vland  --alpine-build  alpine-guest
$  ./vland  alpine-guest  -nw  cd aports/main/lua5.4  --  abuild  -r
$  ./vland  alpine-guest  --  ls  -lh   packages/main/x86_64

Commentary

  • Line 1 will, if a guest named alpine-guest does not exist:
    • create a guest named alpine-guest, and then
    • install Alpine Linux in alpine-guest.
  • Line 1 will also configure alpine-guest for building Alpine packages.
  • Line 2 will build the lua5.4 package inside alpine-guest.
    • -n grants network access, thereby allowing the downloading of any needed build-time dependencies.
    • -w grants (non-root) write access to the entire guest, thereby allowing the installation of build-time dependencies.
    • Aside: Alpine's abuild program expects to run as a non-root user. We use -w (and not -r) in order to accommodate abuild's expectations.
    • The options cd aports/main/lua5.4 tell lxroot to chdir() to that directory before executing the specified command. aports/main/lua5.4 is a relative path. Relative paths are relative to $HOME inside the guest.
    • -- precedes the command to execute.
    • The abuild -r command will build both: the Lua package and several supporting packages.
  • Line 3 will list the newly created Lua package files.

Alpine Linux - Lua - install

Introduction

  • Let's install the Lua package we built in the preceding tutorial.
  • This tutorial continues from the end of the preceding tutorial.

Commands

$  ./vland  alpine-guest       --  ls  -lh   packages/main/x86_64
$  ./vland  alpine-guest  -nr  --  apk  --force-non-repository  add  "$HOME"/packages/main/x86_64/lua5.4-5.4.3-r0.apk
$  ./vland  alpine-guest       --  which  lua5.4
$  ./vland  alpine-guest       --  lua5.4  --version

Commentary

  • Line 1 will list the newly created Lua package files.
  • Line 2 will install the newly created lua5.4-5.4.3-r0.apk package.
    • -n grants network access, thereby allowing the downloading of any needed run-time dependencies.
    • -r simulates uid = 0 (root) and grants write access to the entire guest.
    • --force-non-repository is only needed if alpine-guest is located on a non-persistent tmpfs filesystem.
    • $HOME will be evaluated in the host environment. Explanation: (1) We built the package in $HOME in alpine-guest as a non-root user. (2) But we are installing the package as a simulated root user. (3) The simulated root user will almost certainly have a different $HOME. (4) Therefore, when installing the package, we need to specify the full (non-relative) path of the newly built package file.
    • Further note regarding $HOME: This tutorial assumes that your non-root user will have the same $HOME both (a) on the host and (b) as a non-root user inside alpine-guest. This assumption is likely true, but could fail in rare cases.
    • If the lua5.4 package has been updated since this tutorial was written, you may (obviously) need to use the updated filename.
  • Line 3 shows the path of the installed lua5.4 program.
  • Line 4 shows the version of the installed lua5.4 program.

Arch Linux - Lua - build

Introduction

  • Let's build a Lua package for Arch Linux.

Commands

$  ./vland  --arch-build  arch-guest
$  ./vland  arch-guest  -n  --  asp  checkout  lua
$  ./vland  arch-guest  -n  cd lua/trunk  --  makepkg  --clean  --syncdeps  --rmdeps
$  ./vland  arch-guest  --  ls  -lh  lua/trunk

Commentary

  • If a guest named arch-guest does not exist, then line 1 will:
    • create a guest named arch-guest, and then
    • install Arch Linux in arch-guest.
  • Line 1 will also configure arch-guest for building Arch packages.
  • Line 2 downloads the package build instructions.
  • Line 3 will build the package.
    • -clean --syncdeps --rmdeps were included in the source tutorial I used to write this tutorial. They may or may not be necessary. They may or may not cause problems when attempting to build other packages. I suspect that any build-time dependencies for the Lua package were already installed in the guest as a result of line 1. At some point in the future I hope to learn more about installing build-time dependencies when building Arch packages with vland.
  • Line 4 will list the newly built package and other files in the $HOME/lua/trunk directory.

Arch Linux - Lua - install

Introduction

  • Let's install the Lua package we built in the preceding tutorial.
  • This tutorial continues from the end of the preceding tutorial.

Commands

$  ./vland  arch-guest  --  ls  -lh  lua/trunk
$  ./vland  arch-guest  -r  --  pacman  -U  "$HOME"/lua/trunk/lua-5.4.3-1-x86_64.pkg.tar.zst
$  ./vland  arch-guest      --  which  lua
$  ./vland  arch-guest      --  lua  -v

Commentary

  • Line 1 will list the newly created Lua package files.
  • Line 2 will install the newly created lua5.4-5.4.3-r0.apk package.
    • -r simulates uid = 0 (root) and grants write access to the entire guest.
    • We are installing the package as simulated root. Therefore, $HOME (inside the guest) has a different value. Therefore, we specify the full absolute path of the package file.
  • Line 3 shows the path of the installed lua program.
  • Line 4 shows the version of the installed lua program.

Arch Linux - Chromium - build

Introduction

  • Let's build a Chromium package for Arch Linux.
  • Chromium is an open source web browser.

Commands

TODO

Commentary

  • TODO

Arch Linux - Chromium - install

Introduction

  • Let's install the Chromium package we built in the preceding tutorial.
  • This tutorial continues from the end of the preceding tutorial.

Commands

TODO

Commentary

  • TODO