Skip to content

Latest commit

 

History

History
262 lines (218 loc) · 10.9 KB

README.md

File metadata and controls

262 lines (218 loc) · 10.9 KB

LensorOS

A 64-bit all-inclusive operating system, from bootloader to userspace.

Table of Contents

Running LensorOS

Free, compatible virtual machines:

I just want to open LensorOS!

If you are just interested in poking around LensorOS, and not editing code, I recommend a pre-built release from the releases page. It will include all the necessary resources and instructions on how to run LensorOS. Keep in mind that this will be missing a lot of features to ensure maximum compatibility across systems. By building from source, you are able to build for your exact system and get every possible feature enabled.

Launching LensorOS using the Build System

NOTE: There is no automation for anything except QEMU for now. There are, however, instructions on how to setup a virtual machine in VirtualBox and VMWare Workstation Player.

When the CMake build system is generated, it looks for QEMU on your system; if it finds it, it will add the following targets to the project. Invoke them to launch QEMU from the corresponding LensorOS boot media.

The targets:

  • run_qemu -- Straight from directory that mimics LensorOS.img (fastest)
  • runimg_qemu -- LensorOS.img
  • runhda_qemu -- LensorOS.bin
  • runiso_qemu -- LensorOS.iso

Assuming the CMake build system was generated in the kernel/bld/ subdirectory, invoke like:

cmake --build kernel/bld --target <name of target>

VirtualBox

  1. Open VirtualBox.
  2. Click the New button to create a new virtual machine (VM).
  3. Give the VM a name and a file path you are comfortable with.
  4. Select Type of Other and Version of Other/Unknown (64-bit).
  5. Leave the memory size how it is; 64MB is plenty at this time.
  6. Select the Do not add a virtual hard disk option.
  7. Click the Create button to create the new virtual machine.
  8. Select the new VM in the list on the left, then click the Settings button.
  9. Navigate to System within the list on the left.
    1. Change Chipset to ICH9.
    2. Enable Extended Feature Enable EFI (special OSes only).
  10. Navigate to Storage within the list on the left.
    1. Right click the default controller (IDE), and select Remove Controller.
    2. Right click the area labeled Storage Devices, and select AHCI (SATA).
    3. Richt click the new AHCI storage controller, and select either Optical Drive or Hard Disk depending on whether you'd like to boot from the .iso or .bin, respectively.
    4. Click Add in the new Virtual Media Selector window that pops up.
    5. Browse to this folder and, depending on whether Optical Drive or Hard Disk was selected, choose either LensorOS.iso or LensorOS.bin.
  11. Navigate to Network within the list on the left.
    1. Disable all network adapters.

VMWare

  1. Open VMWare Workstation Player
  2. Select Home in the list on the left side. Click Create a New Virtual Machine on the right.
  3. Select the I will install the operating system later. option.
  4. Select a guest OS of Other, and a Version of Other 64-bit.
  5. Give the VM a name and path you are comfortable with. Keep note of the path.
  6. It will ask about a disk, but the disk it's asking about won't be used. Click next.
  7. The next screen should be an overview of the virtual machine hardware. Click Customize Hardware....
    1. Select New CD/DVD on the left, then click Advanced... on the right.
    2. Select SATA, then click OK.
    3. On the right, select Use ISO image file, and then click Browse....
    4. Select the LensorOS.iso image file (located in kernel/bin/).
    5. Select the hard drive that we skipped configuring in the list on the left.
    6. Remove the hard drive using the Remove button near the bottom center.
    7. Remove any and all network adapters and sound cards in the same manner.
    8. Click Close in the bottom right to close the hardware configuration window.
  8. Click Finish.
  9. Navigate to the path specified in step #5, where the virtual machine is located.
    1. Open the file ending with .vmx in a text editor.
    2. Add the following line of text: firmware="efi".
    3. Save the file, then close it.

You will have to select UEFI Shell once VMware Workstation boots into LensorOS (even if it says something like Unsupported).

Building LensorOS

There are multiple steps in the LensorOS build process, outlined here.

  1. Dependencies
  2. Bootloader
  3. LensorOS Toolchain + Kernel
  4. Boot Media Generation

NOTE: All blocks of shell commands given are expected to start with the working directory at the root of the repository.

Dependencies

Download and install the following project-wide dependencies if you don't have them already, or if the version you have isn't up to date.

Next, clone the source code from the repository. If you would like to edit the code and make contributions, be sure to fork first and clone from that repository.

git clone https://github.com/LensPlaysGames/LensorOS.git

This will create a subdirectory titled LensorOS with the contents of this repository in the current working directory.

Bootloader

NOTE: This section is going to change, and any information here may become incorrect or out of date at any moment. This is due to being in the middle of migrating bootloaders to the self-created RADII bootloader.

The bootloader is an EFI application; specifically an OS loader written for the UEFI spec. (currently V2.9). That specification outlines the use of PE32+ executables with a specific subsystem. As you may know, the PE32+ format is also used by Windows as it's executable format. This means that a compiler that generates Windows executables will generate the proper format of executable for an EFI application, given the subsystem modification. However, twenty or so years ago, GNU decided to write custom relocation linker scripts that create PE32+ executables from ELF executables. This means that a compiler that generates ELF executables is used, then that executable is transformed into a PE32+ executable with the proper subsystem for an EFI application. Luckily, all of this is handled by a Makefile.

Build dependencies for the bootloader:

cd gnu-efi
make

That only ever has to be done once, to generate libgnuefi.a.

From here, the bootloader executable can be built using the bootloader make target:

cd gnu-efi
make bootloader

Toolchain + Kernel

See the toolchain README

Once the toolchain is usable, continue on here.

I recommend taking a look at kernel/config.cmake and seeing what there is to fiddle with, but going with the defaults is just as well.

First, generate a build system using CMake. If you choose a different build system, keep in mind not all build systems honour our request to use a custom toolchain. I recommend Ninja, as it can speed up build times. Another tip to speed up build times; install ccache. The CMake scripts in this project detect and use it automatically.

cmake -G "Unix Makefiles" -S kernel -B kernel/bld

To generate the kernel executable, invoke the build system generated by CMake:

cmake --build kernel/bld

CMake will create certain targets if the proper dependencies are detected on the system.

To see a list of all available targets, use the following command:

cmake --build kernel/bld --target help

Boot Media Generation

Here is a list of the current build targets relating to boot media generation, as well as their dependencies listed underneath each.

  • image_raw -- Combine built executables and resources to generate UEFI-compatible FAT32 boot media.
  • image_gpt -- Create GPT-partitioned, bootable hard drive image from FAT32 boot media.
    • image_raw
    • One of the following:
      • fdisk -- Native command on Unix
      • createGPT
      • mkgpt
        • Repository
        • On Unix, use the automatic build + install script in the scripts subdirectory.
  • image_iso -- Create ISO-9660 "El-Torito" bootable CD-ROM image from FAT32 boot media.
  • image_vdi -- Convert GPT-partitioned raw disk image into Virtual Disk Image format (.vdi).

As an example, a FAT32 formatted UEFI-compatible boot image may be generated using the following command:

cmake --build kernel/bld --target image_raw

It takes just one command to build the LensorOS kernel, generate new boot media, and then launch the QEMU virtual machine into LensorOS.

cmake --build kernel/bld --target runimg_qemu

Birthday

Work on LensorOS began on January 9th, 2022.