essence-os/help/Source Map.md

Source map

This file contains a list and description of the files and folders in the source tree.

• apps/ Builtin applications. Each application has an .ini file that is automatically detected by the build system.
  • samples/ Sample applications, demonstrating a small part of the API.
    • hello.c A hello world GUI application. Read through this first if you want to learn how to write applications for Essence!
    • converter.cpp A simple currency converter. Demonstrates panels, buttons, and textboxes.
    • game_loop.cpp A simple game loop. Demonstrates how to draw directly to the window with a custom UI element, and manually process keyboard input events.
    • list.cpp A sample of the fixed items mode of the list view.
  • file_manager/ The file manager application.
    • commands.cpp Implementation of commands like copy and paste.
    • folder.cpp Contains implementations of namespaces, like file system folders and the drives page.
    • main.cpp Main message loop, and settings management.
    • string.cpp String and path utilities.
    • type_database.cpp Management of file types.
    • ui.cpp Creates and manages the user interface. Contains the thumbnail generator.
• arch/ Contains target architecture specific files. Each architecture is placed in a separate folder, named after the target name. Note that some architecture specific code is also located in boot/. The folder will contain the following files:
  • kernel.s The assembly translation unit that will be linked with the kernel.
  • kernel.cpp The C++ translation unit that will be linked with the kernel. Together with kernel.s, this should provide all the functions listed in the architecture specific layer part of the kernel/kernel.h.
  • api.s The assembly translation unit that will be linked with the desktop. This must provide a system call interface, as well as a few miscellaneous functions.
  • config.ini Specifies additional compilation flags for the architecture.
• bin/ Contains the output of the build system that will not be copied onto the drive image.
  • Logs/ Contains various logs of the build processes and emulators.
    • net.dat Network packets captured and sent by Qemu.
    • audio.wav Audio captured by Qemu.
    • qemu_serial1.txt Serial output captured by Qemu.
    • system.log A list of commands passed to system() by util/build.c, including the time each command took.
  • cache/ Cached files downloaded from the internet, managed by the get-source command in the build system.
  • generated_code/ Automatically generated code.
  • build.ini The build configuration file that is passed from util/build.c to util/build_core.c. Save this if you want to automate a specific build.
  • build_config.ini The configuration file for util/build.c. Stores whether the user has read the license, and information about the cross compiler toolchain.
  • config.ini The configuration file modified by util/config_editor.c (open by running the config command in the build system). The full list of options in the file is stored in the options array in util/build_common.h.
  • dependencies.ini Saved information about source file dependencies used by the util/build_core.c for minimal rebuilds.
  • drive The output drive image, used to boot the emulators.
  • Additionally, there is an ELF executable file with debug symbols for each of the built applications, the desktop, the kernel and the build utilities.
• boot/ Contains boot code for different architectures, before the kernel is reached.
  • x86/ Boot code for x86 PC platforms.
    • mbr.s First stage of the MBR boot loader. Placed in the first sector of the drive.
    • mbr-emu.s An alternative version of mbr.s for CD-ROMs rather than hard drives.
    • esfs-stage1.s Second stage of the MBR boot loader. Placed in the first sector of the EsFS partition. Loaded by the first stage.
    • loader.s Third stage of the MBR boot loader. Placed in the reserved area of the EsFS partition. Loaded by the second stage.
    • esfs-stage2.s File system specific code for the third stage of the MBR boot loader.
    • vbe.s Contains code to select and set a video mode for the MBR boot loader; part of the third stage.
    • uefi.c First stage of the UEFI boot loader.
    • uefi_loader.s Second stage of the UEFI boot loader.
• cross/ Contains the cross compiler toolchain.
  • bin2/ When using the pre-built toolchain, wrappers of the executables in bin/ are stored here. These are needed to replace the system root path that was hard coded into the toolchain when it was configured.
