From 8a6b1e635736b520d6b5bca687c3710b4c6de6a1 Mon Sep 17 00:00:00 2001 From: hut Date: Mon, 29 Apr 2024 16:31:58 +0200 Subject: [PATCH] add HACKING.md --- HACKING.md | 95 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 94 ++--------------------------------------------------- 2 files changed, 97 insertions(+), 92 deletions(-) create mode 100644 HACKING.md diff --git a/HACKING.md b/HACKING.md new file mode 100644 index 0000000..2dc86f6 --- /dev/null +++ b/HACKING.md @@ -0,0 +1,95 @@ +# Dev Features + +For development, it's recommended to use `--features dev`: + +``` +cargo [run|build] --features dev +``` + +This enables the following: + +- Mutes music by default (you can still unmute it) +- Enables "dev mode", which changes the game slightly: + - Enables additional cheats (see source code) + - Speeds up dialogs + - Adds additional debugging features +- Enables dynamic linking for faster compile times. Note that this makes it harder to run the game directly with `./outfly`, please use `cargo run` instead. +- Enables bevy's "file watcher" feature that auto-reloads changed assets while the game is running. This obviously works only if the assets are not embedded directly into the binary with the `embed_assets` feature. Since `embed_assets` is enabled by default, you must customize your compile features in order to use the file watcher feature, e.g. like: `--no-default-features --features "dev x11"` + +# pack.sh + +The [pack.sh](src/build/pack.sh) script is used by the developer team to compile and pack release binaries into official packages. + +It could serve as a starting point for package maintainers or tinkerers. + +# Building OutFly + +If there is no package for the version or operating system that you need, or if you wish to tinker on the game, you can also build outfly yourself. + +## On Linux + +Install the build dependencies. On ArchLinux, it's the following, though you can replace `rust` with `rustup`: + +``` +pacman -S rust libx11 pkgconf alsa-lib +``` + +Then run the following commands, replacing `[URL]` with the clone URL of the git repository: + +``` +git clone [URL] +cd outfly +cargo run --release +``` + +## Building for Windows on Linux + +``` +rustup target add x86_64-pc-windows-gnu +pacman -S mingw-w64-toolchain # on ArchLinux. other distros have their equivalent package +cargo build --target=x86_64-pc-windows-gnu --release +``` + +More information here: https://bevy-cheatbook.github.io/setup/cross/linux-windows.html + +## Building on Mac OS + +Install homebrew, and then get the following dependencies: + +``` +brew install pkg-config molten-vk rustup +rustup-init +``` + +Download, compile and run the game: + +``` +git clone [URL] +cd outfly +cargo run --release +``` + +## Building for WASM/Browser + +This is a work in progress, for now these are just some general hints: + +``` +git clone [URL] +cd outfly +rustup target install wasm32-unknown-unknown +pacman -S wasm-bindgen binaryen +mkdir outfly_wasm +cargo build --release --target wasm32-unknown-unknown +wasm-bindgen --out-name outfly --out-dir outfly_wasm --target web target/wasm32-unknown-unknown/release/outfly.wasm +wasm-opt -Oz --output wasm/outfly_bg.wasm wasm/outfly_bg.wasm +echo '' > wasm/index.html +python -m http.server -d wasm +``` + +## Building release versions optimized for packaging + +To build release versions optimized for final deployment, build with the following features: (see also [pack.sh](https://codeberg.org/hut/outfly/src/branch/main/src/build/pack.sh)) + +``` +cargo build --release --no-default-features --features release_[linux|windows] [--target=$YOUR_TARGET] +``` diff --git a/README.md b/README.md index 06db097..de69ac2 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ + ▀████████████████████████████████████████████████████▀ ``` -[Features](#features) • [Controls](#controls) • [Running OutFly](#running-outfly) • [Troubleshooting](#troubleshooting) • [Building](#building) +[Features](#features) • [Controls](#controls) • [Running OutFly](#running-outfly) • [Troubleshooting](#troubleshooting) # OutFly @@ -99,7 +99,7 @@ yay -S outfly-git ## Running on MacOS / Android / iOS -No releases for these operating systems exist yet. For MacOS, you can build OutFly yourself using the instructions below. Support for Android/iOS is planned for the future. +No releases for these operating systems exist yet. For MacOS, you can build OutFly yourself using the instructions in [HACKING.md](https://codeberg.org/hut/outfly/src/branch/main/HACKING.md). Support for Android/iOS is planned for the future. # Troubleshooting ## My GPU doesn't support Vulkan! @@ -137,93 +137,3 @@ If you build without the "`embed_assets`" feature, the asset folder must be in t Create a shortcut, change the target from `[...]outfly.exe` to e.g. `[...]outfly.exe --gl`. See https://superuser.com/questions/1202989/how-to-you-add-a-parameter-to-an-executable-in-windows-10 - -# Building - -If there is no package for the version or operating system that you need, or if you wish to tinker on the game, you can also build outfly yourself. - -## On Linux - -Install the build dependencies. On ArchLinux, it's the following, though you can replace `rust` with `rustup`: - -``` -pacman -S rust libx11 pkgconf alsa-lib -``` - -Then run the following commands, replacing `[URL]` with the clone URL of the git repository: - -``` -git clone [URL] -cd outfly -cargo run --release -``` - -## Building for Windows on Linux - -``` -rustup target add x86_64-pc-windows-gnu -pacman -S mingw-w64-toolchain # on ArchLinux. other distros have their equivalent package -cargo build --target=x86_64-pc-windows-gnu --release -``` - -More information here: https://bevy-cheatbook.github.io/setup/cross/linux-windows.html - -## Building on Mac OS - -Install homebrew, and then get the following dependencies: - -``` -brew install pkg-config molten-vk rustup -rustup-init -``` - -Download, compile and run the game: - -``` -git clone [URL] -cd outfly -cargo run --release -``` - -## Building for WASM/Browser - -This is a work in progress, for now these are just some general hints: - -``` -git clone [URL] -cd outfly -rustup target install wasm32-unknown-unknown -pacman -S wasm-bindgen binaryen -mkdir outfly_wasm -cargo build --release --target wasm32-unknown-unknown -wasm-bindgen --out-name outfly --out-dir outfly_wasm --target web target/wasm32-unknown-unknown/release/outfly.wasm -wasm-opt -Oz --output wasm/outfly_bg.wasm wasm/outfly_bg.wasm -echo '' > wasm/index.html -python -m http.server -d wasm -``` - -## Building release versions optimized for packaging - -To build release versions optimized for final deployment, build with the following features: (see also [pack.sh](https://codeberg.org/hut/outfly/src/branch/main/src/build/pack.sh)) - -``` -cargo build --release --no-default-features --features release_[linux|windows] [--target=$YOUR_TARGET] -``` - -## Dev Features - -For development, it's recommended to use `--features dev`: - -``` -cargo [run|build] --features dev -``` - -This enables the following: - -- Mutes music by default (you can still unmute it) -- Enables "dev mode", which changes the game slightly: - - Enables additional cheats (see source code) - - Speeds up dialogs - - Adds additional debugging features -- Enables dynamic linking for faster compile times. Note that this makes it harder to run the game directly with `./outfly`, please use `cargo run` instead. -- Enables bevy's "file watcher" feature that auto-reloads changed assets while the game is running. This obviously works only if the assets are not embedded directly into the binary with the `embed_assets` feature. Since `embed_assets` is enabled by default, you must customize your compile features in order to use the file watcher feature, e.g. like: `--no-default-features --features "dev x11"`