• • OrangeFox is FREE SOFTWARE licensed under the GPL version 3 (or any later version). The OrangeFox source code, vendor tree, and official device trees all fall under the GPL.
• • License under the GPL means, among other things, that the OrangeFox sources are freely available on the OrangeFox gitlab repository.
• • License under the GPL also means that, if you make any unofficial release of OrangeFox for public use, and you have patched or edited any part of the OrangeFox source code or vendor tree or device tree to build that release, you MUST also release all the patched source code (and trees if they have also been patched/edited). This code release should ideally be done in opensource-supporting repositories such as gitlab or github - and should be "public" (ie, members of the public have free and easy read-access to it). It is irrelevant that your build/release is considered "unofficial". You are still bound by the terms of the GPL and must make a public release of the patched/edited code. In other words, your patched code cannot be "private".
• • Please note that, if you will build and make a public release of OrangeFox, we fully expect you to comply with the terms of the GPL - and we will hold you to it.

Using our sync shell script from our "sync" repository; do NOT run this as root. The example below uses a script to sync the fox_12.1 branch.

• This method requires familiarity with linux shell scripts.
• If you want to build for Android 12 and higher ROMs, sync the fox_12.1 branch. You need at least 45GB of disk space for the fox_12.1 branch
• If your device
  requires
  a 14.x build system, then sync the fox_14.1 branch (note that
  very few
  devices would require this).
• The 14.1 branch is still at an
  experimental
  stage, and we will answer no questions relating to any problems you may encounter with it. You need at least 85GB of disk space for the fox_14.1 branch.
• You really should avoid building the 14.x branch, unless you are very keen on experimentation. In that case, you are on your own.
• In order to build OrangeFox, you must first sync the sources and manifest, using the sync script. For example:

• Tip: The version number of the build manifest is <u>a very different thing</u> from the OrangeFox release version numbers. If you have synced as shown above, then you already have the sources for the latest OrangeFox Stable releases for whichever branch you have synced.

• The process of syncing the sources will take a very long time. Depending on the speed of your internet connection, and on which method of syncing you use, it can take <u>hours</u>.
• After you finish building, your build may have problems with decryption. If this happens, there is little that we can do to help you. You will need to work on your device tree.

What if there is no device tree for my device?

• Amend the OrangeFox/TWRP device tree for a device with similar specifications, or
• Create a new device tree from the scratch, either manually, or by editing a template produced by some sort of "twrpgen" site (this is not a trivial task)

Building tips

• A. If you get any errors relating to anything with a ".py" extension or anything containing "py2",etc, then it means <u>you need to install Python 2.x</u>. Run "<u>python --version</u>" to see which version is being used as default - and, if it is not Python 2.7.x (eg, if it is Python 3.x) then you will have issues, and you will need to install v2.x
• B. Indeed, you should always make sure that your default python for building is python 2.x
• C. If you get build errors relating to "ui.xml for TW_THEME: portrait_hdpi", "Set TARGET_SCREEN_WIDTH and TARGET_SCREEN_HEIGHT to automatically select an appropriate theme", or "set TW_THEME to one of the following", etc, then it is possible that the bootable/recovery/gui/theme/ directory has not been properly synced. In that case, you might need to run a command like:

  git clone https://gitlab.com/OrangeFox/misc/theme.git bootable/recovery/gui/theme

  from the manifest root directory.
• D. If the device that you are building for is <u>not</u> a Xiaomi MIUI device, and/or you don't care about block-based incremental OTA updates, then you should consider adding this to your build process:

  export OF_DISABLE_MIUI_SPECIFIC_FEATURES=1

  or

  export FOX_VANILLA_BUILD=1
• E. If the device for which you are building OrangeFox is an A-only Xiaomi MIUI device, then you probably want to add this to your build process, to prevent the MIUI recovery from overwriting OrangeFox when you boot into the MIUI ROM:

  export OF_PATCH_AVB20=1
