### How-to run a mini Slint system provided as a Qemu image ### 

# IMPORTANT: read carefully the instructions below and modify the
# suggested commands as need be before typing the commands

# Please note that these commands have been tested in Linux only.
# Prior to run them from another OS, adaptations are to be done by you.

# This documents explains how to run a mini Slint system already
# installed on a virtual hard disk (or image) using the Qemu emulator.

# In this file all lines beginning with a '#' are explanations, all
# others are commands to be typed at a console or terminal.
# When you are advised to type a command, always remove the leading '#'

# To get help, post your questions on the Slint mailing list. To
# register (mandatory), just send an email to slint-request@ecartis.org
# with as subject or content just the word: subscribe, then follow
# instructions provided in the email sent to you as answer.

# It is possible to mount the image to examine its content, to convert
# it to a format suitable for VirtualBox or VMWare, possibly in another
# OS like Windows or MacOS, and to transfer it to a "real" hard disk,
# cf. OTHER FEATURES at the end of this document. 

## INSTRUCTIONS STEP BY STEP ##

# 1. Download the image and its associated md5 checksum here
# https://slackware.uk/slint/x86_64/slint-14.2.1/minislint/slintmini64-14.2.1.3.raw
# https://slackware.uk/slint/x86_64/slint-14.2.1/minislint/slintmini64-14.2.1.3.raw.md5
# then check the integrity of the downloaded image. We will assume that
# this script and other files have been downloaded in the same
# directory, from which you will run it. Else, adapt the paths in the
# commands presented below.

# 2. Next, enlarge the virtual hard disk with this command, typed as
# regular user:
qemu-resize -f raw  slintmini64-14.2.1.3.raw 20G

# Thgis will increase the size of the hard disk to 20G, which leaves 4G
# available for your data beyond a fill Slint installation. You may
# increase the size if you have enough free space on the same partition. 

# 3. Start the virtual machine.

# The following command set up a Qemu virtual machine including the
# virtual hard disks and starts Slint already installed in it.
# I advise to you create an empty file named minislint.sh, copy and
# paste in this file the multi-lines command below, then execute the
# command typing as regular user:
sh minislint.sh

# Here is the content suggested for minislint.sh:

qemu-system-x86_64 \
-machine q35 \
-enable-kvm \
-cpu host \
-m 2G \
-soundhw hda \
-boot menu=on \
-display gtk \
-vga std \
-drive file=slintmini64-14.2.1.3.raw,format=raw,media=disk

# let's comment these options, that you can modify at will:
# -machine q35 sets the (virtual) machine type
# -enable kvm and -cpu host options allow the virtual machine to run as
#  fast as underlying hardware
# -m 2G indicates the amount of RAM allocated to the virtual machine.
#  Don't make it greater than half the size of the RAM on the host
# -sound hda sets the sound board used
# -display gtk displays the machine in window drawn with GTK
# -vga std sets the display mode

# To know more, type:
qemu-system-x86_64 --help|less

# In the mini Slint, brltty and espeakup ar enabled, so blind users
# will have speech and braille to log in. The machine starts in console
# mode as there is no graphical environment yet. LANG is set to
# en_US.utf8, the keyboard has a 'us' layout, the time zone is
# that of Paris (UTC+1). You will be able to change these settings as
# soon as logged in using the utilities 'localesetup', 'loadkeys' (see
# an example below) and 'clocksetup' respectively.

# Two users are set up in initially:
# 'root' has the password 'privilege'
# 'user' has the password 'noprivilege'
# Initially the keyboard map on the console is us. If you have another
# one, you can change it with the command loadkeys. For instance using
# a French keyboard I would type:
loadkeys fr
# You can make this change permanent typing:
keyboardsetup
# You can modify the user accounts and add new ones with this command:
usersetup

# 4. Enlarge the root (/) partition.

# Initially you will have less than 100M available on the root
# partition /dev/sda1, to make the downloaded image small.

# As soon as logged in as 'root' for the first time, use the command
# fdisk or cfdisk to delete the first and only partition then re-create
# it using all the space allocated to the virtual disk at step 2.

