derivation {
  # derivations need a human-readable name to affix to the end of their path
  name = "foo";

  # they can only be built on a system that matches a given platform specifier
  system = "x86_64-linux";

  # when a derivation is built, an executable called a builder is copied to the
  # store and executed to produce the output
  builder = ./builder.sh;

  # optionally, commandline arguments can be passed to the builder
  args = [ "--do-the-thing" ];

  # by default, the builder is provided with an environment variable called `out`.
  # it's the location it should produce its output at, which corresponds to
  # `/nix/store/<hash>-<name>`
  #
  # optionally, you can supply a list of environment variables to use as outputs
  # instead, which each correspond to `/nix/store/<hash>-<name>-<output>`
  outputs = [ "bin" "lib" "doc" ];

  # any other attribute is simply converted to string and provided to the builder
  # as an environment variable.
  #
  # these attributes are converted to strings, mostly as if passed to `toString`,
  # however:
  #
  # - paths are *copied to the store* as if string interpolated
  #
  # - derivations are automatically built when this one is, so their output paths
  #   are guaranteed to exist
  #
  # this is useful for passing in all the paths to sources, dependencies, etc.
  # needed for the build, e.g.
  src = /path/to/source;
  some-dependency = dependency-derivation;
}

let drv = derivation { /* ... */ }; in [
  # the string "derivation"
  drv.type

  # the original input set
  drv.drvAttrs

  # the store path for the derivation, `/nix/store/<hash>-<name>.drv`,
  # which doesn't exist until this attribute is accessed or the derivation is built
  drv.drvPath

  # the name of the output path (e.g. "out")
  drv.outputName

  # the output path as a string, which may not exist until the derivation is built
  drv.outPath

  # in the case of derivations with multiple outputs, the `outputName` and `outPath`
  # will only represent *the first one* in the list. if you want to access the
  # other output paths, you can first supply the output name as an attribute
  drv.lib.outputName # = "lib"
  drv.lib.outPath

  # you can also access a list of all of these output variants of the derivation
  # with `drv.all`
  (builtins.head drv.all).outPath
]

