path: root/pkgs/stdenv/generic/docs.txt

* genericBuild performs a generic build of (typically) autotool-style
  packages

  
* unpack phase

** may be overriden by setting $unpackPhase to point at a function that
   unpacks the source (which should set $sourceRoot)

** the generic unpacker unpacks all sources specified by $srcs, or
   $src if $srcs is empty

** supports tar, bzipped tar, gzipped tar, compressed tar, zip

** zip must be in scope (in $buildinputs)

** additional file types may be supported by setting $findUnpacker,
   which is called with a single argument specifying the file to be
   unpacked

** $findUnpacker should set $unpackCmd, specifying the full command to
   unpack the file (must include the file name)

** alternatively, $unpackCmd can be set before calling the generic
   builder (e.g., 'unpackCmd="unrar x $src"'); this only works if
   there is a single source file

** the generic unpacker then sets $sourceRoot to the name of the
   directory created by unpacking the source archives

** the source archives should produce only one directory

** alternatively, $setSourceRoot may be set to a function that sets
   $sourceRoot


* the generic builder then chdirs to $sourceRoot


* patch phase (skipped if neither $patchPhase nor $patches are set)

** may be overriden by setting $patchPhase to point at a function that
   unpacks the source (which should set $sourceRoot)

** if the $patches variable is set, it runs `patch -p1 < ...' in
   $sourceRoot for each element in $patches (the `patch' command
   should be in $PATH; note that it isn't in the standard environment)


* configuration phase

** may be overriden by setting $configurePhase to point at a function

** calls $preConfigurer first, if set (useful for running
   autoconf/automake)

** the configure script is specified by $configureScript, which
   defaults to ./configure
   
** if no executable file exists at $configureScript, does nothing

** if a file ./ltmain.sh exists and $dontFixLibtool is not set, calls
   function fixLibtool to remove its default search path (/usr etc.)

** adds "--prefix=$out" to $configureFlags unless $dontAddPrefix is
   set

** calls $configureScript with $configureFlags

** calls $postConfigurer, if set (useful for any last-minute patches
   prior to building)


* build phase

** may be overriden by setting $buildPhase to point at a function

** runs make with flags $makeFlags


* install phase

** may be overriden by setting $installPhase to point at a function

** runs make with flags $installFlags

** unless $dontStrip is set or $NIX_STRIP_DEBUG is not 1, finds all *.a
   files in $out and runs "strip -S" on them (executables and dynamic
   libraries can be stripped automatically by setting NIX_STRIP_DEBUG
   to 1 (default))

** if $propagatedBuildInputs is set, its contents are written to
   $out/nix-support/propagated-build-inputs