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

The machine's settings, which differ from one computer to the next and stay out of what is committed: where
CIRCT is (`CIRCT_BIN`), and the target's own (on the Tang Primer 25K `GOWIN_HOME`, `UART_PORT`, ...).

Each is looked up in order:

  1. the environment variable (`CIRCT_BIN=...`): for CI and one-off overrides;
  2. the application's config, `config :elixir_hls, circt_bin: "..."`: kept out of git in `config/local.exs`, which
     `config/config.exs` imports when it exists (as `mix ehls.new` writes them);
  3. the user's config for every application of the machine, `~/.config/ehls/config.exs` (the same
     `config :elixir_hls, ...`; another file with `EHLS_USER_CONFIG`);
  4. found on the machine, where the setting knows how (`hlstool` on `PATH` for `CIRCT_BIN`);
  5. else not set: the step that needs it stops and says where it looked; `mix ehls.doctor` shows them all.

A path beginning with `~` is expanded.

# `setting`

```elixir
@type setting() :: %{
  key: atom(),
  env: String.t(),
  find: (-&gt; String.t() | nil) | nil,
  doc: String.t()
}
```

A setting: its key in the config, its environment variable, a function finding it on the machine (or nil) and
what it is.

# `cache_dir`

The user's cache, shared by every application of the machine: what the flash holds (`EHLS.Flash`) and what a
target sets up once (`mix ehls.setup`). `~/.cache/ehls` on Linux; another directory with `EHLS_CACHE_DIR`.

# `env`

The environment for a target's scripts: each setting that is set, as its variable.

# `get`

A setting's value by key, or nil.

# `get!`

A setting's value; raises, saying where it looked, when it is not set.

# `lookup`

A setting's value and where it came from (`:env`, `:config`, `:user`, `:found`), or `{nil, nil}`.

# `own`

elixir-hls' own settings.

# `settings`

Every setting of the project: elixir-hls' and its target's.

# `user_config_path`

The user's config file.

---

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