Skip to content

Getting Started

Jump to bottom
Keeton Feavel edited this page Jan 30, 2022 · 17 revisions

Welcome to the Xyris project! This guide is will detail the software necessary to build the Xyris kernel and all related software. Fortunately, Xyris has a lot of work put into the build system which should make it easier to work with than other projects.

While it it recommended that a Linux system is used, macOS is also viable. Unfortunately Windows is not officially supported, though it should be possible to get working. If you are new to Linux and development on Linux, it is recommended that you use Virtual Machine software, like VMWare Player or VMWare Fusion, to run Ubuntu. Both version of VMWare have free, non-commercial licenses available. While some may disagree with the decision to recommend Ubuntu, it has all of the packages needed to work on Xyris, and it is usually beginner friendly.

Required Packages

  • Python 3
    • PiP 3 (Python Package Manager)
  • Docker (Instructions here for Ubuntu)
  • scons
  • qemu
    • qemu-system-i386

That's it! Because Xyris uses Docker, very few packages need to be installed on the host system. This helps ensure that all software being used for compilation is managed by the Xyris contributors and that all software used by all contributors is of the same version and configuration. As of version 3.3.1 of the xyris-build Docker image, ARM platforms are supported and will no longer require x86(_64) emulation.

Once Python 3 is installed along with PiP 3, install the scuba package. Scuba is an easy to use Docker image wrapper that allows for easy to use compilation commands.

Details on Scuba are available on its Github page.

Contributing (Quick Start)

If you plan on contributing to Xyris, please fork the repository so you can open Merge Requests. Once forked, replace the URLs in the following steps with the URL to the appropriate fork.

  1. Install required packages (and optional packages to run Xyris using official methods)
  2. Create a PAT for Docker, as described here. Following these steps allows scuba to access Github's Docker registry.
    • Create a new PAT (Personal Access Token) here.
    • Copy the generated PAT token.
    • Login to the Github registry and enter your PAT.
  3. Clone the Repo (SSH: git clone git@github.com:XyrisOS/xyris.git HTTPS: https://github.com/XyrisOS/xyris.git)
  4. Update Git Submodules (git submodule update --init)
  5. Build kernel (scuba build)
  6. Build image (scuba image)
  7. Run in Qemu (scons run-i686)

Scuba Commands

The following scuba commands are available in order to simplify common tasks.

Execute these commands as scuba [command].

Building

  • build: Default build target
  • clean: Remove all build products
  • debug: Build the kernel in debug mode
  • release: Build the kernel in release mode

Documentation

  • docs: Build kernel documentation

Testing

  • test: Build and run the unit tests (no standard output)

Running

The Xyris docker image used by Scuba does not have qemu installed, which is what the Xyris contributors use by default. If scons and qemu-system-x86_64 are both installed, then the scons run-i686 command can be used to launch the Xyris .img image in Qemu. Otherwise, Virtual Machine software such as Virtualbox, VMWare, or Bochs should work, though they are not officially supported.

Additionally, VSCode is the IDE of choice for Xyris development, and as such, there are pre-made tasks for building, testing, and running Xyris.

Copyright the Xyris contributors. All rights reserved.

Clone this wiki locally