===================
                        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.

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' and `xdg' modules.  The
`xdg' module allows creating an immutable XDG_CONFIG_HOME in
/run/current-system, which allows environment.etc-like management of
per-user configuration files, without introducing a new, seperate build
command à la home-manager.  The disadvantage to this approach is that,
unlike home-manager, it assumes that the user has permission to rebuild
the entire NixOS system.  The `home' 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.

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.