# Oceanbox Nixpkgs

`obx-pkgs` is the shared Oceanbox Nix overlay. It collects packages that we use
across projects but that are either not in nixpkgs, are stuck on an outdated
version, or need internal patches. Each project that consumes the overlay gets
the same versions, the same fixes, and a single place to update them.

## Usage

### As an overlay on nixpkgs (recommended)

With `npins`:

```nix
{
  sources ? import ./npins,
  pkgs ? import sources.nixpkgs {
    overlays = [ (import "${sources.obx-pkgs}/overlay.nix") ];
  },
}:
# pkgs.arcosparse, pkgs.openzl, pkgs.sphinx-shibuya-theme, ... are now available
```

With `flakes`:

```nix
{
  inputs.obx-pkgs.url = "git+https://git.oceanbox.io/oceanbox/obx-pkgs";

  outputs = { nixpkgs, obx-pkgs, ... }: {
    legacyPackages.x86_64-linux = import nixpkgs {
      system = "x86_64-linux";
      overlays = [ obx-pkgs.overlays.default ];
    };
  };
}
```

### As a standalone package set

```nix
let
  obx = import sources.obx-pkgs { };
in
  [ obx.copernicusmarine obx.sz3 ]
```

Useful when you want one of our packages without modifying the rest
of nixpkgs.

## Adding a package

```text
by-name/
  <package-name>/
    default.nix
```

`default.nix` is a regular `callPackage` function, the same shape you would
write for nixpkgs:

```nix
{ stdenv, fetchFromGitHub, ... }:
stdenv.mkDerivation { ... }
```

Cross-references between our own packages work via the standard argument syntax
name the dependency in the argument list (e.g. `arcosparse`) and the overlay's
`self.callPackage` injects it.

Once the directory exists it is picked up automatically

## Development

```text
nix-shell
```

drops you into a shell with `npins`, `nix-init`, `nix-update`, and a
pre-configured `treefmt`.

Format the tree:

```text
treefmt
```

Update a pin:

```text
npins update nixpkgs
```

Bump a package version:

```text
nix-update -f . <package-name>
```