# API reference

## default.nix
Evaluate a flake without the flake evaluator. flake-compatish reads
`flake.nix` and `flake.lock` and calls `outputs` itself.

### Inputs

`args`
: A path, or an attrset. A path `p` is short for
  `{ source = p; overrides.self = p; }`, which evaluates `p` in place with
  no store copy.

  `source`
  : The flake to evaluate: a path, or a flake reference string.

  `overrides` (default `{ }`)
  : Input name to a path, used in place, or a flake reference string,
    fetched. `self` names the root. A name that is not `self` or a root
    input is ignored and not evaluated. A path that does not exist falls
    back to the lockfile.

  `overridesFile` (default `source + "/overrides.nix"`)
  : An optional machine-local file of the same shape. It is read only in
    impure evaluation, and it wins over `overrides`.

  `systemOverrides` (default `true`)
  : The machine's overrides, matched by flake reference and not by name,
    at every depth. `true` reads the file the NIX_PATH entry
    `flake-compatish-overrides` names, `false` reads nothing, and a path,
    attrset or function is used instead. Impure evaluation only. It wins
    over `overrides` and loses to the local file.

  `warnOverrides` (default `true`)
  : Print a warning for each override that applies.

  `reroot` (default `{ }`)
  : Input name to an evaluated flake, or to a function from the flake that
    would have been used to its replacement. It applies at every depth.

  `nixpkgsArgs` (default `null`)
  : A function from a system to the arguments for the root `nixpkgs`
    input. The result replaces `self.legacyPackages` in compatible flakes.

Set `FLAKE_COMPATISH_DISABLE_OVERRIDES=1` to ignore `overrides`, the local
file, the system-wide overrides and `reroot`, and evaluate from the
lockfile alone.

### Output

`outputs`
: The root flake, as another flake would see it.

`inputs`
: The root's resolved inputs, and `self`.

`impure`
: `outputs`, with `builtins.currentSystem` selected in each attribute
  that has it.

`compatish`
: The `lib.nix` result for the same evaluation: `override`, `args` and
  `sources`, with strict name checks. Evaluated only when read.

### Examples
#### `default.nix` usage example

```nix
let
  lock = builtins.fromJSON (builtins.readFile ./flake.lock);
  flake-compatish = builtins.fetchTree lock.nodes.flake-compatish.locked;
in
import flake-compatish {
  source = ./.;
  overrides = {
    self = ./.;
    # Not `~/Code/nixpkgs`: pure evaluation rejects `~` while parsing.
    nixpkgs = /. + builtins.getEnv "HOME" + "/Code/nixpkgs";
  };
}
```



## lib.nix
The overridable entrypoint. `default.nix` stays a plain flake-compat shim;
this one returns a result you can override again after import, after
[sprinkles](https://git.afnix.fr/sprinkles/sprinkles).

### `flake-compatish.lib.new`

Evaluate a flake, and return a result that can be overridden again.

The result has the attributes `default.nix` returns, and also:

`args`
: The arguments this result was evaluated with.

`sources`
: The root's inputs as fetched: after `overrides`, before `reroot`.

`override`
: Re-evaluate with changed arguments. An attrset merges into `args`,
  and its `overrides` and `reroot` merge key by key. A function gets
  the previous `args` and returns the attrset to merge with `//`, so it
  can also remove a key.

#### Inputs

`args`
: A path, or an attrset with the arguments `default.nix` takes. Also:

  `strict` (default `true`)
  : Abort on an `overrides` name that is not `self` or a root input,
    and on a `reroot` name that no flake in the graph declares.
    `default.nix` ignores such names; here they are typos until proved
    otherwise. A local `overrides.nix` is never checked, because it is
    the machine's and not the project's.

A `reroot` value can be a function. It gets the flake that would have
been used, and returns the one to use instead.

#### Examples
##### `new` usage example

```nix
let
  fc = import "${flake-compatish}/lib.nix";
  flake = fc.new ./.;
in
(flake.override { overrides.nixpkgs = /. + builtins.getEnv "HOME" + "/Code/nixpkgs"; })
  .impure.packages.default
```



## nix/core.nix
The evaluator behind both entrypoints. Internal: the public interface is
`default.nix` and `lib.nix`.

`default.nix` returns `compat`. `nix/overridable.nix` also reads the
attributes beside it.

### Inputs

`args`
: A path, or the attrset `default.nix` documents.

### `flake-compatish.core.compat`

What `default.nix` returns, without `compatish`: `inputs`, `outputs` and
`impure`.

### `flake-compatish.core.args`

The arguments as an attrset. A path argument becomes
`{ source = path; overrides.self = path; }`.

### `flake-compatish.core.overrideNames`

The names `overrides` accepts: `self` and the root's inputs.

### `flake-compatish.core.rerootNames`

The names `reroot` accepts: every input name declared anywhere in the
graph.

### `flake-compatish.core.sources`

The root's inputs as fetched, after `overrides` and before `reroot`.


## nix/overridable.nix
Wraps one core evaluation into the overridable result that `lib.nix`
documents. Internal.

It takes the core's output, not its arguments, so `default.nix` can share
a single evaluation between its own attributes and `compatish`.

### Type

```
overridable :: CoreResult -> AttrSet
```