b12f/nixpkgs
1
0
Fork 0
Code Issues Pull requests Packages Projects Releases Wiki Activity

added documentation for makeWrapperArgs

Browse source
This commit is contained in:
Allen Nelson 2015-05-24 22:22:20 -05:00
parent 6bb2e47abf
commit d2cbcc68be
1 changed files with 61 additions and 47 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

108
doc/language-support.xml
View file

@ -245,14 +245,14 @@ are provided with all modules included.</para>
Name of the folder in <literal>${python}/lib/</literal> for corresponding interpreter. Name of the folder in <literal>${python}/lib/</literal> for corresponding interpreter.
</para></listitem> </para></listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term><varname>interpreter</varname></term> <term><varname>interpreter</varname></term>
<listitem><para> <listitem><para>
Alias for <literal>${python}/bin/${executable}.</literal> Alias for <literal>${python}/bin/${executable}.</literal>
</para></listitem> </para></listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term><varname>buildEnv</varname></term> <term><varname>buildEnv</varname></term>
<listitem><para> <listitem><para>
@ -260,29 +260,29 @@ are provided with all modules included.</para>
See <xref linkend="python-build-env" /> for usage and documentation. See <xref linkend="python-build-env" /> for usage and documentation.
</para></listitem> </para></listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term><varname>sitePackages</varname></term> <term><varname>sitePackages</varname></term>
<listitem><para> <listitem><para>
Alias for <literal>lib/${libPrefix}/site-packages</literal>. Alias for <literal>lib/${libPrefix}/site-packages</literal>.
</para></listitem> </para></listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term><varname>executable</varname></term> <term><varname>executable</varname></term>
<listitem><para> <listitem><para>
Name of the interpreter executable, ie <literal>python3.4</literal>. Name of the interpreter executable, ie <literal>python3.4</literal>.
</para></listitem> </para></listitem>
</varlistentry> </varlistentry>
</variablelist> </variablelist>
<section xml:id="build-python-package"><title><varname>buildPythonPackage</varname> function</title> <section xml:id="build-python-package"><title><varname>buildPythonPackage</varname> function</title>
<para> <para>
The function is implemented in <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/python-modules/generic/default.nix"> The function is implemented in <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/python-modules/generic/default.nix">
<filename>pkgs/development/python-modules/generic/default.nix</filename></link>. <filename>pkgs/development/python-modules/generic/default.nix</filename></link>.
Example usage: Example usage:
<programlisting language="nix"> <programlisting language="nix">
twisted = buildPythonPackage { twisted = buildPythonPackage {
name = "twisted-8.1.0"; name = "twisted-8.1.0";
@ -308,27 +308,27 @@ twisted = buildPythonPackage {
<varname>python27Packages</varname>, <varname>python32Packages</varname>, <varname>python33Packages</varname>, <varname>python27Packages</varname>, <varname>python32Packages</varname>, <varname>python33Packages</varname>,
<varname>python34Packages</varname> and <varname>pypyPackages</varname>. <varname>python34Packages</varname> and <varname>pypyPackages</varname>.
</para> </para>
<para> <para>
<function>buildPythonPackage</function> mainly does four things: <function>buildPythonPackage</function> mainly does four things:
<orderedlist> <orderedlist>
<listitem><para> <listitem><para>
In the <varname>configurePhase</varname>, it patches In the <varname>configurePhase</varname>, it patches
<literal>setup.py</literal> to always include setuptools before <literal>setup.py</literal> to always include setuptools before
distutils for monkeypatching machinery to take place. distutils for monkeypatching machinery to take place.
</para></listitem> </para></listitem>
<listitem><para> <listitem><para>
In the <varname>buildPhase</varname>, it calls In the <varname>buildPhase</varname>, it calls
<literal>${python.interpreter} setup.py build ...</literal> <literal>${python.interpreter} setup.py build ...</literal>
</para></listitem> </para></listitem>
<listitem><para> <listitem><para>
In the <varname>installPhase</varname>, it calls In the <varname>installPhase</varname>, it calls
<literal>${python.interpreter} setup.py install ...</literal> <literal>${python.interpreter} setup.py install ...</literal>
</para></listitem> </para></listitem>
<listitem><para> <listitem><para>
In the <varname>postFixup</varname> phase, <literal>wrapPythonPrograms</literal> In the <varname>postFixup</varname> phase, <literal>wrapPythonPrograms</literal>
bash function is called to wrap all programs in <filename>$out/bin/*</filename> bash function is called to wrap all programs in <filename>$out/bin/*</filename>
@ -337,23 +337,23 @@ twisted = buildPythonPackage {
</para></listitem> </para></listitem>
</orderedlist> </orderedlist>
</para> </para>
<para>By default <varname>doCheck = true</varname> is set and tests are run with <para>By default <varname>doCheck = true</varname> is set and tests are run with
<literal>${python.interpreter} setup.py test</literal> command in <varname>checkPhase</varname>.</para> <literal>${python.interpreter} setup.py test</literal> command in <varname>checkPhase</varname>.</para>
<para><varname>propagatedBuildInputs</varname> packages are propagated to user environment.</para> <para><varname>propagatedBuildInputs</varname> packages are propagated to user environment.</para>
<para> <para>
By default <varname>meta.platforms</varname> is set to the same value By default <varname>meta.platforms</varname> is set to the same value
as the interpreter unless overriden otherwise. as the interpreter unless overriden otherwise.
</para> </para>
<variablelist> <variablelist>
<title> <title>
<varname>buildPythonPackage</varname> parameters <varname>buildPythonPackage</varname> parameters
(all parameters from <varname>mkDerivation</varname> function are still supported) (all parameters from <varname>mkDerivation</varname> function are still supported)
</title> </title>
<varlistentry> <varlistentry>
<term><varname>namePrefix</varname></term> <term><varname>namePrefix</varname></term>
<listitem><para> <listitem><para>
@ -363,7 +363,7 @@ twisted = buildPythonPackage {
if you're packaging an application or a command line tool. if you're packaging an application or a command line tool.
</para></listitem> </para></listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term><varname>disabled</varname></term> <term><varname>disabled</varname></term>
<listitem><para> <listitem><para>
@ -373,21 +373,21 @@ twisted = buildPythonPackage {
for examples. for examples.
</para></listitem> </para></listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term><varname>setupPyInstallFlags</varname></term> <term><varname>setupPyInstallFlags</varname></term>
<listitem><para> <listitem><para>
List of flags passed to <command>setup.py install</command> command. List of flags passed to <command>setup.py install</command> command.
</para></listitem> </para></listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term><varname>setupPyBuildFlags</varname></term> <term><varname>setupPyBuildFlags</varname></term>
<listitem><para> <listitem><para>
List of flags passed to <command>setup.py build</command> command. List of flags passed to <command>setup.py build</command> command.
</para></listitem> </para></listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term><varname>pythonPath</varname></term> <term><varname>pythonPath</varname></term>
<listitem><para> <listitem><para>
@ -396,21 +396,21 @@ twisted = buildPythonPackage {
(contrary to <varname>propagatedBuildInputs</varname>). (contrary to <varname>propagatedBuildInputs</varname>).
</para></listitem> </para></listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term><varname>preShellHook</varname></term> <term><varname>preShellHook</varname></term>
<listitem><para> <listitem><para>
Hook to execute commands before <varname>shellHook</varname>. Hook to execute commands before <varname>shellHook</varname>.
</para></listitem> </para></listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term><varname>postShellHook</varname></term> <term><varname>postShellHook</varname></term>
<listitem><para> <listitem><para>
Hook to execute commands after <varname>shellHook</varname>. Hook to execute commands after <varname>shellHook</varname>.
</para></listitem> </para></listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term><varname>distutilsExtraCfg</varname></term> <term><varname>distutilsExtraCfg</varname></term>
<listitem><para> <listitem><para>
@ -419,15 +419,29 @@ twisted = buildPythonPackage {
configuration). configuration).
</para></listitem> </para></listitem>
</varlistentry> </varlistentry>
<varlistentry>
<term><varname>makeWrapperArgs</varname></term>
<listitem><para>
A list of strings. Arguments to be passed to
<varname>makeWrapper</varname>, which wraps generated binaries. By
default, the arguments to <varname>makeWrapper</varname> set
<varname>PATH</varname> and <varname>PYTHONPATH</varname> environment
variables before calling the binary. Additional arguments here can
allow a developer to set environment variables which will be
available when the binary is run. For example,
<varname>makeWrapperArgs = ["--set FOO BAR" "--set BAZ QUX"]</varname>.
</para></listitem>
</varlistentry>
</variablelist> </variablelist>
</section> </section>
<section xml:id="python-build-env"><title><function>python.buildEnv</function> function</title> <section xml:id="python-build-env"><title><function>python.buildEnv</function> function</title>
<para> <para>
Create Python environments using low-level <function>pkgs.buildEnv</function> function. Example <filename>default.nix</filename>: Create Python environments using low-level <function>pkgs.buildEnv</function> function. Example <filename>default.nix</filename>:
<programlisting language="nix"> <programlisting language="nix">
<![CDATA[with import <nixpkgs> {}; <![CDATA[with import <nixpkgs> {};
@ -436,31 +450,31 @@ python.buildEnv.override {
ignoreCollisions = true; ignoreCollisions = true;
}]]> }]]>
</programlisting> </programlisting>
Running <command>nix-build</command> will create Running <command>nix-build</command> will create
<filename>/nix/store/cf1xhjwzmdki7fasgr4kz6di72ykicl5-python-2.7.8-env</filename> <filename>/nix/store/cf1xhjwzmdki7fasgr4kz6di72ykicl5-python-2.7.8-env</filename>
with wrapped binaries in <filename>bin/</filename>. with wrapped binaries in <filename>bin/</filename>.
</para> </para>
<variablelist> <variablelist>
<title> <title>
<function>python.buildEnv</function> arguments <function>python.buildEnv</function> arguments
</title> </title>
<varlistentry> <varlistentry>
<term><varname>extraLibs</varname></term> <term><varname>extraLibs</varname></term>
<listitem><para> <listitem><para>
List of packages installed inside the environment. List of packages installed inside the environment.
</para></listitem> </para></listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term><varname>postBuild</varname></term> <term><varname>postBuild</varname></term>
<listitem><para> <listitem><para>
Shell command executed after the build of environment. Shell command executed after the build of environment.
</para></listitem> </para></listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term><varname>ignoreCollisions</varname></term> <term><varname>ignoreCollisions</varname></term>
<listitem><para> <listitem><para>
@ -504,13 +518,13 @@ exist in community to help save time. No tool is preferred at the moment.
additional logic inside <varname>shellPhase</varname> to run additional logic inside <varname>shellPhase</varname> to run
<command>${python.interpreter} setup.py develop</command> for the package. <command>${python.interpreter} setup.py develop</command> for the package.
</para> </para>
<warning><para><varname>shellPhase</varname> is executed only if <filename>setup.py</filename> <warning><para><varname>shellPhase</varname> is executed only if <filename>setup.py</filename>
exists.</para></warning> exists.</para></warning>
<para> <para>
Given a <filename>default.nix</filename>: Given a <filename>default.nix</filename>:
<programlisting language="nix"> <programlisting language="nix">
<![CDATA[with import <nixpkgs> {}; <![CDATA[with import <nixpkgs> {};
@ -522,18 +536,18 @@ buildPythonPackage {
src = ./.; src = ./.;
}]]> }]]>
</programlisting> </programlisting>
Running <command>nix-shell</command> with no arguments should give you Running <command>nix-shell</command> with no arguments should give you
the environment in which the package would be build with the environment in which the package would be build with
<command>nix-build</command>. <command>nix-build</command>.
</para> </para>
<para> <para>
Shortcut to setup environments with C headers/libraries and python packages: Shortcut to setup environments with C headers/libraries and python packages:
<programlisting language="bash">$ nix-shell -p pythonPackages.pyramid zlib libjpeg git</programlisting> <programlisting language="bash">$ nix-shell -p pythonPackages.pyramid zlib libjpeg git</programlisting>
</para> </para>
<note><para> <note><para>
There is a boolean value <varname>lib.inNixShell</varname> set to There is a boolean value <varname>lib.inNixShell</varname> set to
<varname>true</varname> if nix-shell is invoked. <varname>true</varname> if nix-shell is invoked.
@ -562,12 +576,12 @@ buildPythonPackage {
Known bug in setuptools <varname>install_data</varname> does not respect --prefix</link>. Example of Known bug in setuptools <varname>install_data</varname> does not respect --prefix</link>. Example of
such package using the feature is <filename>pkgs/tools/X11/xpra/default.nix</filename>. As workaround such package using the feature is <filename>pkgs/tools/X11/xpra/default.nix</filename>. As workaround
install it as an extra <varname>preInstall</varname> step: install it as an extra <varname>preInstall</varname> step:
<programlisting>${python.interpreter} setup.py install_data --install-dir=$out --root=$out <programlisting>${python.interpreter} setup.py install_data --install-dir=$out --root=$out
sed -i '/ = data_files/d' setup.py</programlisting> sed -i '/ = data_files/d' setup.py</programlisting>
</para></listitem> </para></listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term>Rationale of non-existent global site-packages</term> <term>Rationale of non-existent global site-packages</term>
<listitem><para> <listitem><para>
@ -616,7 +630,7 @@ sed -i '/ = data_files/d' setup.py</programlisting>
this into a nix expression that contains all Gem dependencies automatically.</para> this into a nix expression that contains all Gem dependencies automatically.</para>
<para>For example, to package sensu, we did:</para> <para>For example, to package sensu, we did:</para>
<screen> <screen>
<![CDATA[$ cd pkgs/servers/monitoring <![CDATA[$ cd pkgs/servers/monitoring
$ mkdir sensu $ mkdir sensu
@ -876,7 +890,7 @@ fileSystem = buildLuaPackage {
src = fetchurl { src = fetchurl {
url = "https://github.com/keplerproject/luafilesystem/archive/v1_6_2.tar.gz"; url = "https://github.com/keplerproject/luafilesystem/archive/v1_6_2.tar.gz";
sha256 = "1n8qdwa20ypbrny99vhkmx8q04zd2jjycdb5196xdhgvqzk10abz"; sha256 = "1n8qdwa20ypbrny99vhkmx8q04zd2jjycdb5196xdhgvqzk10abz";
}; };
meta = { meta = {
homepage = "https://github.com/keplerproject/luafilesystem"; homepage = "https://github.com/keplerproject/luafilesystem";
hydraPlatforms = stdenv.lib.platforms.linux; hydraPlatforms = stdenv.lib.platforms.linux;
@ -887,7 +901,7 @@ fileSystem = buildLuaPackage {
</para> </para>
<para> <para>
Though, more complicated package should be placed in a seperate file in Though, more complicated package should be placed in a seperate file in
<link <link
xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/lua-modules"><filename>pkgs/development/lua-modules</filename></link>. xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/lua-modules"><filename>pkgs/development/lua-modules</filename></link>.
</para> </para>