NativeOS is a homebrew operating system for i386.
Go to file
Dani Rodríguez 1ef7f6427d i386: enable basic PS paging 2022-03-19 00:09:15 +01:00
.github Clarify contributing conditions 2017-07-15 23:38:30 +02:00
.vscode build: add meta files for Visual Studio Code 2021-12-29 11:56:54 +01:00
arch/i386 build: remove stash files that will not be used 2022-01-12 00:17:54 +01:00
conf i386: enable basic PS paging 2022-03-19 00:09:15 +01:00
kernel i386: enable basic PS paging 2022-03-19 00:09:15 +01:00
ramdisk main: cleanup kern_main demo routines 2022-01-23 23:40:04 +01:00
tools main: cleanup kern_main demo routines 2022-01-23 23:40:04 +01:00
.clang-format lint: change AlwaysBreakAfterReturnType value 2021-08-21 13:22:10 +02:00
.editorconfig stdkern: rebrand libc as stdkern 2021-07-17 20:13:50 +02:00
.gitignore doc: update doxygen toolchain 2022-01-02 09:25:33 +01:00 doc: adopt Contributor Covenant 2.0 (#2) 2019-11-18 22:11:56 +01:00 Clarify a few topics 2017-07-16 12:45:27 +02:00
CONTRIBUTORS Rewrite code header comments 2018-02-22 07:47:54 +01:00
COPYING Update docs 2015-12-12 14:17:28 +01:00
Doxyfile doc: update doxygen toolchain 2022-01-02 09:25:33 +01:00
Makefile meta: use SDL backend for QEMU 2022-01-28 20:54:13 +01:00 kcons: handle depfiles in makefile 2022-01-01 21:28:01 +01:00


NativeOS is a hobbyist kernel and operating system for the x86 platform. It is designed as a project to learn more about how the x86 processor work and how operating systems work. My intention is purely educational. The source code is open in the hope that it helps other people too.

Roadmap and contributing to the project

This project has no public roadmap. This means that I'm not disclosing what I'm working on when I'm working on this project. This is intended at this moment for this project because the project is not mature or stable enough and is still under development.

My issue and pull request policy is clarified on I'm not accepting pull requests at this moment. See the document to read why. Issues are still open and covered by the Code of Conduct. See for details.

Building the NativeOS Kernel

To build the kernel image (in other words, the program that will run when the computer starts up), you will need to install the LLVM compiler if you don't have it already. NativeOS switched to LLVM because it has support for foreign ABIs (such as i386-elf in an x86-64 macOS) out of the box without requiring to setup a cross-compiler.

GNU Make is also required to run the Makefile file.

Python 3 is also required to run the kcons tool, which is used to generate the Makefiles.

Windows NT is not a supported platform and there may be bugs. Users of Windows NT are encouraged to setup a POSIX system such as MSYS or Cygwin, or use the Windows Subsystem for Linux if available.

Picking a profile

Profiles are kernel compilation settings. A profile causes a specific subset of source code files to be compiled into the kernel image, and some specific optional settings to be enabled.

At the moment, the repository provides the I386 profile, to build a basic 32 bit kernel image for the i386 architecture. The settings file for this profile is at conf/I386.

Building a profile

To build a profile, you can use the kcons script. kcons will parse the profile and the associated files and generate a Makefile that can be used to build the kernel. Call tools/kcons providing the path to a profile file as a parameter.

$ tools/kcons conf/I386

This will generate a subdirectory named after the profile name inside the compile/ directory. In this directory, a Makefile will be present. Use it to build the kernel image:

$ cd compile/I386

Generating a depfile is recommended in order to have the object files recompiled whenever the imported source code changes:

$ make .depend

Then, proceed to build the kernel.

$ make kernel

Or, to make things faster,

$ make -C compile/I386 .depend kernel

The NativeOS kernel file is a binary in the ELF format. It supports the Multiboot specification, so it can be deployed in any machine using a bootloader capable of loading Multiboot binaries, such as GNU GRUB, SYSLINUX or Limine.

Running the profile in QEMU

For the i386 platform, QEMU supports a special flag called -kernel, where the path to a Multiboot executable file can be given. QEMU will treat the given file as if it was booted via a CD-ROM. This allows to quickly test the executable file without having to build CD-ROMs:

$ make -C compile/I386 qemu
qemu-system-i386 -kernel kernel -serial stdio

Debugging the profile in QEMU

QEMU also supports using the gdbserver protocol, so it is possible to connect QEMU with GDB in order to debug the running processor. There is a gdbinit file in the conf directory to help with the process.

$ make -C compile/I386 qemu-gdb

(In another terminal:)

$ gdb -x conf/gdbinit.I386
> continue


It is also possible to configure and build a kernel image profile using the root Makefile. Provide the profile name as the PROFILE parameter and it will run all the commands above.

$ make build-kernel PROFILE=I386

Creating a CD image

You can use some of the GRUB Command Line Tools to generate ISO files. There is already a rule in the Makefile file to generate a CD-ROM using GRUB.

You need the GRUB Command Line Tools installed with support for the i386-elf platform. If you are using GNU/Linux, you probably already have support for that platform, but otherwise you might have to install it to your system. Take protections to prevent GRUB to running on your host system if that is not practical for you. The grub-mkrescue program should be able to run in your command line.

GNU xorriso is additionally required to generate the ISO file.

To create a NativeOS ISO image, run the following command, specifying the name of a previously built profile as the PROFILE variable:

$ make cdrom PROFILE=I386

Windows NT, macOS and BSD users can install the GRUB Command Line tools by following the instructions given in the following address: (Instructions are the same for Windows).

NOTE: You'll be getting the GRUB Command Line Tools here. This is definitely NOT the same as installing the GRUB Bootloader on your host PC, although the command line tools allow you to do that, so care must be taken in order to avoid running any dangerous command.

Running NativeOS

A virtual machine is the safest way for running and testing NativeOS. I don't recommend running this on your host PC unless you know what you are doing and you have inspected the source code. Also, take a look at the disclaimer below before attempting to run anything that you could regret later.

The Makefile already has some rules to run the NativeOS ISO file with QEMU. It is even possible to run QEMU in debug mode and to remotely attach GDB in order to debug the kernel image.

Run the following commands:

$ make qemu PROFILE=I386      # Run qemu-system-i386
$ make qemu-gdb PROFILE=I386  # Run qemu-system-i386 in debug mode

For more information on GDB debugging with QEMU, see the QEMU manual or the following article:

License and disclaimer

Copyright (C) 2015-2021 Dani Rodríguez

NativeOS is licensed under the terms of the GNU General Public License v3. See the COPYING file for more information. Old NativeOS files will probably not have the GPL header on it. I'm working on that.

NativeOS is provided AS IS with no extra support. Working with kernels and OS and bootloaders is fun, but I'm not resposible for anything wrong you do with it. If you break your hard drive or your computer because of using the wrong command, that is not my fault.