stdenv.mkDerivation {
  # it's sometimes useful to be able to access a package's version string
  # on its own, so here it can be defined seperately from the package name.
  # the derivation's `name` will automatically be set to `"${pname}-${version}"`
  pname = "foo";
  version = "1.0";


  # instead of writing our own builder, a number of environment variables may be
  # passed to the builder script in order to control its behaviour, many of which
  # are explained below.

  ## Dependencies
  # setup.sh does automatic dependency configuration (taking care of PATH,
  # LD_LIBRARY_PATH etc. for you), and introduces the concept of Autoconf-style
  # platforms to express different kinds of dependencies more specifically.
  #
  #
  # for the purposes of setup.sh's dependency system:
  #   a derivation is built on its *build platform*,
  #   producing an output that runs on its *host platform*,
  #   and its output may itself produce output that runs on its *target platform*.
  #
  # the "target" platform is only relevant when a derivation produces something
  # like a compiler; most software doesn't itself produce platform-specific code.
  #
  # as such, we normally only care about build-time versus run-time dependencies:
  # whether a dependency runs on its dependent's build platform (which we will
  # notate as `build -> *`), or its host platform (`host -> *`).
  #
  # for this, we only need to know two dependency types:

  # `build -> host`, a build-time dependency
  nativeBuildInputs = ... ;

  # `host -> target`, a run-time dependency
  buildInputs = ... ;

  # but if we *are* building something like a cross-compiler and we really do
  # care about the target platform of a dependency, we can also use the
  # following (the platform after the arrow is the *dependency's target*):

  # `build -> build`
  depsBuildBuild = ... ;

  # `build -> target`
  depsBuildTarget = ... ;

  # `host -> host`
  depsHostHost = ... ;

  # `target -> target`
  depsTargetTarget = ... ;


  # sometimes, when a derivation is used as a dependency, one of its own
  # dependencies should be *propagated* to its dependent, as if the dependent
  # also has that dependency.
  #
  # in this case, we can use the propagated variants of the attributes:

  propagatedNativeBuildInputs = ... ;
  propagatedBuildInputs = ... ;

  depsBuildBuildPropagated = ... ;
  depsBuildTargetPropagated = ... ;
  depsHostHostPropagated = ... ;
  depsTargetTargetPropagated = ... ;

  # when these dependencies are propagated, we have to consider not just what
  # type of dependency they are to us, but also what type of dependency we are to
  # our dependent!
  #
  # once again, if you only care about the two common types of dependencies,
  # all you'll need to know is this:
  # `                                                   will be seen by
  # | this type                   | propagated by     | the dependent as  |
  # +-----------------------------+-------------------+-------------------+
  # | propagatedBuildInputs       | buildInputs       | buildInputs       |
  # | propagatedBuildInputs       | nativeBuildInputs | nativeBuildInputs |
  # | propagatedNativeBuildInputs | buildInputs       | nativeBuildInputs |
  # | propagatedNativeBuildInputs | nativeBuildInputs | NOT PROPAGATED    |
  # ` 
  # however, the full algorithm for determining the types of propagated
  # dependencies is described below if you really really need it.
  # this is advanced stuff, folks!


  # if we think of each platform as some integer offset from the dependent's host
  # platform, we can say that build = -1, host = 0, target = 1.
  #
  # then, as if using the following function:
  #
    f = host: target: input: = if input == 1 then target else host - input ;
  #
  # if our dependent sees us as the type `host -> target`,
  # and we see our propagated dependency as the type `p-host -> p-target`,
  # then our dependent will see that propagated dependency as the type
  # `f host target p-host -> f host target p-target`.
  #
  #
  # for example,
  #
  # a `nativeBuildInputs` (`-1 -> 0`)
  # with a `propagatedBuildInputs` (`0 -> 1`)
  # will propagate the latter to its dependent as if it were
  # a `f -1 0 0 -> f -1 0 1`, i.e. a `-1 -> 0`, another `nativeBuildInputs`!
  #
  # whereas a `depsBuildBuild` (`-1 -> -1`)
  # with a `depsBuildTargetPropagated` (`-1 -> 1`)
  # would hypothetically propagate to its dependent as if it were
  # a `f -1 -1 -1 -> f -1 -1 1`, i.e. a `-2 -> -1`,
  # but platform offsets outside the range `[-1, 1]` don't make sense, so it's
  # never propagated at all!


  # further reading in Specifying dependencies (nixpkgs manual)

  ## Fetchers
  # fetchers are simple derivations that produce files from some external source,
  # like the source code for some software you're building.
  #
  # they're known as *fixed-output* derivations, because we can't make guarantees
  # about the purity of the output from an external source (someday the same
  # URL might serve something different, or corruption will cause the output to
  # differ), so we need to specify the expected output's hash in advance.

  # one example of a fetcher is `fetchurl`, which simply downloads a file
  src = fetchurl {
    url = "https://www.example.com/v${version}/download";
    hash = "sha256-47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=";
  };
  # (defined here)

  # more specialized fetchers exist, too, like ones for specific git services:
  src = fetchFromGitHub {
    owner = "example";
    repo = "test";
    rev = "v1.0"; # can be a commit hash or a tag
    hash = "sha256-47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=";
  };
  # (defined here)

  # for more complicated fetchers like this, it can be difficult to know the hash
  # of the file in advance. don't worry, though: if the derivation fails, nix
  # will tell you what hash it expected. it's common to fill in a dummy hash
  # and let it fail, so that nix will tell you what you actually need to put in.

  # most of the important fetchers implemented in nixpkgs are listed in
  # Fetchers (nixpkgs manual)

  ## Phases
  # when the derivation is built, it goes through a series of phases, by default
  # the following:
  phases = [
    prePhases
    "unpackPhase" "patchPhase"
    preConfigurePhases "configurePhase"
    preBuildPhases "buildPhase" "checkPhase"
    preInstallPhases "installPhase"
    preFixupPhases "fixupPhase" "installCheckPhase"
    preDistPhases "distPhase"
    postPhases
  ];
  # you shouldn't overwrite this attribute yourself, but you *can* set the
  # `pre...Phases` and `postPhases` attributes in that list if you want to add
  # more phases.


  # each phase is a bash snippet that performs some action to process the input
  # and produce the output.
  #
  # they have too many options to list here, but they're described extensively in
  # Controlling phases (nixpkgs manual).
  #
  # you can also read the `...Phase()` function for each phase in setup.sh
  # if you want to know exactly how they're defined.

  # the gist of it is, by default:
  #
  # - `unpackPhase` unpacks the `src` (and/or the list of paths `srcs`) or
  #   just copies it if it's already a directory, then `cd`s into that directory
  #
  # - `patchPhase` applies diff patches in the list `patches` (which is
  #   initially empty, making it a no-op by default)
  #
  # - `configurePhase` runs `./configure` if present
  #
  # - `buildPhase` runs `make` if Makefile present
  #
  # - `checkPhase` runs `make check` if Makefile and `check` target present,
  #   only if `doCheck = true`
  #
  # - `installPhase` creates the directory `$prefix` (which defaults to `$out`)
  #   and then runs `make install`
  #
  # - `fixupPhase` is mainly a vessel for miscellaneous post-processing hooks;
  #   it runs the `fixupOutput` hooks for each output:
  #     - `strip` binaries,
  #     - patch RPATHs and shebangs to refer to nix store paths of `host -> *`
  #       dependencies,
  #     - automatically move stuff around to sensible locations,
  #     - etc etc
  #   and adds the hook scripts in `setupHook`/`setupHooks` to
  #   `$dev/nix-support/setup-hook` so they can be propagated to your dependents
  #
  # - `installCheck` runs `make installcheck` if Makefile and
  #   `installcheck` target present, only if `doInstallCheck = true`
  #
  # - `distPhase` runs `make dist` and copies source tarballs to `$out/tarballs`,
  #   only if `doDist = true`
  

  # you can replace the default actions by overwriting 
  # the `...Phase` attribute with your own string containing a bash snippet
  #
  # like, let's say if the program you're installing doesn't have an `install`
  # target in its makefile, but instead has a little install script you can run:
  installPhase = ''
    ./install $out
    # success!
  '';

  ## Setup Hooks
  # if you choose, each phase also includes *setup hooks* that allow you to
  # extend the phase with additional code without replacing it entirely.
  #
  # hooks can be added by name as attributes in your derivation, or they can be
  # added by your dependencies: if a dependency consists of just a file, or a
  # directory that contains the file `nix-support/setup-hook`, that file is
  # sourced by the setup script.
  # 
  # makeSetupHook is a helpful shortcut for making your own setup hook derivations.
  #
  # from there, the file may modify the setup script, typically by adding a hook
  # to one of its arrays like so:
  #
  #   ```
  #   # the array for the 'preFixup' hook
  #   preFixupHooks+=(_myFixupHook)
  #
  #   _myFixupHook () {
  #     do-cool-stuff --to $out
  #   }
  #   ```
  #
  # keep in mind that the runHook calls are inside the phase functions themselves.
  # e.g. if you replace `installPhase`, you have to include `runHook preInstall`
  # and `runHook postInstall` yourself if you want them to happen during your
  # custom `installPhase`.

  # `mkDerivation` contains several setup hooks by default in order to provide
  # a variety of conveniences.
  #
  # they're described in Package setup hooks (nixpkgs manual) and defined in
  # `nixpkgs/pkgs/build-support/setup-hooks/`

  ## Meta
  # this attribute is optional and not passed to the builder, but it contains
  # static information that may be displayed and used by external tools.
  meta = let
    inherit (lib) licenses maintainers;
  in {
    # package information is useful to display by nix and by other search tools
    description = "A short description of the package";
    longDescription = ''
      A more detailed, arbitrarily long description of the package.
      It should be able to span multiple lines.
    '';
    homepage = "https://www.example.com";
    maintainers = [ maintainers.example ];
    # nixpkgs will restrict packages with unfree licenses if configured to do so
    license = licenses.mit;

    # there are several more defined attributes you can put in this set,
    # described in Standard meta-attributes (nixpkgs manual)
  };

  # `passthru` contains attributes that also aren't passed to the builder, but
  # appear on the derivation value as if they were. they can be used for
  # anything that you don't want to trigger a rebuild when changed.
  passthru = {
    # commonly, it may contain an attribute `tests`, containing a set of
    # derivations which may be built to see if they succeed.
    tests = {
      test = /*...*/ ; # Testers (nixpkgs manual)
    };
    # Tests (nixpkgs manual)

    # or an update script, which is used with the maintainer tool
    # `maintainers/scripts/update.nix`, and is given the env var
    # `UPDATE_NIX_ATTR_PATH` pointing to the attribute path to be updated.
    updateScript = ./update.sh;
    # or
    updateScript = [ ./update.sh "--with-args" ];
    # Special variables (nixpkgs manual)
  };
}

# overrideAttrs accepts a function with two arguments:
# `super` is the "old" set of attributes we're about to change,
# and `self` is the "final" set of attributes that will exist after all overrides
# are applied.
#
# the function should return a set of the attributes you want added/changed.
drv.overrideAttrs (self: super: {
  version = super.version + "-raccoon";
  src = ./extra-special-raccoon-fork;
})

# you can also pass a one-argument function to overrideAttrs, in which case
# it'll just receive `super`

# in package functions, we specify dependencies as set attributes on our input
#
# when your package is called, they'll be filled in with derivations
# corresponding to other packages in Nixpkgs.
{
  # the Nixpkgs standard library. this isn't a derivation, but a set of useful
  # functions and constants inside `nixpkgs/lib/` that every package has access to
  lib,

  # this is our stdenv derivation, located at `nixpkgs/pkgs/stdenv/generic/`
  stdenv,

  # and these are some useful fetchers, discussed earlier
  fetchurl, fetchFromGitHub,

  # additionally, you can specify configuration options in this set that can be
  # modified to create different variants of the derivation
  enableFoo ? false
}:
stdenv.mkDerivation { /* ... */ }

drv.override {
  enableFoo = true;
}