Skip to content

tutorial

Jump to bottom
parke edited this page Jan 11, 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.

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.

Install and build packages with ./vland --pkg

  • The ./vland --pkg operation can install and build packages inside a guest.
  • At present, --pkg supports Alpine and Arch guests.

The syntax of --pkg is:

./vland  --pkg  overlay  [guest]  action  [--]  [package ...]

Where action is one of:

update update/sync the guest's package database
install download and install a pre-built package
deps download and install all of `package`'s build dependencies
build build the package
build-install build and install the package

Tutorial: Alpine package management

Introduction

  • In this tutorial will do the following:
    • create an Apline guest named alpine-guest
    • install the zsh package in alpine-guest
    • build and install the lua5.4 package in alpine-guest

Commands

$  ./vland  --create  alpine  alpine-guest
$  ./vland  --pkg  alpine-guest  install  zsh
$  ./vland  --pkg  alpine-guest  build-install  lua5.4

Commentary

  • Line 1 creates an Apline guest named alpine-guest.
  • Line 2 install the pre-built zsh package in alpine-guest.
  • Line 3 builds and installs the lua5.4 package in alpine-guest.
  • The same commands should would for an Arch guest. Note that in Arch, the Lua 5.4 package is named lua.

Build and install Arch AUR packages with ./vland --aur

  • The ./vland --aur operation can build and install packages from Arch's AUR.
  • The --aur operation has the same syntax as the --pkg operation.
  • However, the --aur operation has fewer actions.
  • The --aur operation only works with Arch guests.

The syntax of the --aur operation is:

$  ./vland  --aur  overlay  [guest]  action  [--]  [package ...]

Where action is one of:

deps download and install all of `package`'s build dependencies
build build the package
build-install build and install the package

Tutorial: Arch AUR package management

Introduction

  • In this tutorial, we will do the following:
    • create an Arch guest named arch-guest
    • build and install the jed-snapshot AUR package in arch-guest

Commands

$  ./vland  --create  arch  arch-guest
$  ./vland  --aur  arch-guest  build-install  jed-snapshot

Commentary

  • Line 1 creates an Arch guest named arch-guest.
  • Line 2 builds and install the AUR jed-snapshot package.
Clone this wiki locally