• F. If you are building for an A/B device (you must be sure of this!), then you should add this to your build process:

  export FOX_AB_DEVICE=1
• G. If you are building with the

  fox_12.1

  (or higher) branch and your device is a recent

  Virtual A/B ("VAB")

  device, then you should add this to your build process if you are getting problems with flashing the OrangeFox zip installer itself, or with things like changing the splash :

  export FOX_VIRTUAL_AB_DEVICE=1
• H. If you want your subsequent builds to be faster, then use <i>ccache</i> - eg

  export USE_CCACHE=1

  export CCACHE_EXEC=/usr/bin/ccache

  ccache -M 50G

  # this sets aside 50GB disk space for the cache
• I. If you are using a prebuilt kernel, and you start getting a "NO KERNEL CONFIG" error, try adding

  export OF_FORCE_PREBUILT_KERNEL=1

  to your build process (eg, in vendorsetup.sh)
• J. If your OrangeFox build variables are not being processed, ensure that your Linux shell for building is

  bash

  , and that you have run

  export FOX_BUILD_DEVICE=<device>

  before building.
• K. If your build is getting stuck on the logo (indicating a decryption problem), you should consider providing a default version number for the keymaster services, using the

  OF_DEFAULT_KEYMASTER_VERSION

  variable (in fact, it is <u>strongly recommended</u> to always do this anyway). This needs to specify the version number of the keymaster services that you have provided in your device tree (ensure that this is correct) - eg, for keymaster version 4.1:

  export OF_DEFAULT_KEYMASTER_VERSION=4.1
• L. If you enable

  TW_NO_SCREEN_BLANK

  in your device tree, then make sure that you give a correct value for

  TW_MAX_BRIGHTNESS

  - othewise, a default value (1023) will be used - and this may not be what you really want.
• M. Make sure that you have sufficient RAM on your PC/Server (read the requirements section at the top of this page).

If the build fails because the size of the recovery is too big

• If the kernel supports LZMA compression, then the most promising way to reduce the size is to use LZMA compression: "export OF_USE_LZMA_COMPRESSION=1"
• The next most promising way is to use "export FOX_DRASTIC_SIZE_REDUCTION=1" (this must come after all other exports)
• Other potential ways of reducing the size of the recovery image:

• Disable extra languages, in BoardConfig.mk: "TW_EXTRA_LANGUAGES :="
• Disable NTFS_3G, in BoardConfig.mk: "TW_INCLUDE_NTFS_3G :="
• Disable some other features, in BoardConfig.mk: "TW_EXCLUDE_TZDATA := true" "TW_EXCLUDE_LPDUMP := true"

• If you want help/support with respect to building OrangeFox for your device, go to our OrangeFox Recovery discord server.
• Make sure that you strictly follow the rules of our telegram and discord groups, otherwise you may be issued with warnings - or bans.
• If you have problems with build errors, or with booting up a successful build, or with things not working properly or not looking right, then you
  must
  provide the following: a) a link (on <u>gitlab</u> or <u>github</u>) to <u>your device tree</u> - this
  must
  be the <u>exact</u> version that you used to build the OrangeFox build that you are reporting problems for; b) a link (on a site like https://del.dog or https://pastebin.com) to a <u>full</u> log of your entire build process - do <u>NOT</u> just post screenshots or excerpts from the build logs; c) a list of <u>all the exact commands</u> that you used in building.

• If you truly want assistance with debugging your problematic build, then a) <u>You must provide a very detailed account</u> of what <u>exactly</u> you tried, and what <u>exactly</u> happened when you tried it. b) You must also provide a full account of the OrangeFox build variables that you used; c) You should also try to get a
  logcat
  (if booting is not successful), or, d) If booting is successful but the recovery is not behaving correctly, then you must also post the recovery logs
• Menu->Copy Log to SD", including the kernel log or
• adb pull /tmp/recovery.log
• adb pull /tmp/logcat.log