# For instance if using fdisk type:
fdisk/dev/sda
# then at the prompt each key press will be interpreted as a command by
# fdisk as follows
d # to delete /dev/sda1
n # to re-create /dev/sda1
[Enter] # To confirm the proposed type of partition (primary)
[Enter] # To confirm the proposed partition number (1) 
[Enter] # To confirm the proposed first sector of the partition
[Enter] # To confirm the proposed last sector of the new partition
w # To actually write the new partition.

# 5. Before going further, to make the kernel aware of the new layout
# of the partition table layout just type this command:
partprobe /dev/sda

# 6. Now, enlarge the root file system (of tupe ext4) so that it
# occupies all the space # now available in /dev/sda1 with this command:
resize2fs /dev/sda1

# Before you ask: no, deleting then re-creating the partition then
# expand it while Slint is running won't damage the data in it at all,
# under the condition that the old and new partitions begins exactly
# at the same place (at sector number 2048 in our case, the default
# value for both fdisk and cfdisk for the first created partition). 

# 7. Then, update the packages database and get the updated packages (if
# any since the image was built) with these three commands
slapt-get --add-keys
slapt-get -u
slapt-get --upgrade-all
dotnew # To handle possible changes in configuration files

# 8. Now, let's convert the mini Slint in a full-size Slint. Although
# not mandatory, it is highly recommended: this will bring all features.
# Rememeber that initially the system has no graphical environment. 

# 8a. To install all packages coming from Slackware used in Slint, type:
slapt-get --install-set a ap d e k kde l n t tcl x xap xfce y
# This will take a while to download and install several hundreds of
# packages, possibly many hours. A package will actually come from Slint
# if it ships one with the same name but a different content.
# You may exclude 'kde' of the list above if you won't use it, as it is
# heavy. Note that KDE4 is hardly accessible with speech.

# 8b. To install all packages built specifically for Slint type:
slapt-get --install-set slint extra
# This will take a while to downlad and install several hundreds of
# packages, possibly several hours.

# 9. You may now re-configure Slint to your liking. This can be done
# using the utilities provided, mostly borrowed to Salix.

# To decide which services to start at boot, type:
servicesetup
# to re configure the network (which use dhcp initially), type:
netsetup
# To choose how to log in (in graphical or console mode, type:
startupmode

# 1O. Before starting a graphical environment after step 8, yiu need to
# set one of them as default (this can be changed at anytime)

# To do this, log in as 'user' (not as root). Reminder: the initial
# password of 'user' is 'unprivilegied' (don't type the quotes).
# Then type
session-chooser

# 11 To know more, read the docs! As regular user, type:
slint-doc
# The documentation is also available on line at this address:
https://slackware.uk/slint/x86_64/slint-14.2.1/doc/ 

## OTHER FEATURES ##

# We will just list what you can do with the image beyond using it in
# Qemu. To know more type:
qemu-system-x86_64 --help|less
# and read:
https://en.wikibooks.org/wiki/QEMU/Images
https://docs.openstack.org/image-guide/convert-images.html

# 1. Mount the image to examine its content.
# For instance type as root:
mount -o offset=1048576 slintmini64-14.2.1.3.raw
# offset tells to the mount command wher the partition begins, i.e.
# how many bytes after the befgining of the image. 1O48576 is computed
# like this: number of sectors * size of a sector, in this case
# 2048*512=1048576
# Then you can use any file browser to examine the content of the image
# i.e. of the root partition of minislint 

# 2. Convert the image to another format suitable for VirtualBox or
# The image stored in the minislint repository is in the rew Qemu
# format. You can convert the image to several other formats like
# vdi for VirtualBox or vmdk for VMWare using the command
qemu-img convert ...

# 3. Transfer the image to a hard disk:
# cf.:
https://en.wikibooks.org/wiki/QEMU/Images#Copying_an_image_to_a_physical_device

Be aware that you could need to adapt the command line to the real
machine as well as the initrd case occurring.

Have fun!

Didier Spaier
Paris, Sunday 12 January 2020