_This article is a work-in-progress._ # Building ## Prerequisites ToaruOS's build system is not a professional, portable build system. You will need an environment very similar to the one I use myself in order to run the tools. I recommend the latest LTS release of Ubuntu as this is likely to be what I'm currently running. The scripts will attempt to get things working on some other Linux platforms. You should also be able to use Bash on Ubuntu on Windows (WSL). ## Get things set up You will need `git` to check out the repository (some magic in the build tools may not function properly if you build from an archive - it is always recommended that you use a git checkout), and `make` to run most of the tools. As ToaruOS currently depends on Python, and Python requires you to have a local installation of the same version to cross-compile that version, you will need to **install Python 3.6** on your host. You can build it from source, or install it from a package if available. At some point, we may make building a local Python 3.6 (if it is not already available) part of the toolchain build, but that is not the case as of this writing. Additionally, the build tools assume your shell is bash. If you use Zsh or some other shell, please run a bash shell while building the OS. ## Build the Toolchain 1. To install the toolchain: make toolchain This will attempt to install several packages necessary for the toolchain and then provide instructions for continuing. You should follow those instructions if they differ from what is listed below. The toolchain build will take several minutes - possibly an hour, depending on your hardware. It will retrieve many archives of third-party software such as GCC, Binutils, and a handful of libraries used by the OS. It also builds gcc and binutils twice (for two different targets) and cross compiles all of the libraries, and this can take quite some time. 2. Activate the toolchain. Note that the space is significant - you are not running this script, you are sourcing it. . toolchain/activate.sh 3. Build the kernel and a first pass at the userspace. make 4. Install Python and pycairo. toolchain/install-python.sh toolchain/install-pycairo.sh 5. Rebuild the disk image. make clean-disk; make ## Trouble-shooting the toolchain 1. **"Your genext2fs does not support the -B (--block-size) argument."** You need a patched version of this tool, `genext2fs`. This patch ships by default in Debian, but has not reached other distributions. This software package is no longer maintained and the patch did not make it into a released version, so you will need to build the _current CVS HEAD_, not a release tarball. 2. **Python did not install and says that `python3.6` is missing. Can I skip installing Python?** You need to install a local build of Python 3.6 on your host. Python is required for the OS to function as several core applications were written in Python or ported from C versions. Python is a key part of the modern ToaruOS experience. ## Building CDs instead Once you have a functioning toolchain, you can also build CDs. You need to clone the repository into a new directory, have your original toolchain activated, rebuild Python and Pycairo in the new checkout, and run `make cdrom`. GRUB and xorriso are required to build CDs. # Running ToaruOS From the development environment, you can run `make run` to launch a QEMU virtual machine. You can also run `make virtualbox` which will build a bootstrap CD and launch VirtualBox. If you have built a CD, `make run` will run the CD instead of using a hard disk. For VirtualBox, use `make virtualbox-cdrom`. ## Virtual Machine Configurations VirtualBox is the best-supported virtual machine for running ToaruOS (providing guest display and mouse integration, as well as full support for audio and networking), but QEMU provides better network performance in NAT modes (with mouse integration available through a new driver). VMWare is not officially supported, but progress is being made to ensure that it works and to improve functionality of the OS within both Player and Workstation. ### QEMU Many different settings for QEMU are supported. KVM is recommended (`-M accel=kvm`), 1GB or more of RAM is preferred (`-m 1G`). You may choose between several network chipsets: `-net nic,model=rtl8139 -net user` or `model=pcnet` or `model=e1000` - by default, QEMU will use the `e1000` chipset unless you specify a network config option at which point QEMU will not provide a network card unless you specify one; note that the emulation for the `e1000` chipset makes it the slowest option under KVM. For graphics, `-vga std` is preferred as it supports arbitrary widths, but `-vga vmware` is also supported (it needs to round to even widths). For audio, `-soundhw pcspk,ac97` will provide full support. Consider passing `-rtc base=localtime` so that the RTC time is your local time (ToaruOS does not support timezones at the moment), and `-serial stdio` to make the serial logging functionality available. When using QEMU with ToaruOS 1.0.4 or later, the VMware absolute mouse device is enabled by default. To toggle to relative pointer mode (useful when playing games), a widget applet is provided on the panel . The recommended configuration for best results is: qemu-system-i386 -m 1G -M accel=kvm -cdrom toaruos.iso -soundhw pcspk,ac97 -net nic,model=rtl8139 -net user -rtc base=localtime ### VirtualBox VirtualBox should be configured with the default settings for the OS type "Unknown/Other" and a recommended 1GB or more of RAM. Both of the "AMD PCNet" and all three "Intel PRO/1000" series network cards should function - the AMD PCNet FAST III is selected by default in this configuration. VirtualBox's guest display and mouse integration support is enabled by default - you should disable mouse integration from the VM menu if you need a relative mouse pointer, eg. when playing games. ### VMWare Player / Workstation Support for VMWare is limited and currently being worked on in 1.0.4. If you are using an earlier release (1.0.3 or older), disable the ATA/ATAPI DMA driver from the "Configure optional modules" menu in GRUB. The optimal configuration for VMWare can be obtained by selecting "Other (64-bit)" as the guest OS type. While ToaruOS is 32-bit only, this configuration selects particular network hardware which should function in the OS in 1.0.4 or newer. Audio support is not currently available in VMWare as it does not provide an ICH AC'97 audio chipset option (we are working on a driver for the Ensoniq ES1371 provided by VMWare). Please also ensure that you provide the VM with 1GB of RAM, as it will default to 256MB and this is insufficient for installing packages. As with QEMU, the VMware absolute mouse device is enabled by default. To toggle to relative pointer mode (useful when playing games), a widget applet is provided on the panel . Note that support for the VMWare absolute mouse is still experimental, and there are known issues in certain configurations when using it with VMWare, such as the mouse not being in the right place if the host window is moved. If you are manually configuring VMWare, enable the `e1000` network card - the default PCNet card does not function with ToaruOS's PCNet driver.