From e4077e0634ada44fbeccf8c60f81a8f2e8377c5b Mon Sep 17 00:00:00 2001
From: Tomas Susanka <tsusanka@gmail.com>
Date: Mon, 10 Feb 2020 13:05:41 +0100
Subject: [PATCH] docs/core: improve build section

---
 docs/core/build/embedded.md | 16 +++++++++++++---
 docs/core/build/emulator.md |  6 ++++--
 docs/core/build/index.md    | 22 ++++++++++++++++------
 3 files changed, 33 insertions(+), 11 deletions(-)

diff --git a/docs/core/build/embedded.md b/docs/core/build/embedded.md
index 1b239429b..2e5a8c578 100644
--- a/docs/core/build/embedded.md
+++ b/docs/core/build/embedded.md
@@ -1,6 +1,7 @@
 # Build instructions for Embedded (ARM port)
 
 First clone, initialize submodules and install Pipenv as defined [here](index.md).
+**Do not forget you need to be in a `pipenv shell` environment!**
 
 ## Requirements
 
@@ -13,17 +14,26 @@ You will also need Python dependencies for signing.
 sudo apt-get install scons gcc-arm-none-eabi libnewlib-arm-none-eabi
 ```
 
+### 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
+```
+
 ### 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`
+4. Run `make vendor build_boardloader build_bootloader build_firmware`
 
 ## Building
 
 ```sh
-pipenv run make vendor build_boardloader build_bootloader build_firmware
+make vendor build_boardloader build_bootloader build_firmware
 ```
 
 ## Uploading
@@ -41,7 +51,7 @@ You need to have OpenOCD installed.
 You can also build firmware in debug mode to see log output or run tests.
 
 ```sh
-PYOPT=0 pipenv run make build_firmware
+PYOPT=0 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.
diff --git a/docs/core/build/emulator.md b/docs/core/build/emulator.md
index 1488b986b..3e7a9c8b9 100644
--- a/docs/core/build/emulator.md
+++ b/docs/core/build/emulator.md
@@ -1,6 +1,8 @@
 # Build instructions for Emulator (Unix port)
 
-First clone, initialize submodules and install Pipenv as defined [here](index.md).
+First clone, initialize submodules, install Pipenv and enter the Pipenv shell as 
+defined [here](index.md). **Do not forget you need to be in a `pipenv shell`
+environment!**
 
 ## Dependencies
 
@@ -51,7 +53,7 @@ brew install scons sdl2 sdl2_image pkg-config
 Run the build with:
 
 ```sh
-pipenv run make build_unix
+make build_unix
 ```
 
 ## Run
diff --git a/docs/core/build/index.md b/docs/core/build/index.md
index a7eea4f0b..f1928e490 100644
--- a/docs/core/build/index.md
+++ b/docs/core/build/index.md
@@ -1,25 +1,35 @@
 # Build
 
+## New Project
+
 Run the following to checkout the project:
 
 ```sh
-git clone --recursive https://github.com/trezor/trezor-firmware.git
+git clone --recurse-submodules 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:
+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.
+
+## Existing Project
+
+If you are building from an existing checkout, do not forget to refresh the submodules
+ and the pipenv environment:
 
 ```sh
-make vendor
+git submodule update --init --recursive --force
+pipenv sync
 ```
 
-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.
+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. **The commands in this section suppose you are in a `pipenv shell` environment!**
 
 ```sh
 sudo pip3 install pipenv
 pipenv sync
+pipenv shell
 ```