Skip to content

tutorial

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

vland tutorials

Basic usage

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/.local/vland and may write 1.5GB of files inside $HOME/.local/vland.
  • If you wish to use a different location, please create a symlink at $HOME/.local/vland that points to the desired location.

Commands

$  ./vland  --self-test

vland also has a second, larger self test (that uses 3GB to 5GB of disk space), that you may run as follows:

$  ./vland  --self-test-full

Commentary for ./vland --self-test

  • vland --self-test will attempt to do the following:
    • Create an Alpine guest named vland-self-test/alpine.
    • Create an Arch guest named vland-self-test/arch.
    • Install the zsh package in vland-self-test/alpine.
    • Build and install the lua5.4 package in vland-self-test/alpine.
    • Install the zsh package in vland-self-test/arch.
    • Build and install the lua package in vland-self-test/arch.
    • Build and install the jed-snapshot AUR package in vland-self-test/arch.
    • vland --self-test may take two minutes or more to complete.
    • vland --self-test is expected to to use about 1.5GB of disk space.

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. The output will end with something like the below:

/=========================================================\
|                                                         |
|            ./vland --self-test  results                 |
|                                                         |
\=========================================================/

+  vland vland-self-test/alpine -- zsh --version
zsh 5.8 (x86_64-alpine-linux-musl)

+  vland vland-self-test/alpine -- lua5.4 -v
Lua 5.4.3  Copyright (C) 1994-2021 Lua.org, PUC-Rio

+  vland vland-self-test/arch -- zsh --version
zsh 5.8 (x86_64-pc-linux-gnu)

+  vland vland-self-test/arch -- lua -v
Lua 5.4.3  Copyright (C) 1994-2021 Lua.org, PUC-Rio

+  vland vland-self-test/arch -- jed --version
jed version: pre0.99.20-158/Unix

/=========================================================\
|                                                         |
|            ./vland --self-test  done                    |
|                                                         |
\=========================================================/

Commentary for ./vland --self-test-full

  • vland --self-test-full will attempt to do the following:
    • First, run vland --self-test.
    • Then, create four guests, as follows:
      • An Alpine guest named vland-self-test/alpine-full
      • An Arch guest named vland-self-test/arch-full
      • An Void guest named vland-self-test/void-full
      • An Void (musl) guest named vland-self-test/void-musl-full
    • vland --self-test-full will run vland --self-test inside each of the above four guests.
      • This will create two nested guests inside each of the above four guests.
    • vland --self-test-full may take 10 or more minutes to complete.
    • vland --self-test-full is expected to use 3GB to 5GB of disk space.
    • vland --self-test-full will delete each guest upon successful completion of each self-test in order to use less disk space.

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

Introduction

  • Tutorial 3 continues from the end of tutorial 1.
  • We will create Arch Linux guest userland named arch.
  • Aside: An overlay named arch will also be created.

Commands

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

Commentary

  • Line 1 creates a guest named arch.
  • Line 1 also installs Arch Linux in the arch guest.
  • Typically, the guest will be created at $HOME/.local/vland/guest/arch.
  • Typically, the overlay will be created at $HOME/.local/vland/overlay/arch.
  • Fyi, the full syntax of --create is: vland --create distro [guest] [overlay]
  • If lxroot and/or aria2c are not installed on the host, then vland will automatically download and use static builds of each.
  • Line 2 runs an interactive shell inside the guest.
  • Lines 3-7 run various commands inside the guest.

Tutorial 4 - Install the Chromium browser inside the guest

Introduction

  • Tutorial 4 continues from the end of tutorial 3.
  • We will install the Chromium browser inside the guest.

Commands

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

Alternatively, you could could use the --pkg operation to install chromium as follows:

$  ./vland  --pkg  arch  install  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.
  • As you can see, using --pkg may be simpler than running pacman directly.

Tutorial 5 - Run Chromium inside the guest

Introduction

  • Tutorial 5 continues from the end of tutorial 4.
  • We will run Chromium inside the guest.

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.
  • Because -x is specified, vland will copy $HOME/.Xauthority into the 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.
  • This tutorial is incomplete, as I have not yet published my aria2c build script. Feel free to open an issue requesting that I publish it.

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 guest
    • 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.

Package management

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  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
build-clean remove non-essential build-time files

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
$  ./vland  alpine-guest  --  zsh  --version
$  ./vland  alpine_guest  --  lua5.4  -v

Commentary

  • Line 1 creates an Apline guest named alpine-guest.
  • Line 2 downloads and installs the pre-built zsh package in alpine-guest.
  • Line 3 builds and installs the lua5.4 package in alpine-guest.
  • Line 4 verifies that zsh installed successfully.
  • Line 5 verifies that lua5.4 installed successfully.
  • The same commands should would for an Arch guest. Note that in Arch, the Lua 5.4 package is currently 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  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
build-clean remove non-essential build-time files

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
$  ./vland  arch-guest  --  jed  --version

Commentary

  • Line 1 creates an Arch guest named arch-guest.
  • Line 2 builds and installs the AUR jed-snapshot package.
  • Line 3 verifies that jed installed successfully.
Clone this wiki locally