jflib-rt
The runtime at the very bottom of JFLib. A program built on JFLib does not
need Rust's standard library, and this crate is the reason why: it brings what std would
otherwise bring, the memory allocator, memcpy and its relatives, the program's entry point and
what happens when something goes wrong. Every other JFLib crate stands on it.
Do you need this crate?
Usually not directly. An app depends on jflib, which brings
this crate along and makes it available as jflib::rt. All of JFLib's crates share one version
and are released together, so there is nothing to pick and nothing to keep in step by hand.
What it does
It starts the program. ui::main! (for apps with a window) and rt::main! (for command-line
tools) end up here. rt defines the entry symbol and hands what the build put into the program, its
name, its permission manifest and its built-in assets, to the platform layer before your code
runs. There is no C runtime underneath. Memory comes in pages straight from the operating system,
and on Linux the result is a static executable that talks to the kernel through system calls.
It ends the program cleanly when something goes wrong. A panic and a real crash (an access
violation, an illegal instruction, a division by zero) end the same way: one report on stderr
that says what happened and where, then the app's own crash hook if it set one
(rt::crash::set_hook, a good place to save a backup of the open document), then exit code 3.
The crash path never allocates, because the crashing thread may be holding the allocator's lock.
It keeps numbers the same everywhere. JFLib is meant to compute the same pixels and the same
text on every machine. rt holds the few operations where that does not come for free:
float-to-integer conversions and rounding exactly as SSE does them (rt::fx), and the
extended-precision steps that turn a double into decimal text and back, plus pow, sin,
cos, exp2, log2 and atan2 (rt::x87). On x86-64 those run on the processor's x87 unit.
On ARM64, Android, Apple systems and in the browser a software version takes over that gives the
same bits on every processor and stays within about half an ulp.
And a few small things the rest needs: the processor's features (rt::cpu), a spin lock
(rt::sync::SpinLock), JFLib's version (rt::VERSION), the app's own version
(rt::app_version!()) and the calling convention of plugins and loadable modules
(rt::plugin_abi!).
With the standard library
An app may still use std, for example to use a crate that needs it (jflib with the feature
std). Then std brings the allocator, the entry point and the panic handler, and rt steps
aside. rt::panic_hook() makes std's panics end with JFLib's crash report all the same. With the
feature unwind, a panic the app catches with std::panic::catch_unwind leaves the program
running, and rt::panic_take() tells what it said. The guide explains it under
An app with std.
Platforms
Windows (x86-64 and ARM64), Linux (x86-64 and ARM64), macOS and iOS on Apple silicon, Android, and the browser (wasm32).
What's new in 0.2.1
Intel Macs (x86_64-apple-darwin): cpu detects the processor by CPUID and x87 computes on the
x87 unit, as on Windows and Linux; under Rosetta 2 the decimal conversions give the same bits as on
Windows. cargo test --lib builds the unit tests of a library crate with std and rt::main!. On
Linux the build script picks the build against glibc itself, so cargo run needs no flags.
Everything is in the changelog.
Documentation
- JFLib's guide: how an app is written
- API reference: every public
item of
rt, also on docs.rs
License
MIT or Apache-2.0, at your choice.