Skip to content

tutorial

Jump to bottom
parke edited this page Jan 6, 2022 · 62 revisions

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.

Alpine Linux - build a Lua package

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 non-root, but with sudo access. 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 - install our newly built Lua package

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. Full write access is necessary (obviously) to install packages.
    • --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 is likely, but not certainly, a safe assumption.
    • 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 - build Lua

Introduction

  • Let's build Lua for Arch Linux.

Commands

$  vland  --arch-build  arch
$  vland  arch  -n  --  asp  lua
$  vland  arch  -n  cd TODO  --  TODO
$  vland  arch  --  ls  -lh  TODO
$  vland  arch  --  pacman  -U  TODO
$  vland  arch  --  lua  --version

Commentary

  • TODO

Arch Linux - build Chromium

Introduction

  • Let's build Chromium for Arch Linux.

Commands

TODO

Commentary

  • TODO
Clone this wiki locally