• desktop/ The desktop and user interface.
  • prefix.h The prefix for the C/C++ API header. Contains various macros and things.
  • crt1.c Implementation of _start for executables running under the POSIX subsystem. Calls into the C standard library which will call main.
  • crtglue.c Redirection of POSIX system calls into posix.cpp.
  • api.cpp The main file of the desktop, including initialisation, work queues, user tasks, instances, undo stack management, command management, mount point management, and message processing.
  • api_tests.cpp Tests for the API. Called by the build system command run-tests.
  • desktop.cpp The desktop environment, including container windows, the task bar, the wallpaper, device management, and global initilisation.
  • gui.cpp The user interface. Contains core functionality and various elements. More complicated elements are split off into their own files.
  • inspector.cpp The debug inspector for the user interface.
  • list_view.cpp The list view UI element.
  • posix.cpp The userland implementation of the POSIX subsystem.
  • profiling.cpp Hooks for profiling with the gf extension pack.
  • renderer.cpp Rendering of 2D vector graphics.
  • settings.cpp The settings application.
  • syscall.cpp Wrappers of system calls.
  • text.cpp Text rendering, shaping and planning.
  • textbox.cpp The textbox UI element.
  • theme.cpp Theming and rendering for the user interface. More complicated rendering is handled by renderer.cpp. Uses the theme file made by util/designer2.cpp and stored in res/Theme.dat.
  • icons.header A list of constants for each of the icons in the standard icon pack. Automatically generated by util/render_svg.c.
  • os.header The API header itself. Language specific headers are generated by util/header_generator.c.
  • styles.header A list of styles available in the theme. Automatically generated by util/designer2.cpp.
• drivers/ Drivers linked into the kernel.
  • acpi.cpp Simple ACPI layer. Parses the MADT for loading other processors.
  • acpi_thermal.cpp ACPI thermal layer. Requires ACPICA.
  • acpica.cpp Integration with ACPICA, which provides greater ACPI functionality.
  • ahci.cpp AHCI/SATA drives.
  • bga.cpp Bochs Graphics Adapter, for setting the video mode on emulators.
  • esfs2.cpp The Essence file system (second version).
  • ext2.cpp Ext2 file system.
  • fat.cpp FAT12/16/32 file systems.
  • hda.cpp HD Audio.
  • i8254x.cpp i8254x networking card.
  • ide.cpp IDE/ATA drives.
  • iso9660.cpp ISO9660 file system for CD-ROMs.
  • ntfs.cpp NTFS file system.
  • nvme.cpp NVMe drives.
  • pci.cpp PCI bus enumeration.
  • ps2.cpp PS/2 keyboard and mouse.
  • rtc.cpp x86 Real Time Clock.
  • svga.cpp (S)VGA graphics drivers.
  • usb.cpp Common USB management for connecting and identifying devices.
  • usb_bulk.cpp USB bulk mass storage drives.
  • usb_hid.cpp USB HID class devices, including keyboards, mice and game controllers.
  • xhci.cpp xHCI USB controller driver.
• help/ You are here! Contains documentation about the project.
• kernel/ The kernel.
  • kernel.h Internal definitions for the kernel, including tweakable constants for the memory and cache managers, a list of functions that need to be implemented by the architecture specific layer, and includes for all the components of the kernel.
  • module.h The header file to be included by drivers that will be linked into the kernel or loaded as separate modules.
  • cache.cpp The cache manager, used by the file system manager. Provides CCSpace which can be read and written to with CCSpaceAccess.
  • drivers.cpp Management of drivers and device objects.
  • elf.cpp Loading ELF executables.
  • files.cpp The file system manager. Provides caching of directory structures and enumeration of file systems.
  • graphics.cpp Graphics routines.
  • main.cpp Initialisation and shut down.
  • memory.cpp The memory manager. Manages physical memory and virtual memory spaces.
  • networking.cpp The networking stack. Work in progress.
  • objects.cpp Includes object management and other IPC mechanisms: Opening/closing references to objects, handle tables, message queues, pipes and constant buffers.
  • posix.cpp The kernel side implementation of the POSIX subsystem.
  • scheduler.cpp The scheduler and management of threads and processes.
  • symbols.cpp Management of kernel symbols for linking with driver modules. This is kept as a separate translation unit so that it can receive a list of the functions available in the main kernel translation unit before all being linked together.
  • synchronisation.cpp Contains implementations of the synchronisation primitives and objects that the scheduler supports.
  • syscall.cpp The system call interface, between the desktop and kernel. Note that the system call interface is an internal implementation detail and is not an API.
  • terminal.cpp Terminal/serial output and debugging utilities.
  • windows.cpp The window manager.
  • config.ini A list of components and drivers available to the kernel. Drivers can specify a parent driver or module which will load them if a device they manage is enumerated.
