Ensure that you have Docker installed. You can follow [Docker's installation instructions](https://docs.docker.com/engine/installation/).
When the build is done, you will find the current firmware in `build/legacy/firmware/trezor.bin`.
### Running with sudo
It is possible to run `build-docker.sh` if either your Docker is configured in rootless mode,
or if your user is a member of the `docker` group; see [Docker documentation](https://docs.docker.com/install/linux/linux-postinstall/)
for details.
If you don't satisfy the above conditions, and run `sudo ./build-docker.sh`, you might receive a `Permission denied`
error. To work around it, make sure that the directory hierarchy in `build/` directory
is world-writable - e.g., by running `chmod -R a+w build/`.
## Building older versions
For firmware versions **1.8.1** and newer, you can checkout the respective tag locally.
To build firmware 1.8.2, for example, run `git checkout legacy/v1.8.2` and then use
the instructions below.
Note that the unified Docker build was added after version 1.8.3, so it is not available
for older versions.
For firmwares older than 1.8.1, please clone the archived [trezor-mcu](https://github.com/trezor/trezor-mcu) repository and follow the instructions in its README.
## Local development build
Make sure you have Python 3.6 or later and [pipenv](https://pipenv.readthedocs.io/en/latest/install/)
installed.
If you want to build device firmware, also make sure that you have the [GNU ARM Embedded toolchain](https://developer.arm.com/open-source/gnu-toolchain/gnu-rm/downloads) installed.
See [Dockerfile](../../ci/Dockerfile#L72-L76) for up-to-date version of the toolchain.
The build process is configured via environment variables:
* `EMULATOR=1` specifies that an emulator should be built, instead of the device firmware.
* `DEBUG_LINK=1` specifies that DebugLink should be available in the built image.
* `MEMORY_PROTECT=0` disables memory protection. This is necessary for installing unofficial firmware.
* `DEBUG_LOG=1` enables debug messages to be printed on device screen.
* `BITCOIN_ONLY=1` specifies Bitcoin-only version of the firmware.
To run the build process, execute the following commands:
3. Use `trezorctl` dry-run mode to get the firmware fingerprint:
```sh
trezorctl firmware-update -n -f trezor.signed.bin
```
Step 3 should produce the same sha256 fingerprint like your local build (for the same version tag). Firmware has a special header (of length 256 bytes) holding signatures themselves, which must be avoided while calculating the fingerprint, that's why tail command has to be used.
Step 3 should produce the same fingerprint like your local build (for the same version tag).
## How to install custom built firmware?
**WARNING: This will erase the recovery seed stored on the device! You should never do this on Trezor that contains coins!**
*Note: if your device is on the latest bootloader version and you flash custom firmware then you will receive a hard fault warning when booting the firmware image. To avoid this issue, just remove the code in startup.s added by [this commit](https://github.com/trezor/trezor-firmware/commit/222c9ea46c7574cb52d4713c481438a32b85e692#diff-178d0ab7c4debbcf430a0fad8fa06a5c).*
## Building for development
If you want to build device firmware, make sure you have the
[GNU ARM Embedded toolchain](https://developer.arm.com/open-source/gnu-toolchain/gnu-rm/downloads) installed.
You will also need Python 3.5 or later and [pipenv](https://pipenv.readthedocs.io/en/latest/install/).
* If you want to build the emulator instead of the firmware, run `export EMULATOR=1`
* If you want to build with the debug link, run `export DEBUG_LINK=1`. Use this if you want to run the device tests.
* When you change these variables, use `script/setup` to clean the repository
1. To initialize the repository, run `script/setup`
2. To initialize a Python environment, run `pipenv install`
3. To build the firmware or emulator, run `pipenv run script/cibuild`
If you are building device firmware, the firmware will be in `firmware/trezor.bin`.
You can launch the emulator using `firmware/trezor.elf`. To use `trezorctl` with the emulator, use
`trezorctl -p udp` (for example, `trezorctl -p udp get_features`).
Switch your device to bootloader mode, then execute: