Nerves.Bootstrap

Nerves.Bootstrap is an Elixir archive that brings Nerves support to Elixir's Mix build tool and provides a new project generator, mix nerves.new.

We recommend reading the Nerves Installation Guide for installing and using Nerves. Read on for details specific to Nerves.Bootstrap.

Installation

The first time you use Nerves and whenever you update your Elixir installation, run the follow to install the official archive:

mix archive.install hex nerves_bootstrap

From then on, Nerves.Bootstrap checks for new versions and will let you know. To manually upgrade either run the above line or the following:

mix local.nerves

If you need to force a specific version, run:

mix archive.install hex nerves_bootstrap 1.0.1

Mix tasks

This section provides a high level overview of Mix tasks provided by Nerves.Bootstrap. For additional details, run mix help task.

mix nerves.new

A mix task for creating new Nerves projects.

mix nerves.new my_project

The generated project will support compilation for all of the officially supported Nerves devices. Just like the Elixir new project generator, nerves.new supports many options to tweak the output.

Generated projects will boot and provide an IEx prompt over the default console for the device. Here's a script for creating a new project and building it for a Raspberry Pi 3:

mix nerves.new my_project
cd my_project

# Set MIX_TARGET to select Raspberry Pi 3-specific dependencies in the mix.exs
export MIX_TARGET=rpi3

# Download dependencies, build firmware and write it to a MicroSD card
mix deps.get
mix firmware
mix burn

Generated projects include NervesPack in their dependency list. NervesPack depends on most of the Nerves-specific libraries that you'll need at the beginning of your project. This includes those needed for networking, firmware updates, and various helpful utilities. If you want a minimal project that does not include NervesPack, pass --no-nerves-pack:

mix nerves.new my_new_nerves_project --no-nerves-pack

mix local.nerves

This task checks hex.pm for updates to the nerves_bootstrap archive. If one exists, you'll be prompted to update.

Integration with your project

Nerves.Bootstrap injects Nerves-specific build tasks into the mix build process via an Application.start/1 call in your project's config.exs. If you use mix nerves.new, your project will be created with these lines and no additional work is needed.

# config/config.exs
import Config

Application.start(:nerves_bootstrap)

Internals

Nerves.Bootstrap uses Mix aliases to hook into Mix build steps.

Aliases vary based on whether you are compiling for your host or your target device. For host builds, Nerves.Bootstrap injects the following tasks to add support for downloading pre-compiled archives.

[
  "deps.get": ["deps.get", "nerves.bootstrap", "nerves.deps.get"],
  "deps.update": ["deps.update", "nerves.bootstrap", "nerves.deps.get"]
]

When MIX_TARGET is set, Nerves.Bootstrap injects the following additional tasks to support cross-compilation and firmware creation:

[
  "deps.loadpaths": ["nerves.bootstrap", "nerves.loadpaths", "deps.loadpaths"],
  "deps.compile": ["nerves.bootstrap", "nerves.loadpaths", "deps.compile"],
  # This is just helper to prevent trying to run tasks on host that were
  # compiled for a target
  run: [Nerves.Bootstrap.Aliases.run/1]
]

Nerves.Bootstrap provides only minimal code to inject the Nerves tooling. The main Nerves tooling is the Nerves library.

Local development

If you need to modify Nerves.Bootstrap, here's what you should do to get the source code, build it and install your changes locally:

git clone https://github.com/nerves-project/nerves_bootstrap.git
cd nerves_bootstrap
mix do deps.get, archive.build, archive.install

License

Copyright (C) 2017-22 Nerves Project Authors

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at [http://www.apache.org/licenses/LICENSE-2.0](http://www.apache.org/l>

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.