docs: do not ignore build subdirectory

core/docs/.gitignore

@@ -1 +1,2 @@
-book
+book
+!build/

core/docs/build/embedded.md

@@ -0,0 +1,52 @@
+# Build instructions for Embedded (ARM port)
+
+First clone, initialize submodules and install Pipenv as defined [here](index.md).
+
+## Requirements
+
+You will need the GCC ARM toolchain for building and OpenOCD for flashing to a device.
+You will also need Python dependencies for signing.
+
+### Debian/Ubuntu
+
+```sh
+sudo apt-get install scons gcc-arm-none-eabi libnewlib-arm-none-eabi
+```
+
+### OS X
+
+1. Download [gcc-arm-none-eabi](https://developer.arm.com/open-source/gnu-toolchain/gnu-rm/downloads)
+2. Follow the [install instructions](https://launchpadlibrarian.net/287100883/readme.txt)
+3. To install OpenOCD, run `brew install open-ocd`
+4. Run `pipenv run make vendor build_boardloader build_bootloader build_firmware`
+
+## Building
+
+```sh
+pipenv run make vendor build_boardloader build_bootloader build_firmware
+```
+
+## Uploading
+
+Use `make upload` to upload the firmware to a production device. Do not forget to [enter bootloader](https://wiki.trezor.io/User_manual-Updating_the_Trezor_device_firmware__TT) on the device beforehand.
+
+## Flashing
+
+For flashing firmware to blank device (without bootloader) use `make flash`,
+or `make flash STLINK_VER=v2-1` if using a ST-LINK/V2.1 interface.
+You need to have OpenOCD installed.
+
+## Building in debug mode
+
+You can also build firmware in debug mode to see log output or run tests. To avoid building firmware in debug mode accidentally, we do not provide a _make_ target. You need to rewrite `PYOPT` variable to `0` in `SConscript.firmware` file and then build the same way. The change is intentionally not _gitignored_.
+
+```sh
+sed -i "s/^PYOPT = '1'$/PYOPT = '0'/" SConscript.firmware
+pipenv run make build_firmware
+```
+
+You can then use `screen` to enter the device's console. Do not forget to add your user to the `dialout` group or use `sudo`. Note that both the group and the tty name can differ, use `ls -l` to find out proper names on your machine.
+
+```sh
+screen /dev/ttyACM0
+```

core/docs/build/emulator.md

@@ -0,0 +1,76 @@
+# Build instructions for Emulator (Unix port)
+
+First clone, initialize submodules and install Pipenv as defined [here](index.md).
+
+## Dependencies
+
+Install the required packages, depending on your operating system.
+
+* __Debian/Ubuntu__:
+
+```sh
+sudo apt-get install scons libsdl2-dev libsdl2-image-dev
+```
+
+* __Fedora__:
+
+```sh
+sudo yum install scons SDL2-devel SDL2_image-devel
+```
+
+* __OpenSUSE__:
+
+```sh
+sudo zypper install scons libSDL2-devel libSDL2_image-devel
+```
+
+* __Arch__:
+
+```sh
+sudo pacman -S scons sdl2 sdl2_image
+```
+
+* __NixOS__:
+
+There is a `shell.nix` file in the root of the project. Just run the following **before** entering the `core` directory:
+
+```sh
+nix-shell
+```
+
+* __Mac OS X__:
+
+```sh
+brew install scons sdl2 sdl2_image pkg-config
+```
+
+* __Windows__: not supported yet, sorry.
+
+## Build
+
+Run the build with:
+
+```sh
+pipenv run make build_unix
+```
+
+## Run
+
+Now you can start the emulator:
+
+```sh
+./emu.sh
+```
+
+The emulator has a number of interesting features all documented in the [Emulator](../emulator/index.md) section.
+
+## Building for debugging and hacking in Emulator (Unix port)
+
+Build the debuggable unix binary so you can attach the gdb or lldb.
+This removes optimizations and reduces address space randomization.
+Beware that this will significantly bloat the final binary
+and the firmware runtime memory limit HEAPSIZE may have to be increased.
+
+```sh
+DEBUG_BUILD=1 make build_unix
+```

core/docs/build/index.md

@@ -0,0 +1,25 @@
+# Build
+
+Run the following to checkout the project:
+
+```sh
+git clone --recursive https://github.com/trezor/trezor-firmware.git
+cd trezor-firmware/core
+```
+
+If you are building from an existing checkout, don't forget to use the following to refresh the submodules:
+
+```sh
+make vendor
+```
+
+After this you will need to install some software dependencies based on what flavor of Core you want to build. You can either build the Emulator or the actual firmware running on ARM devices. Emulator (also called _unix_ port) is a unix version that can run on your computer. See [Emulator](../emulator/index.md) for more information.
+
+## Pipenv
+
+We use [Pipenv](https://docs.pipenv.org/en/latest/) to install and track Python dependencies. You need to install it, sync the packages and then use `pipenv run` for every command or enter `pipenv shell` before typing any commands.
+
+```sh
+sudo pip3 install pipenv
+pipenv sync
+```