================================================================
        WELCOME to the Threos OS installation guide!
================================================================

To install the Threos Operating System follow the steps below:

************
* WARNING! *
************
Never copy-and-paste the example commands. Always double-check
the entered command especially the arguments. You can cause
serious data loss with a misspelled command.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES
OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.


----------------------------------------------------------------
 0. ALTERNATE INSTALLATION METHOD
----------------------------------------------------------------

Alternatively, you are free to use the menu-install tool. To
acquire this tool, just install the menu-install package. In
order to use this tool, you might need to adjust the TERM
environment variable.


----------------------------------------------------------------
 1. PRE-INSTALLATION
----------------------------------------------------------------

Select the disk(s) to install on. Populate the disks from the
/dev directory. Also, you can view the partition table of these
disks with the sparted tool.
One can be:

$ sparted /dev/ide0n3 dump

Create MBR and allocate partition(s) on the selected disks.
If the disk does not have an MBR, create one with:

$ sparted /dev/ide0n3 create_mbr

After creating the MBR, arrange the partitions. First, dump
the current partition table and disk info into a file:

$ sparted /dev/ide0n3 dump >/tmp/p

Then edit the file with a text editor. The Threos OS can boot
only from a bootfs, so you must create one (partition type is
0x69). The recommended size is about 20-30 MiB. Note that, you
must leave some space for the bootloader itself. For the root
filesystem we suggest the ext2 filesystem. To create an ext2
partition use the Linux partition type, which is 0x83.
Currently we suggest to use joe:

$ joe /tmp/p

A partition table could be something like this:
 1 simple 0x80 0x69 0x100 0x9f00
 2 simple 0 0x83 0xa000 0x5df350

Then probe your partition table:

$ sparted /dev/ide0n3 dryrun /tmp/p

This will print warnings if the partition table has flaws.
To remove the noise, you can use this as well:

$ sparted /dev/ide0n3 dryrun /tmp/p >/dev/null
[[TODO: the return value shall reflect the correctness]]

If the partition table is correct, write it onto the disk:

$ sparted /dev/ide0n3 write /tmp/p

To format the disks, use the formatfs command. The bootfs
partition shall have about 512KiB reserved space. This parameter
must be passed to the formatfs command. For the example
formatting the partition table would like this:

$ formatfs by-path /dev/ide0n3p1 bootfs 0 0 1024
$ formatfs by-path /dev/ide0n3p2 ext2   1

After formatting the partitions, mount them into the vfs.
Staying at the example partition table above, the mount
commands will be:

$ mkdir /mnt
$ mount /dev/ide0n3p2 /mnt
$ mkdir /mnt/boot
$ mount /dev/ide0n3p1 /mnt/boot

----------------------------------------------------------------
 2. INSTALLATION
----------------------------------------------------------------

Make sure, you have installed the pkman tool, and it is
functional. Also, you need working internet connection.

Use the ih_pkstrap tool to install base packages into the
new system:

$ ih_pkstrap /mnt base base-ext

Enter into the install environment:

$ ih_enter /mnt

In case of "ih_enter" does not work you might try:
- the local /bin/sh exists (and points to a valid shell if
  it is a symlink); if /bin/sh looks corrupted, you can
  remove and replace it to something useful:
  $ cd /bin; rm sh; ln -s barsh
  or
  $ cd /bin; rm sh; ln -s ../run/bin/sh
- ensure the /mnt/bin/ directory exists and has a shell in
  it; if this directory does not contain a shell (must be "sh"
  or "barsh") or any of it is a symlink, but points outside
  of the /mnt directory, you can fix "sh" manually by issuing
  $ cd /mnt/bin; rm sh; ln -s barsh sh
  WARNING: never copy a new shell manually, use the ih_pkstrap
  instead

You can perform other operations now, i.e. installing other
packages, add users, etc.
Now, you have to setup the fstab. You can either use the genfstab
tool (if you installed the "genfstab" package), or write it manually.
In case of the former, issue the following:

$ genfstab ini / >/etc/fstab.ini

In case of the latter, pick a text editor (joe for instance), and
edit the fstab.ini:

$ joe /etc/fstab.ini

According the example above, the entries will be:
"/dev/ide0n3p2  /      ext2    defaults"
"/dev/ide0n3p1  /boot  bootfs  defaults"

After the fstab.ini is set, install the bootloader
resources and generate a Boot Init CPIO. Edit the
bootloader.ini template before copying it to its final
place. It is a good practice to keep the old bootloader.ini
as a backup (note: this is a true backup, the bootloader
may load this file if the "bootloader.ini" is not found
or corrupted):

$ mv /boot/bootloader.ini /boot/bootloader_backup.ini

Consider to change the following parameters:
 - 'timeout'
   This is a delay (in seconds) before the default image
   is loaded. If your system is a final install (the necessity
   of the boot menu is unlikely), then set it to a low
   value, such as "1" or "2".
 - 'arch_param.initmem_div' and 'arch_param.initmem_max'
   For systems with less than 512 MiB RAM should adjust
   these values to force the init memory not more than 64MiB.
   For example: arch_param.initmem_div="8"
   and/or:      arch_param.initmem_max="64M"

$ joe /etc/bootloader/bootloader.ini

After tuning, copy it and generate the boot init CPIO.

$ cp /etc/bootloader/bootloader.ini /boot
$ mkbic -Pvvv

If the "mkbic" above fails, you can generate the boot init
CPIO after quitting the environment. See below.

The last thing to do is to install the bootloader for the new
system. You have to CAREFULLY read and understand the output
of the tool before continue the installation. You must enter
"yes" to continue with the installation.
Issue the following command to perform this:

$ bootldr-install -M -v -p 1 /dev/ide0n3

Where the "-p 1" is the partition number from "/dev/ide0n3p1",
and "/dev/ide0n3" is the entire block device derived from the
same partition device.

Everything is set, sync and exit from the environment:

$ sync
$ exit

If the "mkbic" command above failed, generate it using the
following command:

$ ih_mkbic /mnt -vvv

After every step has successfully completed, unmount the
filesystems:

$ umount -r /mnt

Now, you can reboot your computer to boot Threos.
Enjoy!