Add config

1 files changed, 79 insertions, 0 deletions

diff --git a/README b/README
new file mode 100644
index 000000000000..44dd2a2fc6b5
--- /dev/null
+++ b/README
@@ -0,0 +1,79 @@
+                        ===================
+                        Alyssa's collection
+                        of Nix expressions.
+                        ===================
+
+This is a large collection of Nix expressions.
+
+The primary way to use the expressions is by applying a profile to a
+NixOS or nix-darwin system. See the sys directory for available
+profiles.  A profile can be installed on a system using the `activate'
+script.
+
+These profiles are structured in a way that is very different to NixOS
+configurations in several respects.  First, rather than setting NIX_PATH
+to a mutable tree, these profiles copy the tree into the Nix store at
+build time, then set NIX_PATH to point to that.  This means that
+angle-bracket path syntax (e.g. <nixpkgs>) points to exactly the
+expression that it pointed to when the system was built.  To use a
+mutable working tree in Nix expressions, relative or absolute paths can
+be used instead.  Another advantage of doing things this way is that the
+Nix expressions used to build a given system can always be recovered
+from the Nix store, since they will be a dependency of the system
+derivation.
+
+Another important difference is how programs are configured.  Typically,
+programs are configured on NixOS using modules, but this approach can
+only support a single, system-level configuration for a program.  It is
+desirable to be able to be able to configure a program on a per-user
+basis, or even to allow a user to instantiate multiple versions of the
+same program, with different configurations.  Rather than the module
+approach, these expressions use utility functions to create small
+wrapper programs that apply the desired configuration by setting the
+appropriate command line flag or environment variable, then exec into
+the program itself.  Creating multiple instances of the same program is
+then trivial, by using two different invocations of the helper function.
+The configured programs are defined in the config directory, and the
+aforementioned utility functions are available in config/tools.nix.  The
+configured packages are added to Nixpkgs under the pkgsConfigured
+attribute; defined in nixpkgs-overlays/zzzzzz-config/default.nix.
+
+Whereas NixOS configurations are typically made up of configuration
+files along with seperate repositories or channels for Nixpkgs (and
+possibly some overlays), here a single tree is used.  This means that
+version control history will always be able to identify which version
+of Nixpkgs is compatible with which version of the configuration files,
+while also allowing custom downstream changes to be made to Nixpkgs.
+No other approach provides both of these features in such a convenient
+way.  With the exception of some custom modifications, any upstream
+trees (Nixpkgs, various overlays) are left intact in the tree, for ease
+of patch generation against those upstream trees.  The structure of the
+tree is deliberately designed so that it can be used as a single entry
+in a NIX_PATH.  <nixpkgs> will automatically point to the nixpkgs
+subdirectory, and it will automatically load the overlays in the
+nixpkgs-overlays subdirectory through <nixpkgs-overlays>.  Other
+structures would be possible, but only this one has this feature, and so
+it made sense to choose it.
+
+In constrast to NixOS, an attempt is made here to assist with per-user
+application state management through the `home' module.  This module
+allows activation scripts to be defined on a per-directory basis inside
+a user's home.  For programs like gpg, which require configuration files
+to be in the same directory as mutable program state, this approach
+allows configuration to be stored read-only in the Nix store, and then
+symlinked into the state directory, allowing this type of program to
+still realise some of the benefits of Nix-based configuration.  However,
+unlike other forms of program configuration as described above, this
+can't simply be done by wrapping a program (at least, without increasing
+the startup time of a program too much), and so a module has to be used.
+These modules are, by convention, stored in the appropriate subdirectory
+of the config directory, rather than in the modules directory, so that
+all program-specific configuration for a particular program lives in one
+place.
+
+Note: MIT license does not apply to the packages built by Nixpkgs,
+merely to the package descriptions (Nix expressions, build scripts, and
+so on). It also might not apply to patches included in the tree, which
+may be derivative works of the packages to which they apply. The
+aforementioned artifacts are all covered by the licenses of the
+respective packages.