From ad5e082898112da376740107342bcaa5915eea94 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ole=20Andr=C3=A9=20Vadla=20Ravn=C3=A5s?= Date: Fri, 19 Apr 2024 13:06:00 +0200 Subject: [PATCH] docs: Update the build instructions --- _i18n/en/_docs/building.md | 177 ++++++++++++++----------------------- 1 file changed, 67 insertions(+), 110 deletions(-) diff --git a/_i18n/en/_docs/building.md b/_i18n/en/_docs/building.md index 9f0da1a7..fe0547ee 100644 --- a/_i18n/en/_docs/building.md +++ b/_i18n/en/_docs/building.md @@ -1,148 +1,105 @@ ## Table of contents 1. Building Frida - - [Design Constraints](#design-constraints) - - [GNU/Linux](#gnulinux) - - [macOS](#macos) - - [Windows](#windows) -2. Building the toolchain and SDK - - [Unix](#unix-toolchain-and-sdk) - - [Windows](#windows-toolchain-and-sdk) + - [Prerequisites](#prerequisites) + - [Getting the code](#clone) + - [Building for the native machine](#native) + - [Building for a different machine](#cross) + - [Building out-of-tree](#oot) ## Building Frida -### Design Constraints - -Frida has a fairly complex build system due to some design constraints: - -- **Short build time for new contributors.** Frida downloads a prebuilt -toolchain and SDK to save time. This requires a bit more fiddling to get the -build environment just right, but it has the added benefit of providing a -coherent build environment. - -- **No moving parts.** The final binary must be self-contained/portable. Some of -Frida's run-time components, like frida-helper, frida-agent, etc. may at some -point need to be present on the filesystem. These binaries are serialized and -linked into the Frida library (for example `_frida.so` in the case of -frida-python), which means it's portable without relying on external moving -parts. At runtime these are written out to a temporary directory and later -cleaned up. - -- **No runtime conflicts.** frida-agent, the shared library injected into target -processes, must have all of its dependencies (GLib, Gee, etc.) linked in to -avoid runtime conflicts with target applications that happen to use the same -libraries. Because of this, these libraries are compiled as static libraries. - -- **No resource leaks.** frida-agent, the shared library injected into target -processes, should not allocate any OS resources without releasing them when it -is unloaded to avoid accumulating leaks in long-lived processes. Because Frida -is mostly written in C and makes use of the excellent GLib library, which -unfortunately doesn't provide any way to fully clean up statically allocated -resources, we had to patch that library to add support for this. Upstream -doesn't consider this a valid use-case, so unfortunately we need to maintain our -fork of this library. This means we can't make use of a system-wide GLib on -GNU/Linux systems, which consequently makes the prebuilt SDK a bit larger. - -Frida's build system tries to keep you sane by making use of a prebuilt -toolchain and SDK for each platform. This is what's used in the steps outlined -below. - -### GNU/Linux - -- Make sure you have a: - - Modern x86 system with GCC 7.5 or newer - - Development toolchain, and Node.js on your PATH. E.g. on Ubuntu 20.04: +### Prerequisites + +You need: + +- C/C++ toolchain +- Node.js >= 18 +- Git + +For example on an Ubuntu system: + {% highlight bash %} -$ sudo apt-get install build-essential curl git lib32stdc++-9-dev \ - libc6-dev-i386 nodejs npm python3-dev python3-pip +$ sudo apt-get install build-essential git lib32stdc++-9-dev \ + libc6-dev-i386 nodejs npm {% endhighlight %} -- Clone `frida` and build it: +### Getting the code + {% highlight bash %} -$ git clone --recurse-submodules https://github.com/frida/frida.git -$ cd frida -$ make +$ git clone https://github.com/frida/frida.git {% endhighlight %} -Running `make` will provide you a list of modules to build. See -[the hacking page](https://frida.re/docs/hacking/) for more information. +### Building for the native machine -### macOS +To build, run: -- Make sure you have: - - Xcode with command-line tools - - [Python 3.10](https://www.python.org/downloads/mac-osx/) on your PATH - - [Node.js](https://nodejs.org/) on your PATH -- Clone `frida` and build it: {% highlight bash %} -$ git clone --recurse-submodules https://github.com/frida/frida.git -$ cd frida $ make {% endhighlight %} -Running `make` will provide you a list of modules to build. See -[the hacking page](https://frida.re/docs/hacking/) for more information. +Which will use `./build` as the build directory. Run `make install` to install. -### Windows +You may also do `./configure` first to specify a `--prefix`, or any other +options. Use `--help` to list the top-level options. -- Make sure you have: - - Visual Studio 2022 - - [Git](https://git-scm.com/downloads) on your PATH - - [Python 3.10](https://www.python.org/downloads/windows/) on your PATH - - Select `Add Python 3.10 to PATH` - - Set the installation directory to `C:\Program Files\Python310\`, or edit - releng\frida.props to change the *PythonLocation* values there. - - [Node.js](https://nodejs.org/) on your PATH +For setting lower level options, do: -- Clone the `frida` repository: {% highlight bash %} -$ git clone --recurse-submodules https://github.com/frida/frida +$ ./configure -- first-option second-option … {% endhighlight %} -- Open `frida.sln` and build it. +The options after `--` are passed directly to Meson's `setup` command. This +means you can also pass project options to subprojects, e.g.: -## Building the toolchain and SDK +{% highlight bash %} +$ ./configure -- \ + -Dfrida-gum:devkits=gum,gumjs \ + -Dfrida-core:devkits=core +{% endhighlight %} -This should not be necessary unless you're porting Frida to a new platform. The -following steps assume you have the OS-specific prerequisites mentioned above. +Consult `meson.options` in subprojects/* for available options. You may also +clone the different repos standalone and build the same way as described here. -### UNIX Toolchain and SDK +### Building for a different machine + +#### iOS/watchOS/tvOS -- Make sure your system has the following goodies: -{% highlight bash %} -$ sudo apt-get install bison flex gperf -{% endhighlight %} -- Clone the `frida` repository and build away: {% highlight bash %} -$ git clone --recurse-submodules https://github.com/frida/frida -$ cd frida -$ make -f Makefile.toolchain.mk -$ make -f Makefile.sdk.mk FRIDA_HOST=linux-x86_64 +$ ./configure --host=ios-arm64 +# or: ./configure --host=watchos-arm64 +# or: ./configure --host=tvos-arm64 +# optionally suffixed by `-simulator` +$ make {% endhighlight %} -- Transfer the resulting toolchain and SDK to a web server somewhere: + +#### Android + {% highlight bash %} -$ scp build/toolchain-*.tar.bz2 your@own.server: -$ scp build/sdk-*.tar.bz2 your@own.server: +$ ./configure --host=android-arm64 +$ make {% endhighlight %} -- Now you can clone `frida` like above and adjust the URLs in - `releng/setup-env.sh` (look for `download_command`) before running `make`. - You can also copy the files into `build/` and they'll be picked up instead of - attempting to download them. -### Windows Toolchain and SDK +#### Raspberry Pi -- Clone the `frida` repository and build away: {% highlight bash %} -$ git clone --recurse-submodules https://github.com/frida/frida -$ cd frida -$ python releng\build-deps-windows.py +$ sudo apt-get install g++-arm-linux-gnueabihf +$ ./configure --host=arm-linux-gnueabihf +$ make {% endhighlight %} -- Transfer the resulting toolchain and SDK to a web server somewhere: + +### Building out-of-tree + +Sometimes you may want to use a single source tree to build for multiple +systems or configurations. To do this, invoke `configure` from an empty +directory outside the source tree: + {% highlight bash %} -$ scp toolchain-windows-*.exe your@own.server: -$ scp sdk-windows-*.exe your@own.server: +$ mkdir build-ios +$ ../frida/configure --host=ios-arm64 +$ make +$ cd .. +$ mkdir build-android +$ ../frida/configure --host=android-arm64 +$ make {% endhighlight %} -- Now you can clone `frida` like above and adjust `BUNDLE_URL` in - `releng\deps.py` before opening `frida.sln`. - You can also copy the files into `build\` and they'll be picked up instead of - attempting to download them.