# `EHLS.Target`
[🔗](https://github.com/elixir-hls/elixir-hls/blob/v0.1.0/lib/ehls/target.ex#L1)

A board an application runs on, as the Mix tasks see it (`mix ehls.build`, `mix ehls.run`, `mix ehls.flash`,
`mix ehls.console`, `mix ehls.doctor`, `mix ehls.setup`): the tasks are elixir-hls', the work is the target's.

A target package (atomvm-tang25k-hls for the Sipeed Tang Primer 25K) has a module with `@behaviour EHLS.Target`;
the tasks find it among the application's dependencies. With several, `config :elixir_hls, target: :tang25k`
picks one by its `c:name/0` (or a module name).

For those writing a target: the callbacks below; the steps of a build are `t:EHLS.Build.step/0`, the machine's
settings `t:EHLS.Machine.setting/0`.

# `part`

```elixir
@type part() :: atom()
```

What a flash part writes: `:vm`, `:lib`, `:bitstream`, `:app`, ...

# `board_gpio`
*optional* 

```elixir
@callback board_gpio() :: Path.t() | nil
```

The board's parts for `EHLS.GPIO` (a JSON file), or nil.

# `checks`
*optional* 

```elixir
@callback checks(EHLS.Project.t()) :: [{String.t(), (-&gt; :ok | {:error, String.t()})}]
```

The target's checks for `mix ehls.doctor`: a label and a function giving `:ok` or `{:error, why}`.

# `console`
*optional* 

```elixir
@callback console(EHLS.Project.t()) :: :ok
```

Shows the board's console until interrupted.

# `flash`

```elixir
@callback flash(EHLS.Project.t(), [part()], keyword()) :: :ok
```

Writes the given parts to the board's flash.

# `flash_images`

```elixir
@callback flash_images(EHLS.Project.t()) :: %{required(part()) =&gt; Path.t()}
```

The files each flash part writes, for the record of what the board holds.

# `name`

```elixir
@callback name() :: atom()
```

The target's name, as `config :elixir_hls, target:` gives it (e.g. `:tang25k`).

# `run`

```elixir
@callback run(EHLS.Project.t(), keyword()) :: :ok
```

Sends the application to the board, starts it and shows its console (options: `seconds:`).

# `run_needs`

```elixir
@callback run_needs() :: [part()]
```

The flash parts a run needs in the board (e.g. `[:vm, :lib]`); `mix ehls.run` writes those that changed.

# `settings`

```elixir
@callback settings() :: [EHLS.Machine.setting()]
```

The machine's settings the target needs besides elixir-hls' own (`EHLS.Machine`).

# `setup`
*optional* 

```elixir
@callback setup(EHLS.Project.t(), keyword()) :: :ok
```

Sets up once what the target's builds need on this machine and is not in the dependencies as Mix fetched them (on
the Tang Primer 25K the base's LiteX, AtomVM and host tools), for `mix ehls.setup` (options: `force: true` to do it
again). Kept outside the application (`EHLS.Machine.cache_dir/0`), so the applications of the machine share it.

# `steps`

```elixir
@callback steps(EHLS.Project.t()) :: [EHLS.Build.step()]
```

The steps of a build, in order (`EHLS.Build`).

# `find`

The target if one is found, else nil (for the compile on the host, which needs none).

# `find!`

The target of the current Mix project: `config :elixir_hls, target:` (a name or a module), else the only target
among the dependencies. Raises when there is none, or several and no choice.

---

*Consult [api-reference.md](api-reference.md) for complete listing*
