A 64-bit all-inclusive operating system, from bootloader to userspace.
LensorOS is migrating away from GitHub, in favor of the FOSS Codeberg.
Free, compatible virtual machines:
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.
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.imgrunhda_qemu
-- LensorOS.binruniso_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>
- Open VirtualBox.
- Click the
New
button to create a new virtual machine (VM). - Give the VM a name and a file path you are comfortable with.
- Select Type of
Other
and Version ofOther/Unknown (64-bit)
. - Leave the memory size how it is; 64MB is plenty at this time.
- Select the
Do not add a virtual hard disk
option. - Click the
Create
button to create the new virtual machine. - Select the new VM in the list on the left, then click the
Settings
button. - Navigate to
System
within the list on the left.- Change Chipset to
ICH9
. - Enable Extended Feature
Enable EFI (special OSes only)
.
- Change Chipset to
- Navigate to
Storage
within the list on the left.- Right click the default controller (
IDE
), and selectRemove Controller
. - Right click the area labeled
Storage Devices
, and selectAHCI (SATA)
. - Right click the new AHCI storage controller, and select either
Optical Drive
orHard Disk
depending on whether you'd like to boot from the.iso
or.bin
, respectively. - Click
Add
in the new Virtual Media Selector window that pops up. - Browse to this folder and, depending on whether
Optical Drive
orHard Disk
was selected, choose eitherLensorOS.iso
orLensorOS.bin
.
- Right click the default controller (
- Navigate to
Network
within the list on the left.- Disable all network adapters.
- Navigate to
Serial Ports
within the list on the left.- Ensure
Enable Serial Port
is checked,COM1
is selected,IRQ
is4
, andI/O Port
is0x3F8
.
- Ensure
- Open VMWare Workstation Player
- Select
Home
in the list on the left side. ClickCreate a New Virtual Machine
on the right. - Select the
I will install the operating system later.
option. - Select a guest OS of
Other
, and a Version ofOther 64-bit
. - Give the VM a name and path you are comfortable with. Keep note of the path.
- It will ask about a disk, but the disk it's asking about won't be used. Click next.
- The next screen should be an overview of the virtual machine hardware. Click
Customize Hardware...
.- Select
New CD/DVD
on the left, then clickAdvanced...
on the right. - Select
SATA
, then clickOK
. - On the right, select
Use ISO image file
, and then clickBrowse...
. - Select the
LensorOS.iso
image file (located inkernel/bin/
). - Select the hard drive that we skipped configuring in the list on the left.
- Remove the hard drive using the
Remove
button near the bottom center. - Remove any and all network adapters and sound cards in the same manner.
- Click
Close
in the bottom right to close the hardware configuration window.
- Select
- Click
Finish
. - Navigate to the path specified in step #5, where the virtual machine is located.
- Open the file ending with
.vmx
in a text editor. - Add the following line of text:
firmware="efi"
. - Save the file, then close it.
- Open the file ending with
You will have to select UEFI Shell
once VMware Workstation
boots into LensorOS (even if it says something like Unsupported
).
There are multiple steps in the LensorOS build process, outlined here.
NOTE: All blocks of shell commands given are expected to start with the working directory at the root of the repository.
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.
- A 64-bit version of the GNU toolset for your host OS.
- Debian distros:
sudo apt install build-essential make
- Windows:
- Debian distros:
- CMake >= 3.20
- Git
- Netwide Assembler (nasm)
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://codeberg.org/LensPlaysGames/LensorOS.git
This will create a subdirectory titled LensorOS
with the contents of
this repository in the current working directory.
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 the 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
Once the toolchain is usable, continue on here.
I recommend taking a look at toolchain/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 Ninja -B bld
PLEASE BE ADVISED that there are critical messages in the output of the above command that may detail critical targets haven't been created due to programs not being found on the system.
To build libc, userspace programs, and finally the kernel executable, invoke the build system generated by CMake:
cmake --build 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 bld --target help
Lens' most-used targets:
runhda_qemu
image_gpt
image_vdi
userspace
kernel
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.- The built bootloader EFI application at
gnu-efi/x86_64/bootloader/main.efi
. Kernel
build target (relies onkernel/bin/kernel.elf
).- dd -- Native command on Unix
- On Windows, use one of the following options:
- MinGW installer to get MSYS coreutils ext package
- Cygwin
- Windows Subsystem for Linux
- On Windows, use one of the following options:
- GNU mtools
- Home Page
- Debian distros:
sudo apt install mtools
- Pre-built binaries for Windows
- The built bootloader EFI application at
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
- Repository
- Pre-built binaries for Linux + Windows
- I was annoyed that there wasn't a (working) cross platform tool for creating GPT disk images that was open source, and easy to use, so I made one.
- 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_raw
- GNU xorriso
- Home Page
- Debian distros:
sudo apt install xorriso
- Pre-built binaries for Windows
image_vdi
-- Convert GPT-partitioned raw disk image into Virtual Disk Image format (.vdi
).image_gpt
- qemu-img
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
Work on LensorOS began on January 9th, 2022.