mirror of https://gitlab.com/nakst/essence
organize help
This commit is contained in:
nakst
parent
8867d8686a
commit
81e70f29e5
149
README.md
149
README.md
|
|
@ -58,151 +58,4 @@ Desktop
|
||||||
|
|
||||||
## Building
|
## Building
|
||||||
|
|
||||||
**Warning: This software is still in development. Expect bugs.**
|
See `help/Building.md` for a description of how to build and test the system.
|
||||||
|
|
||||||
### 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 <language> <path-to-output-file>
|
|
||||||
|
|
||||||
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!
|
|
||||||
|
|
|
||||||
|
|
@ -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 <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.
|
||||||
|
|
@ -42,7 +42,7 @@ Variable names are usually descriptive, but sometimes shortened names are used f
|
||||||
|
|
||||||
EsMessage m = {};
|
EsMessage m = {};
|
||||||
m.type = OS_MESSAGE_MEASURE;
|
m.type = OS_MESSAGE_MEASURE;
|
||||||
EsMessagePost(&m);
|
EsMessagePost(&m);
|
||||||
|
|
||||||
Operators are padded with spaces on either side.
|
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;
|
int x = (float) y;
|
||||||
|
|
||||||
Although the operating system is written in C++, most C++ features are avoided.
|
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.
|
Default arguments often provided as functions grow over time.
|
||||||
|
|
||||||
There is no limit on function size. However, you should avoid regularly exceeding 120 columns.
|
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:
|
Synchronisation:
|
||||||
|
|
||||||
void Mutex::Acquire();
|
void KMutexAcquire();
|
||||||
void Mutex::Release();
|
void KMutexRelease();
|
||||||
void Mutex::AssertLocked();
|
void KMutexAssertLocked();
|
||||||
|
|
||||||
void Spinlock::Acquire(); // Disables interrupts.
|
void KSpinlockAcquire(); // Disables interrupts.
|
||||||
void Spinlock::Release();
|
void KSpinlockRelease();
|
||||||
void Spinlock::AssertLocked();
|
void KSpinlockAssertLocked();
|
||||||
|
|
||||||
bool Event::Set();
|
bool KEventSet();
|
||||||
void Event::Reset();
|
void KEventReset();
|
||||||
bool Event::Pool();
|
bool KEventPool();
|
||||||
bool Event::Wait(uintptr_t timeoutMs); // Return false on timeout.
|
bool KEventWait(uintptr_t timeoutMs); // Return false on timeout.
|
||||||
// event.autoReset determines whether the event will automatically reset after Poll() or Wait() return.
|
// event.autoReset determines whether the event will automatically reset after Poll() or Wait() return.
|
||||||
|
|
||||||
Linked lists:
|
Linked lists:
|
||||||
|
|
@ -143,13 +128,3 @@ Linked lists:
|
||||||
LinkedList<T> *list; // The list the item is in.
|
LinkedList<T> *list; // The list the item is in.
|
||||||
T *thisItem; // A pointer to the item itself.
|
T *thisItem; // A pointer to the item itself.
|
||||||
}
|
}
|
||||||
|
|
||||||
## Contributors
|
|
||||||
|
|
||||||
Put your name here!
|
|
||||||
|
|
||||||
- nakst
|
|
||||||
- Brett R. Toomey
|
|
||||||
- vtlmks
|
|
||||||
- Aleksander Birkeland
|
|
||||||
|
|
||||||
|
|
@ -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/`.
|
||||||
|
|
@ -1,3 +1,5 @@
|
||||||
|
# Source map
|
||||||
|
|
||||||
This file contains a list and description of the files and folders in the source tree.
|
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.
|
- `apps/` Builtin applications. Each application has an `.ini` file that is automatically detected by the build system.
|
||||||
|
|
|
||||||
|
|
@ -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
|
||||||
Loading…
Reference in New Issue