jmgilman / std

The Nix Flakes framework for perfectionists with deadlines [maintainer=@blaggacao]

Standard

Ship today.

Standard is THE opinionated, generic, Nix Flakes framework that will allow you to grow and cultivate Nix Cells with ease. Nix Cells are the fine art of code organization using flakes.

Once your nix code has evolved into a giant ball of spaghetti and nobody else except a few select members of your tribe can still read it with ease; and once to the rest of your colleagues it has grown into an impertinence, then std brings the overdue order to your piece of art through a well-defined folder structure and disciplining generic interfaces.

With std, you'll learn how to organize your nix flake outputs ('Targets') into Cells and Cell Blocks — folded into a useful CLI & TUI to also make the lives of your colleagues easier.

Through more intuition and less documentation, your team and community will finally find a canonical answer to the everlasting question: What can I do with this repository?

---

The std repository itself

In this repository, you'll find, both, the implementation and an application of Standard.

Implementation

What is std? — The well-commented nix code → ./src.

That folder implements:

• std.grow: the "smart" importer
• std.growOn: std.grow-variant that recursively merges all additional variadic arguments
• std.harvest: harvest your Targets into a different shape for compatibility
• std.winnow: when more advanced harvesting is required, use this to harvest and filter the output
• std.pick: pick your Targets into a different shape without system scope
• std.incl: a straight-forward source filter with additive semantics
• std.deSystemize: a helper to hide system from plain sight
• std.<blockType>: builtin (Cell) Block Types that implement (Cell Block Type) Actions

Application

Dog-fooding? → ./cells.

• Cells: ./cells mainly implements std.
• Cell Blocks: std implements:
  • cli;
  • devshellProfiles;
  • nixago; and
  • lib.
• Targets: each Cell Block implements one or various targets.
• Block Type Actions: some Targets expose Actions inferred from the Block Type.

{{#include ../dogfood.nix}}

That's it. std.grow is a "smart" importer of your nix code and is designed to keep boilerplate at bay.

TIP: Now, enter the devshell (direnv allow) and play with the std CLI/TUI companion. It answers one critical question to newcomers and veterans alike:

What can I do with this repository?  

Documentation

Where can I find the documentation? → ./docs.

No, I mean rendered? → The Standard Book.

The documentation is structured around these axes:

	For Study	For Work
The Practice	Tutorials	How-To Guides
The Theory	Explanation	Reference

Licenses

What licenses are used? → ./.reuse/dep5.

And the usual copies? → ./LICENSES.

Releases

You may find releases on the GitHub Release Page of this repository.

Why?

• Why nix?
• Why std?

Examples in the Wild

If you'd like to see some examples of what a Standard project looks like, take a look at the following:

• input-output-hk/bitte-cells
• divnix/hive
• input-output-hk/tullia
• mdbook-kroki-preprocessor
• HardenedNixOS-Profile
• Julia2Nix.jl
• inputs-output-hk/cardano-world

🚧 Work in progress, would like to help us extend this section?

Contributions

Please enter the development environment:

direnv allow

---