• Do <u>NOT</u> post silly messages like "it doesn't boot", or "it doesn't work", or "it fails", or "why this (or that) is happening", or anything along those lines. Such messages are <u>totally useless</u>, because they do not tell anybody what <u>exactly</u> is going on, or what exactly happens when you try to boot, or how exactly you are trying to boot, or anything meaningful that anyone could use to try to help you. We may simply ignore (or delete) such messages.
• If your build does not succeed in booting at all, then; a) You must first ensure that you have <u>correctly followed all the building instructions</u> (especially those relating to

  build variables

  ). b) Secondly, you must also ensure that the

  kernel

  you are using is not problematic. c) Thirdly, you must satisfy yourself that your

  device tree

  is correct.
• If errors occur during the build process, then, you should, in addition to providing a link to your device tree, a) Tell us which command you used to do the build (eg, "mka bootimage", etc); b) Capture a <u>full</u> log of the build process (not just extracts of where you think the error occurs) and post it to a site like pastebin.com or a similar site, and c) Post a link to the build log. d) You can capture a log of the build process by running a command like:

  mka recoveryimage | tee build.log

• OrangeFox has many of its own configurations and build variables ("build vars"), which give developers fine control over the features that are built into the recovery - see this (for fox_12.1 builds only) or this (for fox_14.1 builds) to understand which you should to enable.
• You should put the OrangeFox-specific build vars in a shell script, or in
  vendorsetup.sh
  in <u>your own device tree</u>. For a detailed example, have a look at this. Note - this is just an example of appropriate settings for one device. Obviously, you will need to amend this example in order to tailor it for your own device.
• Do <u>NOT</u> put OrangeFox-specific build variables that start with "FOX_" in BoardConfig.mk - they will not be processed properly, or at all, if they are in any ".mk" file - they must be in a script, or exported manually at the command line.

Q. How can I tell whether my device has dynamic partitions?

• If your device has a "Super" partition, or if it has "logical" flags for system, vendor, and product, in its fstab file, then it has dynamic partitions
• You can connect the device to a PC with a USB cable, open a command window, and run this command:
  adb shell getprop ro.boot.dynamic_partitions
  If the device has dynamic partitions, the output of the command will show "true"
• If your device shipped from the factory with Android 10 or higher, then it almost certainly has dynamic partitions

Q. How can I tell whether my device is an "A-only" or "A/B" device?

• Connect the device to a PC with a USB cable, and run the command:
  adb shell getprop ro.boot.slot_suffix
• If the device is an A/B device, then you will see what is the current slot being used (eg, "[_a]" or "[_b]")
• If device is an A-only device, then the command will produce no output
• In bootloader/fastbootd mode, the command to run is:
  fastboot getvar current-slot

• If you cloned the sources using the
  orangefox_sync.sh
  script, then follow the update instructions provided on the OrangeFox sync page

• Logcat will not work if you don't have a "task_profiles.json" file in your device tree's recovery/root/system/etc/ directory. You might need to copy one over from a ROM if you don't have one already.
• Haptics/vibrations may not work (indeed, you might need to disable it in order to get a successful build)
• Formatting the data partition may not work. If you get this problem, you will need to reboot to the bootloader and run the command: "<i>fastboot -w</i>" in order to be able to format the data partition.
• Backup of the <u>data</u> partition is broken. As of September 2025, a workaround has been implemented, meaning that backup and restore of the data partition should work as expected. However, this is only a workaround. Please report any success (or problem) at our Discord building stream.
• Watch this space!

• If you want to customise your version information, you should use "<b>FOX_MAINTAINER_PATCH_VERSION</b>" which can be used to specify any additional version information. You should use numbers only.
• For example, if the official release version is "R11.4", that will appear in every build. You can add your maintainer patch version number (eg, "5") like this:

  export FOX_MAINTAINER_PATCH_VERSION="5"
• In this example, the build release version will automatically become "R11.4_5"
• You can still use "FOX_VARIANT" as before.