diff --git a/README.md b/README.md index 97c2724..6d44ed1 100644 --- a/README.md +++ b/README.md @@ -58,151 +58,4 @@ Desktop ## Building -**Warning: This software is still in development. Expect bugs.** - -### Linux - -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. - -## 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. - - g++ -o bin/build_core util/build_core.c - bin/build_core headers - -Currently supported languages are 'c' (also works for C++), 'zig' and 'odin'. - -There is currently no documentation for the API; 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. - -## TODO - -**This list is incomplete!** - -- Applications - - PDF viewer - - Media player - - Automator - - Web browser -- Desktop environment - - Alt-tab - - Saving application state on shut down - - Task list popup - - Add more settings, and organize them - - Print screen key - - Storing images in the clipboard - - Combined search and Lua REPL - - Clipboard viewer - - Improved color eyedropper -- File Manager - - Deleting files - - Improving thumbnail storage - - Property store - - Searching - - Search indexing - - Tagging; metadata - - Tracking source of files - - Localizing system folder names - - Previewing other file types - - Filtering - - Multi-rename - - Compressed archives - - Creating new files - - Automation - - Grouping -- GUI - - Drag and drop - - Keyboard navigation in menus - - Date/time entry - - Tokens in textbox - - Right-to-left layout - - Accessibility hooks (e.g. for a screen reader) - - Choice boxes - - Resizable scrollbars - - Asynchronously painted element - - Reorder lists - - Dialogs as separate windows - - File dialogs - - Textbox auto-complete - - Media display - - Progress bars - - Dockable UI - - Charts - - Gauges - - Password editor - - Scrollbar animations - - Scaling at the paint level (as well as layout) - - Simpler control of line clipping in `EsTextDisplay` - - Fast scroll - - Keeping items anchored when resizing - - Instance reference counting -- Text rendering - - Variable font support - - Fix custom font renderer - - Unicode bidirectional text algorithm - - Unicode vertical text layout algorithm - - OpenType features - - Grapheme splitter (for textbox) - - Fallback fonts for unsupported languages - - Consistent font size specification -- API - - Date/time - - 2D graphics - - Tweening - - Media decoding - - Debugging other processes - - `io_uring`-like file access - - String sorting; normalization; case conversion -- Shared code - - Better heap allocator - - Faster rendering routines - - Color spaces -- Theming - - Dark theme - - High contrast theme - - Bitmapped font -- Kernel - - Networking protocol implementation - - Networking hardware drivers - - Rewrite audio layer - - Asynchronous IO - - Better IPC messaging - - Double fault handler - - `x86_32` support - - ARM support - - Graphics card drivers - - Support for USB 3.0 devices - - OHCI/UHCI/EHCI drivers - - USB hub support - - Built-in debugger - - Decrease startup time - - Decrease memory usage - - Shared memory permissions - - Proper worker threads - - Read-write file systems: FAT, ext4, NTFS -- Documentation! +See `help/Building.md` for a description of how to build and test the system. diff --git a/help/blog posts.txt b/help/Blog Posts.txt similarity index 100% rename from help/blog posts.txt rename to help/Blog Posts.txt diff --git a/help/Building.md b/help/Building.md new file mode 100644 index 0000000..229ca46 --- /dev/null +++ b/help/Building.md @@ -0,0 +1,53 @@ +# 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 + +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. diff --git a/help/CONTRIBUTING.md b/help/Contributing.md similarity index 86% rename from help/CONTRIBUTING.md rename to help/Contributing.md index 48c3c72..ca23cdd 100644 --- a/help/CONTRIBUTING.md +++ b/help/Contributing.md @@ -42,7 +42,7 @@ Variable names are usually descriptive, but sometimes shortened names are used f EsMessage m = {}; m.type = OS_MESSAGE_MEASURE; - EsMessagePost(&m); + EsMessagePost(&m); Operators are padded with spaces on either side. @@ -53,23 +53,8 @@ A space should be placed between a cast and its expression. int x = (float) y; Although the operating system is written in C++, most C++ features are avoided. -However, the kernel uses a lot of member functions. +However, the kernel uses a lot of member functions; this is being phased out. - struct Window { - void Update(bool fromUser); - void SetCursorStyle(OSCursorStyle style); - void NeedWMTimer(int hz); - void Destroy(); - bool Move(OSRectangle &newBounds); - void ClearImage(); - - Mutex mutex; // Mutex for drawing to the window. Also needed when moving the window. - Surface *surface; - OSPoint position; - size_t width, height; - ... - } - Default arguments often provided as functions grow over time. There is no limit on function size. However, you should avoid regularly exceeding 120 columns. @@ -111,18 +96,18 @@ The following subroutines may be of interest: Synchronisation: - void Mutex::Acquire(); - void Mutex::Release(); - void Mutex::AssertLocked(); + void KMutexAcquire(); + void KMutexRelease(); + void KMutexAssertLocked(); - void Spinlock::Acquire(); // Disables interrupts. - void Spinlock::Release(); - void Spinlock::AssertLocked(); + void KSpinlockAcquire(); // Disables interrupts. + void KSpinlockRelease(); + void KSpinlockAssertLocked(); - bool Event::Set(); - void Event::Reset(); - bool Event::Pool(); - bool Event::Wait(uintptr_t timeoutMs); // Return false on timeout. + bool KEventSet(); + void KEventReset(); + bool KEventPool(); + bool KEventWait(uintptr_t timeoutMs); // Return false on timeout. // event.autoReset determines whether the event will automatically reset after Poll() or Wait() return. Linked lists: @@ -143,13 +128,3 @@ Linked lists: LinkedList *list; // The list the item is in. T *thisItem; // A pointer to the item itself. } - -## Contributors - -Put your name here! - -- nakst -- Brett R. Toomey -- vtlmks -- Aleksander Birkeland - diff --git a/help/Credits.md b/help/Credits.md new file mode 100644 index 0000000..1841840 --- /dev/null +++ b/help/Credits.md @@ -0,0 +1,25 @@ +# Credits + +Thank you to all the people who have contributed to Essence! + +## Contributors + +Put your name here! + +- nakst +- Brett R. Toomey +- vtlmks +- Aleksander Birkeland + +## Included projects + +Licenses for included projects may be found in the following files: + +- `util/nanosvg.h` +- `util/hsluv.h` +- `shared/stb_image.h`, `shared/stb_sprintf.h`, `shared/stb_ds.h` and `util/stb_truetype.h` +- `res/Fonts/Hack License.txt`, `res/Fonts/Inter License.txt` +- `res/Icons/elementary Icons License.txt` +- `res/Sample Images/Licenses.txt` +- `res/Keyboard Layouts/License.txt` +- Ported applications have their licenses in their respective folders in `ports/`. diff --git a/help/notes from discord.txt b/help/Notes from Discord.txt similarity index 100% rename from help/notes from discord.txt rename to help/Notes from Discord.txt diff --git a/help/Source Map.md b/help/Source Map.md index 25984d6..e5a7b4d 100644 --- a/help/Source Map.md +++ b/help/Source Map.md @@ -1,3 +1,5 @@ +# 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. diff --git a/help/TODO.md b/help/TODO.md new file mode 100644 index 0000000..0ae2ac0 --- /dev/null +++ b/help/TODO.md @@ -0,0 +1,106 @@ +# TODO + +**This list is incomplete!** + +- Applications + - PDF viewer + - Media player + - Automator + - Web browser +- Desktop environment + - Alt-tab + - Saving application state on shut down + - Task list popup + - Add more settings, and organize them + - Print screen key + - Storing images in the clipboard + - Combined search and Lua REPL + - Clipboard viewer + - Improved color eyedropper +- File Manager + - Deleting files + - Improving thumbnail storage + - Property store + - Searching + - Search indexing + - Tagging; metadata + - Tracking source of files + - Localizing system folder names + - Previewing other file types + - Filtering + - Multi-rename + - Compressed archives + - Creating new files + - Automation + - Grouping +- GUI + - Drag and drop + - Keyboard navigation in menus + - Date/time entry + - Tokens in textbox + - Right-to-left layout + - Accessibility hooks (e.g. for a screen reader) + - Choice boxes + - Resizable scrollbars + - Asynchronously painted element + - Reorder lists + - Dialogs as separate windows + - File dialogs + - Textbox auto-complete + - Media display + - Progress bars + - Dockable UI + - Charts + - Gauges + - Password editor + - Scrollbar animations + - Scaling at the paint level (as well as layout) + - Simpler control of line clipping in `EsTextDisplay` + - Fast scroll + - Keeping items anchored when resizing + - Instance reference counting +- Text rendering + - Variable font support + - Fix custom font renderer + - Unicode bidirectional text algorithm + - Unicode vertical text layout algorithm + - OpenType features + - Grapheme splitter (for textbox) + - Fallback fonts for unsupported languages + - Consistent font size specification +- API + - Date/time + - 2D graphics + - Tweening + - Media decoding + - Debugging other processes + - `io_uring`-like file access + - String sorting; normalization; case conversion +- Shared code + - Better heap allocator + - Faster rendering routines + - Color spaces +- Theming + - Dark theme + - High contrast theme + - Bitmapped font +- Kernel + - Networking protocol implementation + - Networking hardware drivers + - Rewrite audio layer + - Asynchronous IO + - Better IPC messaging + - Double fault handler + - `x86_32` support + - ARM support + - Graphics card drivers + - Support for USB 3.0 devices + - OHCI/UHCI/EHCI drivers + - USB hub support + - Built-in debugger + - Decrease startup time + - Decrease memory usage + - Shared memory permissions + - Proper worker threads + - Read-write file systems: FAT, ext4, NTFS +- Write documentation