doc/vlunnr.1.scd

   1 VLUNNR(1) "" "VL Runner for Cargo"
   2
   3 # NAME
   4
   5 vlunnr - build and run disk images via Qemu
   6
   7 # SYNOPSIS
   8
   9 *vlunnr run* <_TARGET_>++
  10 *vlunnr build* <_DIR_> <_IMG_>
  11
  12 # FILES
  13
  14 *vlunnr.cfg*++
  15 *.cargo/config.toml*
  16
  17 # CONFIGURATION
  18
  19 Configuration is done via *vlunnr.cfg*(5) in the working directory of the
  20 *vlunnr* process. *vlunnr.cfg*(5) is written in TOML.
  21
  22 You will also need to ensure *cargo*(1) will use *vlunnr* for the target runner.
  23 In the file *.cargo/config.toml*, for the *target* table, there is a *runner*
  24 key, which can be used to specify a command string as the runner for the built
  25 target (or all of them if no *cfg* is specified for the target).
  26
  27 # DESCRIPTION
  28
  29 *vlunnr* is used to build and run disk images for a free standing, Limine-booted
  30 program (AKA, a kernel) through *cargo*(1). The images are typically booted via
  31 *qemu*(1), but the exact program specification must be configured via
  32 *vlunnr.cfg*(5).
  33
  34 *cargo*(1) can be used to automatically run built kernel images via *cargo r* or
  35 *cargo test* with *vlunnr*, and *vlunnr* can automatically determine if the
  36 build target was a test or not.
  37
  38 *vlunnr* generated files are placed within a temporary directory, and may be
  39 copied to a specified path in *vlunnr.cfg*(5).
  40
  41 # OPTIONS
  42
  43 *vlunnr* <_--help_|_-h_|_-?_>++
  44         Prints a help message and the current version of *vlunnr* and exits
  45         successfully.
  46
  47 *vlunnr* <_--version_|_-v_>++
  48         Prints the version string and exits successfully.
  49
  50 *vlunnr* <_--license_|_--copyright_>++
  51         Prints the licensing/copyright information of *vlunnr* and exits
  52         successfully.
  53
  54 # EXAMPLES
  55
  56 *vlunnr run* _target/x86_64-unknown-none/kernel_++
  57         Will place the file at _target/x86_64-unknown-none/kernel_ into a disk
  58         image, and boot the image with *qemu*(1).
  59
  60 *vlunnr build* _mnt_ _boot.img_++
  61         Will place the contents of directory _mnt_ into an EFI System Partition
  62         (_ESP_) within _boot.img_
  63
  64 # SEE ALSO
  65
  66 *cargo*(1), *qemu*(1), *vlunnr.cfg*(5)
  67
  68 # BUGS
  69
  70 To report bugs, send an email to _Ayzee Patton <vlpatton@vlpatton.gay>_
  71 including relevant information. See _<https://git.vlpatton.gay/?p=vlunner.git>_
  72 for more information.
  73
  74 # AUTHORS
  75
  76 *vlunnr* and *vlunnr.cfg*(5) syntax are maintained by _Ayzee Patton
  77 <vlpatton@vlpatton.gay>_. You may find sources at
  78 _<https://git.vlpatton.gay/?p=vlunner.git>_.