Getting Started

Welcome to the Panix project! This guide is will detail the software necessary to build the Panix kernel and all related software. Fortunately, Panix 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 Panix, and it is usually beginner friendly.

Required Packages

• Python 3
  • PiP 3 (Python Package Manager)
• Docker
• make
• qemu (Optional)
  • qemu-system-i386

That's it! Because Panix 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 Panix contributors and that all software used by all contributors is of the same version and configuration.

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 Panix, 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.

0. Install required packages (and optional packages to run Panix using official methods)
1. 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 (docker login docker.pkg.github.com) and enter your PAT.
2. Clone the Repo (SSH: git clone [email protected]:panix-os/Panix.git HTTPS: https://github.com/panix-os/Panix.git)
3. Update Git Submodules (git submodule update --init)
4. Build kernel (scuba build)
5. Build image (scuba image)
6. Run in Qemu (make run)

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

Distribution

• image: Build the default Panix image
• img: Build a Panix image in .img format
• iso: Build a Panix image in .iso format

Testing

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

Running

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