diff --git a/doc/installing-from-source.md b/doc/installing-from-source.md index 4e3a7e0..9c0ee8c 100644 --- a/doc/installing-from-source.md +++ b/doc/installing-from-source.md @@ -1,39 +1,54 @@ # Installing from source -Building Rayhunter from source, either for development or because the install script doesn't work on your system, involves a number of external dependencies. Unless you need to do this, we recommend you use our [compiled builds](https://github.com/EFForg/rayhunter/releases). +Building Rayhunter from source, either for development or otherwise, involves a +number of external dependencies. Unless you need to do this, we recommend you +use our [compiled builds](https://github.com/EFForg/rayhunter/releases). -* Install [nodejs/npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm), which is required to build Rayhunter's web UI - * Make sure to build the site with `pushd daemon/web && npm install && npm run build && popd` before building Rayhunter. If you're working directly on the frontend, `npm run dev` will allow you to test a local frontend with hot-reloading (use `http://localhost:5173` instead of `http://localhost:8080`). -* Install ADB on your computer using the instructions above, and make sure it's in your terminal's PATH - * You can verify if ADB is in your PATH by running `which adb` in a terminal. If it prints the filepath to where ADB is installed, you're set! Otherwise, try following one of these guides: - * [linux](https://askubuntu.com/questions/652936/adding-android-sdk-platform-tools-to-path-downloaded-from-umake) - * [macOS](https://www.repeato.app/setting-up-adb-on-macos-a-step-by-step-guide/) - * [Windows](https://medium.com/@yadav-ajay/a-step-by-step-guide-to-setting-up-adb-path-on-windows-0b833faebf18) -* Install `curl` on your computer to run the install scripts. It is not needed to build binaries. +At a high level, we have: -### Install Rust targets +* A JS frontend written in SvelteKit (`./daemon/web/`) +* A Rust binary `rayhunter-daemon` (`./daemon/`) that runs on the device, and bundles the frontend. +* A Rust binary `installer` (`./installer`) that runs on the computer and bundles `rayhunter-daemon`. + +It's recommended to work either on Mac/Linux, or WSL on Windows. + +## Step 1: Building the frontend + +Install [nodejs/npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm), which is required to build Rayhunter's web UI. + +Run: + +```sh +pushd daemon/web && npm install && npm run build && popd +``` + +## Step 2: Building the daemon [Install Rust the usual way](https://www.rust-lang.org/tools/install). Then, +- install a C compiler (`apt install build-essential` would be the command under Ubuntu) + - install the cross-compilation target for the device Rayhunter will run on: -```sh -rustup target add armv7-unknown-linux-musleabihf -``` -- install the statically compiled target for your host machine to build the binary installer `serial`. -```sh -# check which toolchain you have installed by default with -rustup show -# now install the correct variant for your host platform, one of: -rustup target add aarch64-unknown-linux-musl -rustup target add armv7-unknown-linux-musleabi -rustup target add x86_64-unknown-linux-musl -rustup target add aarch64-apple-darwin -rustup target add x86_64-apple-darwin -rustup target add x86_64-pc-windows-gnu -``` + ```sh + rustup target add armv7-unknown-linux-musleabihf + ``` -Now you can root your device and install Rayhunter by running: +- install the statically compiled target for your host machine: + + ```sh + # check which toolchain you have installed by default with + rustup show + # now install the correct variant for your host platform, one of: + rustup target add aarch64-unknown-linux-musl + rustup target add armv7-unknown-linux-musleabi + rustup target add x86_64-unknown-linux-musl + rustup target add aarch64-apple-darwin + rustup target add x86_64-apple-darwin + rustup target add x86_64-pc-windows-gnu + ``` + +Now to build the daemon: ```sh # Build the daemon binary for local development (rustcrypto TLS backend, fast compilation) @@ -48,16 +63,61 @@ cargo build-daemon-firmware-devel # Build rootshell cargo build-rootshell-firmware-devel +``` +## Step 3: Running the installer + +Now that all dependencies of the installer have been built, you can run the installer like so (with the device connected according to the regular installation instructions): + +```sh # Replace 'orbic' with your device type if different. # A list of possible values can be found with 'cargo run --bin installer help'. FIRMWARE_PROFILE=firmware-devel cargo run -p installer --bin installer orbic ``` -### If you're on Windows or can't run the install scripts +## Optional: Hot-reloading the frontend -* Root your device on Windows using the instructions here: -* Build the web UI using `cd daemon/web && npm install && npm run build` -* Push the scripts in `scripts/` to `/etc/init.d` on device and make a directory called `/data/rayhunter` using `adb shell` (and sshell for your root shell if you followed the steps above) -* You also need to copy `config.toml.in` to `/data/rayhunter/config.toml`. Uncomment the `device` line and set the value to your device type if necessary. -* Then run `./make.sh`, which will build the binary, push it over adb, and restart the device. Once it's restarted, Rayhunter should be running! +If you are working on the frontend, you normally have to repeat all of the above steps everytime to see a change. + +You can instead run the frontend separately on your PC while the Rust parts +continue running on your target device: + +```sh +cd daemon/web + +# Assumes rayhunter-daemon is listening on localhost:8080 +npm run dev + +# Use a custom target IP:port where the backend runs +API_TARGET=http://192.168.1.1:8080 npm run dev +``` + +The UI will listen on `localhost:5173` and instantly show any frontend changes +you make. Backend changes require building everything from the top (daemon and installer). + +## Optional: Installer utils, getting a shell + +Check `FIRMWARE_PROFILE=firmware-devel cargo run -p installer -- util --help` +for useful utilities for transferring files, opening shells. The exact tools +available wildly depend on the device you're working on, and they are +usually documented the relevant device's page under [Supported +Devices](./supported-devices.md). + +A lot of devices run a trimmed down version of Android and have ADB (Android +Debug Bridge) support. The USB-based installers (`orbic-usb`, `pinephone`, +`uz801`) use ADB to perform the installation. + +You might want to install and use actual ADB to connect to the device, push +files and generally poke around. `installer util --help` contains commands to enable +ADB for some devices. + +Note though that we can't assist with any issues setting ADB up, _especially +not_ on Windows. There have been too many driver issues to make this the +"golden path" for most users or contributors. There have been instances where +people managed to brick their orbic devices using ADB on Windows. + +The installers `orbic` and `tplink` use network connections exclusively to +perform the installation. They end up not enabling ADB at all, and as such +cannot run into permission issues, driver issues. The downside is that the +development tooling (getting a shell, transferring a file) is currently all +over the place, and mostly consists of random subcommands in `installer util`.