readme: some hints on what this repo is and does

1 files changed, 32 insertions, 0 deletions

diff --git a/Readme.md b/Readme.md
new file mode 100644
index 0000000..0e40f2a
--- /dev/null
+++ b/Readme.md
@@ -0,0 +1,32 @@
+# stuebinm's nixfiles
+
+this repository contains most of my personal NixOS configuration.
+
+Unless you're me, you're probably not interested in most of it, with the following
+possible exceptions:
+ - `/pkgs` contains several package recipes which are not in `nixpkgs`, and which
+   I don't plan to contribute there. Not all of them are stable or regularly
+   tested, built, or otherwise maintained, but several of them are part of my
+   normal setup. If in doubt, consult the ordering in `pkgs/overlay.nix`, which
+   can give a rough indication.
+   
+   Several of these depend on each other; if you want to use these, it's probably
+   best to import the entire `overlay.nix` file into your nixpkgs; but be aware
+   that it's opinionated in several ways, and some packages also depend on the
+   rust-overlay.
+ - `/modules` contains NixOS modules for a few of the packages in `/pkgs`.
+   You can use these by overlaying the relevant packages into your nixpkgs instance
+   & then importing the module file into your system configuration.
+ - `/tests` contains NixOS VM tests for the things in `/modules`.
+   Run these as `nix-build tests -A <name>`.
+
+In general you're welcome to re-use or import these definitions, but don't
+necessarily except me to continue maintaining anything here (assume the usual
+"this software is provided 'as-is', without warranty of any kind ..." etc.).
+
+More generally, this repository might also server as an example for a
+deterministic NixOS setup with `npins` which does not depend on flakes (beyond
+some hackery to get at the flake-specific definitions of `nixpkgs`, since what I
+do here is still closer to a flake-based setup than it is to a traditional
+channels-based setup).
+