<!--
  SPDX-FileCopyrightText: 2017 Michael Schmidt
  SPDX-FileCopyrightText: 2018 Connor Rigby
  SPDX-FileCopyrightText: 2018 Justin Schneck
  SPDX-FileCopyrightText: 2020 Kian-Meng, Ang
  SPDX-License-Identifier: CC-BY-4.0
-->
# Nerves Internals

The nerves bootstrapping process has several steps.  Its goal is to locate
the "system", compile it, and use the compiled system to setup the cross
compile environment.

## Call Tree

Below is a brief sketch of the call tree for the bootstrap.  It is intended
to be a "10,000 ft" overview.

### mix firmware
* alias
  * nerves.precompile
    * NERVES_PRECOMPILE = 1
    * Mix.Tasks.Nerves.Env
      * Mix.Tasks.Deps.Loadpaths.run ["--no-compile"]
      * Mix.Tasks.Deps.Compile.run ["nerves", "--include-children"]
      * Nerves.Env.start()
        * load_packages()
            * Mix.Project.deps_paths
              * Package.config_path
              * Package.load_config
                * build_runner()
              * validate_packages()
    * Mix.Tasks.Deps.Compile Nerves.Env.system.app
    * Mix.Tasks.Compile.run(--no-deps-check) Only if parent == system_app
    * NERVES_PRECOMPILE = 0
    * Mix.Tasks.Nerves.Loadpaths.run()
      * Mix.task.run(nerves.env) Nerves.Env
        * Nerves.Env.start() ?? See above
      * Nerves.Env.bootstrap()
        * system_path()
          * Nerves.Env.system()
            * Nerves.Artifact.dir()
              * System.get_env(env_var(pkg)) NERVES_SYSTEM
        * toolchain_path()
          * Nerves.Env.toolchain()
            * Nerves.Artifact.dir()
              * System.get_env(env_var(pkg)) NERVES_TOOLCHAIN
        * platform.bootstrap(pkg) Nerves.Env.system.platform ||Nerves.Env.system.config[:build_platform]
          * nerves_env.exs Nerves.System.BR
  * deps.precompile

### nerves_package
  * Nerves.Env.start
  * Nerves.Env.enabled? and Nerves.Artifact.stale?(package)
    * Nerves.Package.artifact(package, toolchain)
      * pkg.build_runner.artifact(pkg, toolchain, opts) [Nerves.Artifact.BuildRunners.HTTP, Nerves.Artifact.BuildRunners.Local]
* firmware

## Key Files/Variables

The following are the key parts of the bootstrap.  Note that NERVES_SYSTEM and
NERVES_TOOLCHAIN can be defined before running `mix firmware` to point to a
trusted decompressed system or toolchain. This is useful in situations where
you produce a system directly using Buildroot and want to force Nerves to use it.

### NERVES_SYSTEM
  * Path to the `nerves_system_*` folder
  * Has to be defined at Nerves.Env.bootstrap() or system blows up
  * Exists only if the system dependency is being included from a source other than hex.
    * When a system is being sourced from hex, it will attempt to place the uncompressed artifact in the global path located at ~/.nerves/artifacts or $NERVES_ARTIFACTS_DIR

### NERVES_TOOLCHAIN
  * Path to the toolchain
  * Has to defined at Nerves.Env.bootstrap() or systems blows up

### nerves_env.exs
  * Sets the cross compile flags
  * NERVES_SYSTEM and NERVES_TOOLCHAIN must be defined prior
  * Everything run after will try to cross compile

### nerves_system/.nerves/artifacts/nerves_system_*
   * "package" directory
   * Gets fetched from nerves_env.exs artifact_sites