Awesome
eframe template
This is a template repo for eframe, a framework for writing apps using egui.
The goal is for this to be the simplest way to get started writing a GUI app in Rust.
You can compile your app natively or for the web, and share it using Github Pages.
Getting started
Start by clicking "Use this template" at https://github.com/emilk/eframe_template/ or follow these instructions.
Change the name of the crate: Choose a good name for your project, and change the name to it in:
Cargo.toml
- Change the
package.name
fromeframe_template
toyour_crate
. - Change the
package.authors
- Change the
main.rs
- Change
eframe_template::TemplateApp
toyour_crate::TemplateApp
- Change
index.html
- Change the
<title>eframe template</title>
to<title>your_crate</title>
. optional.
- Change the
assets/sw.js
- Change the
'./eframe_template.js'
to./your_crate.js
(infilesToCache
array) - Change the
'./eframe_template_bg.wasm'
to./your_crate_bg.wasm
(infilesToCache
array)
- Change the
Alternatively, you can run fill_template.sh
which will ask for the needed names and email and perform the above patches for you. This is particularly useful if you clone this repository outside GitHub and hence cannot make use of its
templating function.
Learning about egui
src/app.rs
contains a simple example app. This is just to give some inspiration - most of it can be removed if you like.
The official egui docs are at https://docs.rs/egui. If you prefer watching a video introduction, check out https://www.youtube.com/watch?v=NtUkr_z7l84. For inspiration, check out the the egui web demo and follow the links in it to its source code.
Testing locally
Make sure you are using the latest version of stable rust by running rustup update
.
cargo run --release
On Linux you need to first run:
sudo apt-get install libxcb-render0-dev libxcb-shape0-dev libxcb-xfixes0-dev libxkbcommon-dev libssl-dev
On Fedora Rawhide you need to run:
dnf install clang clang-devel clang-tools-extra libxkbcommon-devel pkg-config openssl-devel libxcb-devel gtk3-devel atk fontconfig-devel
Web Locally
You can compile your app to WASM and publish it as a web page.
We use Trunk to build for web target.
- Install the required target with
rustup target add wasm32-unknown-unknown
. - Install Trunk with
cargo install --locked trunk
. - Run
trunk serve
to build and serve onhttp://127.0.0.1:8080
. Trunk will rebuild automatically if you edit the project. - Open
http://127.0.0.1:8080/index.html#dev
in a browser. See the warning below.
assets/sw.js
script will try to cache our app, and loads the cached version when it cannot connect to server allowing your app to work offline (like PWA). appending#dev
toindex.html
will skip this caching, allowing us to load the latest builds during development.
Web Deploy
- Just run
trunk build --release
. - It will generate a
dist
directory as a "static html" website - Upload the
dist
directory to any of the numerous free hosting websites including GitHub Pages. - we already provide a workflow that auto-deploys our app to GitHub pages if you enable it.
To enable Github Pages, you need to go to Repository -> Settings -> Pages -> Source -> set to
gh-pages
branch and/
(root).If
gh-pages
is not available inSource
, just create and push a branch calledgh-pages
and it should be available.If you renamed the
main
branch to something else (say you re-initialized the repository withmaster
as the initial branch), be sure to edit the github workflows.github/workflows/pages.yml
file to reflect the changeon: push: branches: - <branch name>
You can test the template app at https://emilk.github.io/eframe_template/.
Updating egui
As of 2023, egui is in active development with frequent releases with breaking changes. eframe_template will be updated in lock-step to always use the latest version of egui.
When updating egui
and eframe
it is recommended you do so one version at the time, and read about the changes in the egui changelog and eframe changelog.