essence-os/help/Building.md

Building Essence

Warning: This software is still in development. Expect bugs.

Linux

These instructions expect you to be running an updated modern Linux distribution. See below for additional information about specific distributions.

Download this project's source.

git clone --depth=1 https://gitlab.com/nakst/essence.git/

Start the build system.

./start.sh

Follow the on-screen instructions to build a cross compiler.

Once complete, you can test the operating system in an emulator.

• If you have Qemu and KVM installed, run k in the build system. Recommended!
• If you have Qemu installed, run t2 in the build system.
• If you have VirtualBox installed, make a 128MB drive called vbox.vdi in the bin folder, attach it to a virtual machine called "Essence" (choose "Windows 7 64-bit" as the OS), and run v in the build system.

Run build-port in the build system to view a list of optional ports that can be built.

Arch Linux

You can install all the needed dependencies with sudo pacman -S base-devel curl nasm gmp mpfr mpc ctags qemu. Run ./start k to build and run the system in Qemu.

Fedora Linux

You can install all the needed dependencies with dnf install nasm gmp gmp-devel mpfr mpfr-devel libmpc libmpc-devel. Run ./start k to build the system. Then run qemu-kvm bin/drive to launch the built image in Qemu.

Configuration

From within the build system, run the command config to open the configuration editor. Click an option to change its value, and then click the Save button. You changes are saved locally, and will not be uploaded by Git. Not all configurations are likely to work; if you don't know what you're doing, it's probably best to stick with the defaults.

Keyboard layout

To set the default keyboard layout for use in the emulator to match your current one, run:

setxkbmap -query | grep layout | awk '{OFS=""; print "General.keyboard_layout=", $2}' >> bin/config.ini

Generating the API header

If you want your project to target Essence, you need to generate the API header for your programming language of choice.

gcc -o bin/build_core util/build_core.c
bin/build_core headers <language> <path-to-output-file>

Currently supported languages are 'c' (also works for C++), 'zig' and 'odin'.

Documentation for the API is still a work in progress. For examples of how to use the API, consult the standard applications in the apps/ folder of the source tree. Minimal sample applications are placed in the apps/samples folder. By placing your application's .ini file in the apps/ folder, it will be automatically built by the build system.