Skip to content

tutorial

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

Alpine Linux package management

vland can install and build Alpine Linux packages, as follows:

Commands

./vland  --alpine-pkg-install        overlay  [guest]  [-- package ...]
./vland  --alpine-pkg-build          overlay  [guest]  [-- package ...]
./vland  --alpine-pkg-build-install  overlay  [guest]  [-- package ...]

In each of the above commands:

  • If guest is not specified, then the overlay's default guest will be used.
  • If the overlay and/or guest do not exist, then they will be created.
  • If the operation is a build operation, then the overlay and guest will be configured for building packages.
  • Zero or more packages may be specified.
  • If you specify a build operation with zero packages, then the overlay and guest will still be configured for building packages. This can be convenient if you wish to build packages manually.
  • If one or more packages are specified, then the specified packages will be built and/or installed as described in the following table of operations.
Operation Action
--alpine-pkg-install Install the specified packages on the specified guest.
--alpine-pkg-build Build the specified packages on the specified overlay and guest.
--alpine-pkg-build-install Build and then install the specified packages on the specified overlay and guest.

Additional notes, just fyi:

  • Installing packages will make changes to the guest, but not (at least typically) to the overlay.
  • Building packages will make changes to the overlay, as packages are built in $HOME/vland-build.
  • Building packages will also make changes to the guest if any build-time dependencies need to be installed.

Arch Linux package management

vland can install and build Arch Linux packages, as follows:

Commands

./vland  --arch-pkg-install        overlay  [guest]  [-- package ...]
./vland  --arch-pkg-build          overlay  [guest]  [-- package ...]
./vland  --arch-pkg-build-install  overlay  [guest]  [-- package ...]
./vland  --arch-aur-build          overlay  [guest]  [-- package ...]
./vland  --arch-aur-build-install  overlay  [guest]  [-- package ...]

In each of the above commands:

  • If guest is not specified, then the overlay's default guest will be used.
  • If the overlay and/or guest do not exist, then they will be created.
  • If the operation is a build operation, then the overlay and guest will be configured for building packages.
  • Zero or more packages may be specified.
  • If you specify a build operation with zero packages, then the overlay and guest will still be configured for building packages. This can be convenient if you wish to build packages manually.
  • If one or more packages are specified, then the specified packages will be built and/or installed as described in the following table of operations.
Operation Action
--arch-pkg-install Install the specified packages on the specified overlay (and guest).
--arch-pkg-build Build the specified packages on the specified overlay (and guest).
--arch-pkg-build-install Build and then install the specified packages on the specified overlay (and guest).
--arch-aur-build Build the specified AUR packages on the specified overlay (and guest).
--arch-aur-build-install Build and then install the specified AUR packages on the specified overlay (and guest).

Additional notes, just fyi:

  • Installing packages will make changes to the guest, but not (at least typically) to the overlay.
  • Building packages will make changes to the overlay, as packages are built in $HOME/vland-build.
  • Building packages will also make changes to the guest if any build-time dependencies need to be installed.
Clone this wiki locally