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
|
||||
|
||||
**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 <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!
|
||||
See `help/Building.md` for a description of how to build and test the system.
|
||||
|
|
|
|||
|
|
@ -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 = {};
|
||||
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<T> *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
|
||||
|
||||
|
|
@ -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.
|
||||
|
||||
- `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