quickstart.rst
1 Quickstart 2 ========== 3 4 Super Fast Quickstart 5 --------------------- 6 7 Building images with live-wrapper is quite simple. For the impatient: 8 9 .. code-block:: shell 10 11 sudo apt install live-wrapper 12 sudo lwr 13 14 This will build you a file named ``output.iso`` in the current directory 15 containing a minimal live-image. 16 17 .. warning:: 18 19 Currently live-wrapper will create a lot of files and directories in the 20 current working directory. There is a TODO item to move these to a temporary 21 location and clean up afterwards, though this has not yet been fully 22 implemented. You may want to use an empty directory to run ``lwr`` in. 23 24 Customising the Image 25 --------------------- 26 27 There are a number of supported command-line arguments that can be passed to 28 live-wrapper. These change the behaviour to create a customised image. 29 30 Changing the Distribution 31 ~~~~~~~~~~~~~~~~~~~~~~~~~ 32 33 By default, the ISO image will be built using the ``stretch`` distribution. If 34 you'd like to build using ``buster`` or ``sid`` you can pass the ``-d`` 35 parameter to live-wrapper like so: 36 37 .. code-block:: shell 38 39 sudo lwr -d buster 40 41 .. note:: 42 43 You must use the codename, and not the suite (e.g. stable), when specifying 44 the distribution. 45 46 Using an Alternative Mirror 47 ~~~~~~~~~~~~~~~~~~~~~~~~~~~ 48 49 By default, ``vmdebootstrap`` will use the mirror configured in your 50 ``/etc/apt/sources.list``. If you have a faster mirror available, you may want 51 to change the mirror you're using to create the image. You can do this with the 52 ``-m`` parameter: 53 54 .. code-block:: shell 55 56 sudo lwr -m http://localhost/debian/ 57 58 Customising Packages 59 ~~~~~~~~~~~~~~~~~~~~ 60 61 There are two methods of specifying extra packages to be installed into the 62 live image: the ``-t`` and the ``-e`` paramaters. The difference between these 63 two parameters is that the list of tasks given to ``-e`` is passed to 64 ``debootstrap`` for installation as part of the initial root filesystem 65 creation, whereas the packages passed to ``-t`` are installed as part of the 66 ``vmdebootstrap`` hook. 67 68 This essentially means that any packages installed using ``-e`` will *not* have 69 their "Recommends" installed, but will have their "Depends" installed while 70 packages installed using ``-t`` will have both installed making ``-t`` the 71 suitable place for the installation of task packages. 72 73 There is no reason you cannot pass your entire package list to ``-t``, these 74 are seperated mainly to help with the readability of parameters passed to 75 live-wrapper. 76 77 For example: 78 79 .. code-block:: shell 80 81 sudo lwr -e vim -t science-typesetting 82 83 Testing the Image with QEMU 84 --------------------------- 85 86 You can easily test your created live images with QEMU. 87 88 .. warning:: You will need to increase the amount of memory available to 89 QEMU when running the live image. The image will crash if run 90 with the default memory limit. 91 92 To test the image using BIOS boot: 93 94 .. code-block:: shell 95 96 qemu-system-x86_64 -m 2G -cdrom live.iso 97 98 For EFI boot you will need to install the ``ovmf`` package and then run: 99 100 101 .. code-block:: shell 102 103 qemu-system-x86_64 -bios /usr/share/ovmf/OVMF.fd -m 2G -cdrom live.iso 104 105 To test with an emulated USB device, run: 106 107 .. code-block:: shell 108 109 qemu-system-x86_64 -m 2G -usbdevice disk:live.iso 110 111 To test the speech synthesis installer option, you will need to add the 112 following to the QEMU invocation: 113 114 .. code-block:: shell 115 116 -soundhw sb16,es1370,adlib 117 118 .. note:: 119 120 Using -hda to attach the disk image will prevent the installer from detecting 121 the "CD-ROM" as this is not a removable device, it is an emulated attached hard 122 disk drive. 123 124 Next Steps 125 ---------- 126 127 To learn more about using live-wrapper, you can read the man page or check out 128 the :doc:`advanced` section of this documentation.