public/nixpkgs
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Merge branch 'master' into staging

Browse Source
This commit is contained in:
Vladimír Čunát
2017-02-27 20:15:27 +01:00
parent 18bd007714 8def08a56c
commit a1919db7cd
832 changed files with 13596 additions and 13197 deletions
Download Patch File Download Diff File Expand all files Collapse all files
doc/configuration.xml
+182 -44
View File
@@ -4,83 +4,221 @@
<title>Global configuration</title>
<para>Nix packages can be configured to allow or deny certain options.</para>
<para>Nix comes with certain defaults about what packages can and
cannot be installed, based on a package's metadata. By default, Nix
will prevent installation if any of the following criteria are
true:</para>
<para>To apply the configuration edit
<filename>~/.config/nixpkgs/config.nix</filename> and set it like
<itemizedlist>
<listitem><para>The package is thought to be broken, and has had
its <literal>meta.broken</literal> set to
<literal>true</literal>.</para></listitem>
<listitem><para>The package's <literal>meta.license</literal> is set
to a license which is considered to be unfree.</para></listitem>
<listitem><para>The package has known security vulnerabilities but
has not or can not be updated for some reason, and a list of issues
has been entered in to the package's
<literal>meta.knownVulnerabilities</literal>.</para></listitem>
</itemizedlist>
<para>Note that all this is checked during evaluation already,
and the check includes any package that is evaluated.
In particular, all build-time dependencies are checked.
<literal>nix-env -qa</literal> will (attempt to) hide any packages
that would be refused.
</para>
<para>Each of these criteria can be altered in the nixpkgs
configuration.</para>
<para>The nixpkgs configuration for a NixOS system is set in the
<literal>configuration.nix</literal>, as in the following example:
<programlisting>
{
nixpkgs.config = {
allowUnfree = true;
};
}
</programlisting>
However, this does not allow unfree software for individual users.
Their configurations are managed separately.</para>
<para>A user's of nixpkgs configuration is stored in a user-specific
configuration file located at
<filename>~/.config/nixpkgs/config.nix</filename>. For example:
<programlisting>
{
allowUnfree = true;
}
</programlisting>
</para>
and will allow the Nix package manager to install unfree licensed packages.</para>
<section xml:id="sec-allow-broken">
<title>Installing broken packages</title>
<para>The configuration as listed also applies to NixOS under
<option>nixpkgs.config</option> set.</para>
<itemizedlist>
<para>There are two ways to try compiling a package which has been
marked as broken.</para>
<listitem>
<para>Allow installing of packages that are distributed under
unfree license by setting <programlisting>allowUnfree =
true;</programlisting> or deny them by setting it to
<literal>false</literal>.</para>
<itemizedlist>
<listitem><para>
For allowing the build of a broken package once, you can use an
environment variable for a single invocation of the nix tools:
<para>Same can be achieved by setting the environment variable:
<programlisting>$ export NIXPKGS_ALLOW_BROKEN=1</programlisting>
</para></listitem>
<listitem><para>
For permanently allowing broken packages to be built, you may
add <literal>allowBroken = true;</literal> to your user's
configuration file, like this:
<programlisting>
$ export NIXPKGS_ALLOW_UNFREE=1
{
allowBroken = true;
}
</programlisting>
</para></listitem>
</itemizedlist>
</section>
</para>
</listitem>
<section xml:id="sec-allow-unfree">
<title>Installing unfree packages</title>
<listitem>
<para>Whenever unfree packages are not allowed, single packages
can still be allowed by a predicate function that accepts package
as an argument and should return a boolean:
<para>There are several ways to tweak how Nix handles a package
which has been marked as unfree.</para>
<itemizedlist>
<listitem><para>
To temporarily allow all unfree packages, you can use an
environment variable for a single invocation of the nix tools:
<programlisting>$ export NIXPKGS_ALLOW_UNFREE=1</programlisting>
</para></listitem>
<listitem><para>
It is possible to permanently allow individual unfree packages,
while still blocking unfree packages by default using the
<literal>allowUnfreePredicate</literal> configuration
option in the user configuration file.</para>
<para>This option is a function which accepts a package as a
parameter, and returns a boolean. The following example
configuration accepts a package and always returns false:
<programlisting>
{
allowUnfreePredicate = (pkg: false);
}
</programlisting>
</para>
<para>A more useful example, the following configuration allows
only allows flash player and visual studio code:
<programlisting>
allowUnfreePredicate = (pkg: ...);
{
allowUnfreePredicate = (pkg: elem (builtins.parseDrvName pkg.name).name [ "flashplayer" "vscode" ]);
}
</programlisting>
</para></listitem>
Example to allow flash player and visual studio code only:
<listitem>
<para>It is also possible to whitelist and blacklist licenses
that are specifically acceptable or not acceptable, using
<literal>whitelistedLicenses</literal> and
<literal>blacklistedLicenses</literal>, respectively.
</para>
<para>The following example configuration whitelists the
licenses <literal>amd</literal> and <literal>wtfpl</literal>:
<programlisting>
allowUnfreePredicate = with builtins; (pkg: elem (parseDrvName pkg.name).name [ "flashplayer" "vscode" ]);
{
whitelistedLicenses = with stdenv.lib.licenses; [ amd wtfpl ];
}
</programlisting>
</para>
</para>
</listitem>
<listitem>
<para>Whenever unfree packages are not allowed, packages can still
be whitelisted by their license:
<para>The following example configuration blacklists the
<literal>gpl3</literal> and <literal>agpl3</literal> licenses:
<programlisting>
whitelistedLicenses = with stdenv.lib.licenses; [ amd wtfpl ];
{
blacklistedLicenses = with stdenv.lib.licenses; [ agpl3 gpl3 ];
}
</programlisting>
</para>
</listitem>
</para>
</listitem>
</itemizedlist>
<listitem>
<para>In addition to whitelisting licenses which are denied by the
<literal>allowUnfree</literal> setting, you can also explicitely
deny installation of packages which have a certain license:
<para>A complete list of licenses can be found in the file
<filename>lib/licenses.nix</filename> of the nixpkgs tree.</para>
</section>
<section xml:id="sec-allow-insecure">
<title>
Installing insecure packages
</title>
<para>There are several ways to tweak how Nix handles a package
which has been marked as insecure.</para>
<itemizedlist>
<listitem><para>
To temporarily allow all insecure packages, you can use an
environment variable for a single invocation of the nix tools:
<programlisting>$ export NIXPKGS_ALLOW_INSECURE=1</programlisting>
</para></listitem>
<listitem><para>
It is possible to permanently allow individual insecure
packages, while still blocking other insecure packages by
default using the <literal>permittedInsecurePackages</literal>
configuration option in the user configuration file.</para>
<para>The following example configuration permits the
installation of the hypothetically insecure package
<literal>hello</literal>, version <literal>1.2.3</literal>:
<programlisting>
{
permittedInsecurePackages = [
"hello-1.2.3"
];
}
</programlisting>
</para>
</listitem>
<listitem><para>
It is also possible to create a custom policy around which
insecure packages to allow and deny, by overriding the
<literal>allowInsecurePredicate</literal> configuration
option.</para>
<para>The <literal>allowInsecurePredicate</literal> option is a
function which accepts a package and returns a boolean, much
like <literal>allowUnfreePredicate</literal>.</para>
<para>The following configuration example only allows insecure
packages with very short names:
<programlisting>
blacklistedLicenses = with stdenv.lib.licenses; [ agpl3 gpl3 ];
{
allowInsecurePredicate = (pkg: (builtins.stringLength (builtins.parseDrvName pkg.name).name) &lt;= 5);
}
</programlisting>
</para>
</listitem>
</itemizedlist>
<para>A complete list of licenses can be found in the file
<filename>lib/licenses.nix</filename> of the nix package tree.</para>
</para>
<para>Note that <literal>permittedInsecurePackages</literal> is
only checked if <literal>allowInsecurePredicate</literal> is not
specified.
</para></listitem>
</itemizedlist>
</section>
<!--============================================================-->
doc/languages-frameworks/qt.xml
+10 -46
View File
@@ -2,67 +2,31 @@
xmlns:xlink="http://www.w3.org/1999/xlink"
xml:id="sec-language-qt">
<title>Qt</title>
<title>Qt and KDE</title>
<para>The information in this section applies to Qt 5.5 and later.</para>
<para>Qt is an application development toolkit for C++. Although it is
not a distinct programming language, there are special considerations
for packaging Qt-based programs and libraries. A small set of tools
and conventions has grown out of these considerations.</para>
<para>Qt is a comprehensive desktop and mobile application development toolkit for C++. Legacy support is available for Qt 3 and Qt 4, but all current development uses Qt 5. The Qt 5 packages in Nixpkgs are updated frequently to take advantage of new features, but older versions are typically retained to support packages that may not be compatible with the latest version. When packaging applications and libraries for Nixpkgs, it is important to ensure that compatible versions of Qt 5 are used throughout; this consideration motivates the tools described below.</para>
<section xml:id="ssec-qt-libraries"><title>Libraries</title>
<para>Packages that provide libraries should be listed in
<varname>qt5LibsFun</varname> so that the library is built with each
Qt version. A set of packages is provided for each version of Qt; for
example, <varname>qt5Libs</varname> always provides libraries built
with the latest version, <varname>qt55Libs</varname> provides
libraries built with Qt 5.5, and so on. To avoid version conflicts, no
top-level attributes are created for these packages.</para>
<para>Libraries that depend on Qt 5 should be built with each available version to avoid linking a dependent package against incompatible versions of Qt 5. (Although Qt 5 maintains backward ABI compatibility, linking against multiple versions at once is generally not possible; at best it will lead to runtime faults.) Packages that provide libraries should be added to the top-level function <varname>mkLibsForQt5</varname>, which is used to build a set of libraries for every Qt 5 version. The <varname>callPackage</varname> provided in this scope will ensure that only one Qt version will be used throughout the dependency tree. Dependencies should be imported unqualified, i.e. <literal>qtbase</literal> not <literal>qt5.qtbase</literal>, so that <varname>callPackage</varname> can do its work. <emphasis>Do not</emphasis> import a package set such as <literal>qt5</literal> or <literal>libsForQt5</literal> into your package; although it may work fine in the moment, it could well break at the next Qt update.</para>
<para>If a library does not support a particular version of Qt 5, it is best to mark it as broken by setting its <literal>meta.broken</literal> attribute. A package may be marked broken for certain versions by testing the <literal>qtbase.version</literal> attribute, which will always give the current Qt 5 version.</para>
</section>
<section xml:id="ssec-qt-programs"><title>Programs</title>
<section xml:id="ssec-qt-applications"><title>Applications</title>
<para>Application packages do not need to be built with every Qt
version. To ensure consistency between the package's dependencies,
call the package with <literal>qt5Libs.callPackage</literal> instead
of the usual <literal>callPackage</literal>. An older version may be
selected in case of incompatibility. For example, to build with Qt
5.5, call the package with
<literal>qt55Libs.callPackage</literal>.</para>
<para>Applications generally do not need to be built with every Qt version because they do not provide any libraries for dependent packages to link against. The primary consideration is merely ensuring that the application itself and its dependencies are linked against only one version of Qt. To call your application expression, use <literal>libsForQt5.callPackage</literal> instead of <literal>callPackage</literal>. Dependencies should be imported unqualified, i.e. <literal>qtbase</literal> not <literal>qt5.qtbase</literal>. <emphasis>Do not</emphasis> import a package set such as <literal>qt5</literal> or <literal>libsForQt5</literal> into your package; although it may work fine in the moment, it could well break at the next Qt update.</para>
<para>Several environment variables must be set at runtime for Qt
applications to function correctly, including:</para>
<para>It is generally best to build an application package against the <varname>libsForQt5</varname> library set. In case a package does not build with the latest Qt version, it is possible to pick a set pinned to a particular version, e.g. <varname>libsForQt55</varname> for Qt 5.5, if that is the latest version the package supports.</para>
<itemizedlist>
<listitem><para><envar>QT_PLUGIN_PATH</envar></para></listitem>
<listitem><para><envar>QML_IMPORT_PATH</envar></para></listitem>
<listitem><para><envar>QML2_IMPORT_PATH</envar></para></listitem>
<listitem><para><envar>XDG_DATA_DIRS</envar></para></listitem>
</itemizedlist>
<para>To ensure that these are set correctly, the program must be wrapped by
invoking <literal>wrapQtProgram <replaceable>program</replaceable></literal>
during installation (for example, during
<literal>fixupPhase</literal>). <literal>wrapQtProgram</literal>
accepts the same options as <literal>makeWrapper</literal>.
</para>
<para>Qt-based applications require that several paths be set at runtime. This is accomplished by wrapping the provided executables in a package with <literal>wrapQtProgram</literal> or <literal>makeQtWrapper</literal> during the <literal>postFixup</literal> phase. To use the wrapper generators, add <literal>makeQtWrapper</literal> to <literal>nativeBuildInputs</literal>. The wrapper generators support the same options as <literal>wrapProgram</literal> and <literal>makeWrapper</literal> respectively. It is usually only necessary to generate wrappers for programs intended to be invoked by the user.</para>
</section>
<section xml:id="ssec-qt-kde"><title>KDE</title>
<para>Many of the considerations above also apply to KDE packages,
especially the need to set the correct environment variables at
runtime. To ensure that this is done, invoke <literal>wrapKDEProgram
<replaceable>program</replaceable></literal> during
installation. <literal>wrapKDEProgram</literal> also generates a
<literal>ksycoca</literal> database so that required data and services
can be found. Like its Qt counterpart,
<literal>wrapKDEProgram</literal> accepts the same options as
<literal>makeWrapper</literal>.</para>
<para>The KDE Frameworks are a set of libraries for Qt 5 which form the basis of the Plasma desktop environment and the KDE Applications suite. Packaging a Frameworks-based library does not require any steps beyond those described above for general Qt-based libraries. Frameworks-based applications should not use <literal>makeQtWrapper</literal>; instead, use <literal>kdeWrapper</literal> to create the necessary wrappers: <literal>kdeWrapper { unwrapped = <replaceable>expr</replaceable>; targets = <replaceable>exes</replaceable>; }</literal>, where <replaceable>expr</replaceable> is the un-wrapped package expression and <replaceable>exes</replaceable> is a list of strings giving the relative paths to programs in the package which should be wrapped.</para>
</section>