Merge branch 'master' of github.com:nerves-project/nerves

docs/Installation.md

@@ -1,49 +1,48 @@
 # Installation
 
-The following is a collection of tools and dependencies required for your system to run Nerves properly. Nerves is actively used on MacOS and various Linux distributions. For Windows users, some people have had success with Linux in VM and the Windows 10 Bash Shell. If you are experiencing issues with any of the tooling, it is important to reference this list to ensure that your system is fully configured to run the Nerves tooling.
+Nerves requires a number of programs on your system to work. These include Erlang, Elixir, and a few other tools for packaging your programs into firmware images. Nerves is actively used on MacOS and various Linux distributions. For Windows users, some people have had success with Linux in VM and the Windows 10 Bash Shell. If you are experiencing issues with any of the tooling, it is important to reference this list to ensure that your system is fully configured to run the Nerves tooling.
 
-## Elixir
+## MacOS
 
-The Nerves build tools and many libraries are written in Elixir and require version `>= 1.2.4`. If you need help installing Elixir, please reference the Elixir [Installation Page](http://elixir-lang.org/install.html).
-
-In addition to Elixir, you will need to fetch dependencies and often compile some Erlang code. Once Elixir is installed you can issue the following commands to install the latest version of both Hex and Rebar
+The easiest installation route on MacOS is to use [Homebrew](brew.sh). Just run the following:
 
 ```
-$ mix local.hex
-$ mix local.rebar
+$ brew update
+$ brew install homebrew/versions/erlang-r19
+$ brew install elixir
+$ brew install fwup squashfs coreutils
 ```
 
-## Erlang
-
-Elixir runs on top of the Erlang VM on your host as well as on your target board. What makes Nerves special is that we replace typical Linux initialization mechanisms like systemd or udev with Erlang. This puts your application in a unique and powerful position of having control over the subsystem initialization as well as your application runtime.
-
-If you followed the instructions from earlier to install Elixir using the instructions found on the Elixir [Installation Page](http://elixir-lang.org/install.html), you should already have Erlang installed.
-
-If you need to install Erlang, it is often best to install using guides and repositories provided by [Erlang Solutions](https://www.erlang-solutions.com/resources/download.html)
+Now skip to the instructions for all platforms below.
 
-## fwup
+## Linux
 
-The fwup utility is a configurable firmware update program. It has two modes of operation. The first mode creates compressed archives containing root file system images, bootloaders, and other image material needed for your target hardware. These can be distributed via websites, email or update servers. The second mode applies these firmware images in a robust and repeatable way.
+We've found quite a bit of variation between Linux distributions. Nerves requires Erlang versions `>= 19.0` and Elixir versions `>= 1.2.4`.
+If you need to install Erlang, see the prebuilt versions and guides provided by [Erlang Solutions](https://www.erlang-solutions.com/resources/download.html)
+For Elixir, please reference the Elixir [Installation Page](http://elixir-lang.org/install.html).
 
-Nerves uses fwup to create, distribute, and install firmware bundles. You can install fwup using the instructions found on the [Installation Page](https://github.com/fhunleth/fwup#installing)
+Next install the `fwup` utility. Nerves uses `fwup` to create, distribute, and install firmware images of your programs. You can install fwup using the instructions found on the [Installation Page](https://github.com/fhunleth/fwup#installing). Installing the prebuilt `.deb` or `.rpm` files is recommended.
 
-## Host Specific tools
+Finally, install `squashfs-tools` using your distribution's package manager. For
+example:
+```
+$ sudo apt-get install squashfs-tools
+```
 
-When finalizing firmware and creating a root filesystem for your target, Nerves utilizes scripts and utilities which have dependencies on the following tools.
+Now continue to the instructions for all platforms below.
 
-`gstat`
-`squashfs-tools`
+## All platforms
 
-For MacOS, these tools can be installed using Homebrew. For more information on how to install homebrew, visit the homebrew [Installation Page](http://brew.sh/)
+It is important to update the versions of `hex` and `rebar` used by Elixir. This is critical even if you didn't need to install Elixir:
 
-Once homebrew is installed, you can install these missing utilities by running the following
 ```
-$ brew install coreutils squashfs
+$ mix local.hex
+$ mix local.rebar
 ```
+If you have your own version of `rebar` in the path, be sure that it is
+uptodate.
 
-## Nerves Bootstrap
-
-With Elixir, Erlang, and your host utilities installed, you can now add the `nerves_bootstrap` archive to your mix environment. This archive allows Nerves to bootstrap the Mix environment, ensuring that your code is properly compiled using the right cross-compiler for the target. The `nerves_bootstrap` archive also includes a new project generator, which you can use to create new Nerves projects. To install the `nerves_bootstrap` archive:
+You can now add the `nerves_bootstrap` archive to your mix environment. This archive allows Nerves to bootstrap the Mix environment, ensuring that your code is properly compiled using the right cross-compiler for the target. The `nerves_bootstrap` archive also includes a new project generator, which you can use to create new Nerves projects. To install the `nerves_bootstrap` archive:
 
 ```
 $ mix archive.install https://github.com/nerves-project/archives/raw/master/nerves_bootstrap.ez

docs/Targets.md

@@ -39,6 +39,24 @@ Targets can be set and persisted several ways.
 
 A Run Level setting will override a Project Level setting, which will override a Global Level setting.
 
+### Example
+
+If you started your nerves project with `mix nerves.new hello_nerves --target rpi3`, and wish to compile for the Raspberry Pi 0, you can do so with:
+
+```
+NERVES_TARGET=rpi mix compile
+NERVES_TARGET=rpi mix firmware
+NERVES_TARGET=rpi mix firmware.burn
+```
+
+These commands will successively compile the code, create the firmware, and burn it to the SD card, for the `rpi` target (which covers the Raspberry Pi 0).
+
+Note: if you want to change the target for the current shell session, you can type: `export NERVES_TARGET=rpi`. For the rest of your shell session, you won't need to type `NERVES_TARGET=rpi` before your commands. If you wish to change the target permanently, you need to edit `mix.exs`.
+
+```
+@target System.get_env("NERVES_TARGET") || "rpi3"
+```
+
 ## Target Dependencies
 
 It is important to note that, although Nerves supports multiple targets for a single application codebase, only one `nerves_system` can be included in a given firmware. Because of this, we recommend taking the following approach for including the system dependency separately from your application dependencies.