• ports/ Ported application, including dependencies.
• res/ Resources, such as fonts and images.
  • Fonts/ Fonts. Licenses are contained in this folder.
  • Keyboard Layouts/ Keyboard layouts. Contains a license file, and extract_keymaps.c which can be used to generate the keyboard layout files here from an X11 system.
  • Sample Images/ Sample images. Contains a license file. Copy these into root/ to access them from the built system.
  • Theme Source.dat The source for the theme file, used by util/designer2.cpp. Open with the designer command in the build system.
  • Theme.dat The exported theme file that will be used by the UI. Call bin/designer2 export to regenerate this from the theme source.
  • elementary Icons.dat The elementaryOS icons pack. The icon pack is a custom format, and is generated by util/render_svg.c.
• root/ Contains the output of the build system that will be copied onto the drive image. You can put any files you want to be copied onto the drive in here.
• shared/ Shared code between different parts of the proejct, including data structures.
  • esfs2.h Definitions for the Essence file system, and code for managing it (compiled into util/build_core.c).
  • ini.h A tiny INI file parser.
  • arena.cpp A memory allocator for arbitrary allocation and freeing of fixed size memory blocks.
  • array.cpp Dynamically allocated array.
  • avl_tree.cpp AVL lookup tree, including support for searches for the "smallest above or equal" and "largest below or equal".
  • bitset.cpp Efficient large bitsets.
  • common.cpp Various common functions, including management of EsRectangles, rendering, string utilities, memory utilities (like EsMemoryCopy), printing and string formatting, pseudo random number generation, standard algorithms like sorting, synchronisation primitives, byte swapping, implementation of the EsCRT- functions, EsBuffer functions, and time and date calculations.
  • crc.h Implementation of CRC32 and CRC64 hash functions.
  • fat.cpp Common definitions for the FAT file system.
  • hash_table.cpp A hash table, including an implementation of the FNV1a hash function.
  • heap.cpp A memory allocator for arbitrary allocation and freeing of non-fixed size memory blocks.
  • linked_list.cpp Two implementations of a doubly-linked list: LinkedList<T> and SimpleList<T> where the latter requires less memory but provides less features.
  • math.cpp Mathematical functions, including basic utilities, interpolation routines, HSV color conversions, standard trigonometric functions, high precision floating-point calculations, and an expression parser.
  • partitions.cpp Contains routines to manage MBR and GPT partition tables.
  • png_decoder.cpp A decoder of PNG image files.
  • range_set.cpp Efficiently stores a subset of the integers as a list of ranges.
  • strings.cpp All text displayed in the user interface of the built-in applications.
  • unicode.cpp Implementations of various Unicode standards, including UTF-8 decoding and validation, and the line breaking algorithm.
  • vga_font.cpp A fixed-width bitmap font.
• util/ Contains utilities for developing and building the project.
  • linker/ Contains linker scripts.
  • w32/ The experimental W32 backend for the Essence desktop.
  • x11/ The experimental X11 backend for the Essence desktop.
  • automation/ Scripts for automating builds.
  • build_common.h Common definitions shared between build.c and build_core.c.
  • luigi.h A single-header cross platform GUI library.
  • build.c The main build system prompt, which manages dependencies, the toolchain, build configurations, and launching emulators. It is accessed by the developer by running the start.sh script at the root of the source tree. The developer can then issue commands to build and test the operating system and other utilities.
  • build_core.c The heart of the build system, which actually builds the project. It is called by build.c, and passed a build configuration file in bin/build.ini which contains all possible configuration options. It can run within Essence. It is also able to build single applications, by passing the .ini file for that application.
  • change_sysroot.c A utility that uses ptrace to replace strings in system calls.
  • toolchain_wrapper.c Wraps the executables in the pre-built toolchain to call into change_sysroot.c, to change the system root path they use.
  • config_editor.c A graphical editor for the configuration file, bin/config.ini. Uses luigi.h.
  • font_editor.c A basic bitmap font editor. Uses luigi.h.
  • header_generator.c Generates the API header for different programming languages from desktop/os.header. Part of build_core.c.
  • render_svg.c Converts SVGs to an internal format for vector graphics, and creates the icon pack found in res/. Despite the name this does not actually render the SVGs to bitmaps! That is eventually done in api/renderer.cpp.
  • designer2.cpp An editor of theme files for the UI. Uses luigi.h.
  • uefi.sh Creates a drive image using the UEFI boot loader.
  • uefi_compile.sh Compiles the UEFI boot loader.
  • uefi_to_device.sh Formats a real device to use the UEFI boot loader.
  • api_table.ini A list of all the functions exposed by the API, and their corresponding ordinals. Managed by header_generator.c.
  • test.txt A file containing a few traps that might be mangled by source control or compression utilities. Verified by start.sh to ensure that the source is as we'd expect.