diff --git a/doc/default.nix b/doc/default.nix
index b8dac00eb65e..cca68014b0d1 100644
--- a/doc/default.nix
+++ b/doc/default.nix
@@ -1,10 +1,12 @@
with import ./.. { };
with lib;
-
+let
+ sources = sourceFilesBySuffices ./. [".xml"];
+ sources-langs = ./languages-frameworks;
+in
stdenv.mkDerivation {
name = "nixpkgs-manual";
- sources = sourceFilesBySuffices ./. [".xml"];
buildInputs = [ pandoc libxml2 libxslt ];
@@ -35,7 +37,9 @@ stdenv.mkDerivation {
echo ""
} >haskell-users-guide.xml
- ln -s "$sources/"*.xml .
+ ln -s '${sources}/'*.xml .
+ mkdir ./languages-frameworks
+ cp -s '${sources-langs}'/* ./languages-frameworks
echo ${nixpkgsVersion} > .version
diff --git a/doc/language-support.xml b/doc/language-support.xml
deleted file mode 100644
index f0d5dbd3e64f..000000000000
--- a/doc/language-support.xml
+++ /dev/null
@@ -1,1047 +0,0 @@
-
-
-Support for specific programming languages
-
-The standard build
-environment makes it easy to build typical Autotools-based
-packages with very little code. Any other kind of package can be
-accomodated by overriding the appropriate phases of
-stdenv. However, there are specialised functions
-in Nixpkgs to easily build packages for other programming languages,
-such as Perl or Haskell. These are described in this chapter.
-
-
-Perl
-
-Nixpkgs provides a function buildPerlPackage,
-a generic package builder function for any Perl package that has a
-standard Makefile.PL. It’s implemented in pkgs/development/perl-modules/generic.
-
-Perl packages from CPAN are defined in pkgs/top-level/perl-packages.nix,
-rather than pkgs/all-packages.nix. Most Perl
-packages are so straight-forward to build that they are defined here
-directly, rather than having a separate function for each package
-called from perl-packages.nix. However, more
-complicated packages should be put in a separate file, typically in
-pkgs/development/perl-modules. Here is an
-example of the former:
-
-
-ClassC3 = buildPerlPackage rec {
- name = "Class-C3-0.21";
- src = fetchurl {
- url = "mirror://cpan/authors/id/F/FL/FLORA/${name}.tar.gz";
- sha256 = "1bl8z095y4js66pwxnm7s853pi9czala4sqc743fdlnk27kq94gz";
- };
-};
-
-
-Note the use of mirror://cpan/, and the
-${name} in the URL definition to ensure that the
-name attribute is consistent with the source that we’re actually
-downloading. Perl packages are made available in
-all-packages.nix through the variable
-perlPackages. For instance, if you have a package
-that needs ClassC3, you would typically write
-
-
-foo = import ../path/to/foo.nix {
- inherit stdenv fetchurl ...;
- inherit (perlPackages) ClassC3;
-};
-
-
-in all-packages.nix. You can test building a
-Perl package as follows:
-
-
-$ nix-build -A perlPackages.ClassC3
-
-
-buildPerlPackage adds perl- to
-the start of the name attribute, so the package above is actually
-called perl-Class-C3-0.21. So to install it, you
-can say:
-
-
-$ nix-env -i perl-Class-C3
-
-
-(Of course you can also install using the attribute name:
-nix-env -i -A perlPackages.ClassC3.)
-
-So what does buildPerlPackage do? It does
-the following:
-
-
-
- In the configure phase, it calls perl
- Makefile.PL to generate a Makefile. You can set the
- variable makeMakerFlags to pass flags to
- Makefile.PL
-
- It adds the contents of the PERL5LIB
- environment variable to #! .../bin/perl line of
- Perl scripts as -Idir
- flags. This ensures that a script can find its
- dependencies.
-
- In the fixup phase, it writes the propagated build
- inputs (propagatedBuildInputs) to the file
- $out/nix-support/propagated-user-env-packages.
- nix-env recursively installs all packages listed
- in this file when you install a package that has it. This ensures
- that a Perl package can find its dependencies.
-
-
-
-
-
-buildPerlPackage is built on top of
-stdenv, so everything can be customised in the
-usual way. For instance, the BerkeleyDB module has
-a preConfigure hook to generate a configuration
-file used by Makefile.PL:
-
-
-{ buildPerlPackage, fetchurl, db }:
-
-buildPerlPackage rec {
- name = "BerkeleyDB-0.36";
-
- src = fetchurl {
- url = "mirror://cpan/authors/id/P/PM/PMQS/${name}.tar.gz";
- sha256 = "07xf50riarb60l1h6m2dqmql8q5dij619712fsgw7ach04d8g3z1";
- };
-
- preConfigure = ''
- echo "LIB = ${db}/lib" > config.in
- echo "INCLUDE = ${db}/include" >> config.in
- '';
-}
-
-
-
-
-Dependencies on other Perl packages can be specified in the
-buildInputs and
-propagatedBuildInputs attributes. If something is
-exclusively a build-time dependency, use
-buildInputs; if it’s (also) a runtime dependency,
-use propagatedBuildInputs. For instance, this
-builds a Perl module that has runtime dependencies on a bunch of other
-modules:
-
-
-ClassC3Componentised = buildPerlPackage rec {
- name = "Class-C3-Componentised-1.0004";
- src = fetchurl {
- url = "mirror://cpan/authors/id/A/AS/ASH/${name}.tar.gz";
- sha256 = "0xql73jkcdbq4q9m0b0rnca6nrlvf5hyzy8is0crdk65bynvs8q1";
- };
- propagatedBuildInputs = [
- ClassC3 ClassInspector TestException MROCompat
- ];
-};
-
-
-
-
-Generation from CPAN
-
-Nix expressions for Perl packages can be generated (almost)
-automatically from CPAN. This is done by the program
-nix-generate-from-cpan, which can be installed
-as follows:
-
-
-$ nix-env -i nix-generate-from-cpan
-
-
-This program takes a Perl module name, looks it up on CPAN,
-fetches and unpacks the corresponding package, and prints a Nix
-expression on standard output. For example:
-
-
-$ nix-generate-from-cpan XML::Simple
- XMLSimple = buildPerlPackage {
- name = "XML-Simple-2.20";
- src = fetchurl {
- url = mirror://cpan/authors/id/G/GR/GRANTM/XML-Simple-2.20.tar.gz;
- sha256 = "5cff13d0802792da1eb45895ce1be461903d98ec97c9c953bc8406af7294434a";
- };
- propagatedBuildInputs = [ XMLNamespaceSupport XMLSAX XMLSAXExpat ];
- meta = {
- description = "Easily read/write XML (esp config files)";
- license = "perl";
- };
- };
-
-
-The output can be pasted into
-pkgs/top-level/perl-packages.nix or wherever else
-you need it.
-
-
-
-
-
-
-Python
-
-
- Currently supported interpreters are python26, python27,
- python33, python34, python35
- and pypy.
-
-
-
- python is an alias to python27 and python3 is an alias to python34.
-
-
-
- python26 and python27 do not include modules that require
- external dependencies (to reduce dependency bloat). Following modules need to be added as
- buildInput explicitly:
-
-
-
- python.modules.bsddb
- python.modules.curses
- python.modules.curses_panel
- python.modules.crypt
- python.modules.gdbm
- python.modules.sqlite3
- python.modules.tkinter
- python.modules.readline
-
-
-For convenience python27Full and python26Full
-are provided with all modules included.
-
-
- Python packages that
- use setuptools or distutils,
- can be built using the buildPythonPackage function as documented below.
-
-
-
- All packages depending on any Python interpreter get appended $out/${python.sitePackages}
- to $PYTHONPATH if such directory exists.
-
-
-
-
- Useful attributes on interpreters packages:
-
-
-
- libPrefix
-
- Name of the folder in ${python}/lib/ for corresponding interpreter.
-
-
-
-
- interpreter
-
- Alias for ${python}/bin/${executable}.
-
-
-
-
- buildEnv
-
- Function to build python interpreter environments with extra packages bundled together.
- See for usage and documentation.
-
-
-
-
- sitePackages
-
- Alias for lib/${libPrefix}/site-packages.
-
-
-
-
- executable
-
- Name of the interpreter executable, ie python3.4.
-
-
-
-
-<varname>buildPythonPackage</varname> function
-
-
- The function is implemented in
- pkgs/development/python-modules/generic/default.nix.
- Example usage:
-
-
-twisted = buildPythonPackage {
- name = "twisted-8.1.0";
-
- src = pkgs.fetchurl {
- url = http://tmrc.mit.edu/mirror/twisted/Twisted/8.1/Twisted-8.1.0.tar.bz2;
- sha256 = "0q25zbr4xzknaghha72mq57kh53qw1bf8csgp63pm9sfi72qhirl";
- };
-
- propagatedBuildInputs = [ self.ZopeInterface ];
-
- meta = {
- homepage = http://twistedmatrix.com/;
- description = "Twisted, an event-driven networking engine written in Python";
- license = stdenv.lib.licenses.mit;
- };
-};
-
-
- Most of Python packages that use buildPythonPackage are defined
- in pkgs/top-level/python-packages.nix
- and generated for each python interpreter separately into attribute sets python26Packages,
- python27Packages, python35Packages, python33Packages,
- python34Packages and pypyPackages.
-
-
-
- buildPythonPackage mainly does four things:
-
-
-
- In the buildPhase, it calls
- ${python.interpreter} setup.py bdist_wheel to build a wheel binary zipfile.
-
-
-
- In the installPhase, it installs the wheel file using
- pip install *.whl.
-
-
-
- In the postFixup phase, wrapPythonPrograms
- bash function is called to wrap all programs in $out/bin/*
- directory to include $PYTHONPATH and $PATH
- environment variables.
-
-
-
- In the installCheck phase, ${python.interpreter} setup.py test
- is ran.
-
-
-
-
- By default doCheck = true is set
-
-
- As in Perl, dependencies on other Python packages can be specified in the
- buildInputs and
- propagatedBuildInputs attributes. If something is
- exclusively a build-time dependency, use
- buildInputs; if it’s (also) a runtime dependency,
- use propagatedBuildInputs.
-
-
-
- By default meta.platforms is set to the same value
- as the interpreter unless overriden otherwise.
-
-
-
-
- <varname>buildPythonPackage</varname> parameters
- (all parameters from <varname>mkDerivation</varname> function are still supported)
-
-
-
- namePrefix
-
- Prepended text to ${name} parameter.
- Defaults to "python3.3-" for Python 3.3, etc. Set it to
- ""
- if you're packaging an application or a command line tool.
-
-
-
-
- disabled
-
- If true, package is not build for
- particular python interpreter version. Grep around
- pkgs/top-level/python-packages.nix
- for examples.
-
-
-
-
- setupPyBuildFlags
-
- List of flags passed to setup.py build_ext command.
-
-
-
-
- pythonPath
-
- List of packages to be added into $PYTHONPATH.
- Packages in pythonPath are not propagated
- (contrary to propagatedBuildInputs).
-
-
-
-
- preShellHook
-
- Hook to execute commands before shellHook.
-
-
-
-
- postShellHook
-
- Hook to execute commands after shellHook.
-
-
-
-
- makeWrapperArgs
-
- A list of strings. Arguments to be passed to
- makeWrapper, which wraps generated binaries. By
- default, the arguments to makeWrapper set
- PATH and PYTHONPATH 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,
- makeWrapperArgs = ["--set FOO BAR" "--set BAZ QUX"].
-
-
-
-
-
-
-
-<function>python.buildEnv</function> function
-
- Create Python environments using low-level pkgs.buildEnv function. Example default.nix:
-
-
- {};
-
-python.buildEnv.override {
- extraLibs = [ pkgs.pythonPackages.pyramid ];
- ignoreCollisions = true;
-}]]>
-
-
- Running nix-build will create
- /nix/store/cf1xhjwzmdki7fasgr4kz6di72ykicl5-python-2.7.8-env
- with wrapped binaries in bin/.
-
-
-
- You can also use env attribute to create local
- environments with needed packages installed (somewhat comparable to
- virtualenv). For example, with the following
- shell.nix:
-
-
- {};
-
-(python3.buildEnv.override {
- extraLibs = with python3Packages;
- [ numpy
- requests
- ];
-}).env]]>
-
-
- Running nix-shell will drop you into a shell where
- python will have specified packages in its path.
-
-
-
-
- <function>python.buildEnv</function> arguments
-
-
-
- extraLibs
-
- List of packages installed inside the environment.
-
-
-
-
- postBuild
-
- Shell command executed after the build of environment.
-
-
-
-
- ignoreCollisions
-
- Ignore file collisions inside the environment (default is false).
-
-
-
-
-
-Tools
-
-Packages inside nixpkgs are written by hand. However many tools
-exist in community to help save time. No tool is preferred at the moment.
-
-
-
-
-
- python2nix
- by Vladimir Kirillov
-
-
-
- pypi2nix
- by Rok Garbas
-
-
-
- pypi2nix
- by Jaka Hudoklin
-
-
-
-
-
-
-Development
-
-
- To develop Python packages buildPythonPackage has
- additional logic inside shellPhase to run
- pip install -e . --prefix $TMPDIR/ for the package.
-
-
- shellPhase is executed only if setup.py
- exists.
-
-
- Given a default.nix:
-
-
- {};
-
-buildPythonPackage {
- name = "myproject";
-
- buildInputs = with pkgs.pythonPackages; [ pyramid ];
-
- src = ./.;
-}]]>
-
-
- Running nix-shell with no arguments should give you
- the environment in which the package would be build with
- nix-build.
-
-
-
- Shortcut to setup environments with C headers/libraries and python packages:
-
- $ nix-shell -p pythonPackages.pyramid zlib libjpeg git
-
-
-
- There is a boolean value lib.inNixShell set to
- true if nix-shell is invoked.
-
-
-
-
-FAQ
-
-
-
-
- How to solve circular dependencies?
-
- If you have packages A and B that
- depend on each other, when packaging B override package
- A not to depend on B as input
- (and also the other way around).
-
-
-
-
- install_data / data_files problems resulting into error: could not create '/nix/store/6l1bvljpy8gazlsw2aw9skwwp4pmvyxw-python-2.7.8/etc': Permission denied
-
-
- Known bug in setuptools install_data does not respect --prefix. Example of
- such package using the feature is pkgs/tools/X11/xpra/default.nix. As workaround
- install it as an extra preInstall step:
-
- ${python.interpreter} setup.py install_data --install-dir=$out --root=$out
-sed -i '/ = data_files/d' setup.py
-
-
-
-
- Rationale of non-existent global site-packages
-
- There is no need to have global site-packages in Nix. Each package has isolated
- dependency tree and installing any python package will only populate $PATH
- inside user environment. See to create self-contained
- interpreter with a set of packages.
-
-
-
-
-
-
-
-
-Contributing guidelines
-
- Following rules are desired to be respected:
-
-
-
-
-
- Make sure package builds for all python interpreters. Use disabled argument to
- buildPythonPackage to set unsupported interpreters.
-
-
-
- If tests need to be disabled for a package, make sure you leave a comment about reasoning.
-
-
-
- Packages in pkgs/top-level/python-packages.nix
- are sorted quasi-alphabetically to avoid merge conflicts.
-
-
-
-
-
-
-
-
-
-Ruby
- There currently is support to bundle applications that are packaged as Ruby gems. The utility "bundix" allows you to write a Gemfile, let bundler create a Gemfile.lock, and then convert
- this into a nix expression that contains all Gem dependencies automatically.
-
- For example, to package sensu, we did:
-
-
- Gemfile
-source 'https://rubygems.org'
-gem 'sensu'
-$ bundler package --path /tmp/vendor/bundle
-$ $(nix-build '' -A bundix)/bin/bundix
-$ cat > default.nix
-{ lib, bundlerEnv, ruby }:
-
-bundlerEnv {
- name = "sensu-0.17.1";
-
- inherit ruby;
- gemfile = ./Gemfile;
- lockfile = ./Gemfile.lock;
- gemset = ./gemset.nix;
-
- meta = with lib; {
- description = "A monitoring framework that aims to be simple, malleable,
-and scalable.";
- homepage = http://sensuapp.org/;
- license = with licenses; mit;
- maintainers = with maintainers; [ theuni ];
- platforms = platforms.unix;
- };
-}]]>
-
-
-Please check in the Gemfile, Gemfile.lock and the gemset.nix so future updates can be run easily.
-
-
-
-
-Go
-
-The function buildGoPackage builds
-standard Go packages.
-
-
-buildGoPackage
-
-net = buildGoPackage rec {
- name = "go.net-${rev}";
- goPackagePath = "golang.org/x/net";
- subPackages = [ "ipv4" "ipv6" ];
- rev = "e0403b4e005";
- src = fetchFromGitHub {
- inherit rev;
- owner = "golang";
- repo = "net";
- sha256 = "1g7cjzw4g4301a3yqpbk8n1d4s97sfby2aysl275x04g0zh8jxqp";
- };
- goPackageAliases = [ "code.google.com/p/go.net" ];
- propagatedBuildInputs = [ goPackages.text ];
- buildFlags = "--tags release";
- disabled = isGo13;
-};
-
-
-
- is an example expression using buildGoPackage,
-the following arguments are of special significance to the function:
-
-
-
-
-
- goPackagePath specifies the package's canonical Go import path.
-
-
-
-
-
- subPackages limits the builder from building child packages that
- have not been listed. If subPackages is not specified, all child
- packages will be built.
-
-
- In this example only code.google.com/p/go.net/ipv4 and
- code.google.com/p/go.net/ipv6 will be built.
-
-
-
-
-
- goPackageAliases is a list of alternative import paths
- that are valid for this library.
- Packages that depend on this library will automatically rename
- import paths that match any of the aliases to goPackagePath.
-
-
- In this example imports will be renamed from
- code.google.com/p/go.net to
- golang.org/x/net in every package that depend on the
- go.net library.
-
-
-
-
-
- propagatedBuildInputs is where the dependencies of a Go library are
- listed. Only libraries should list propagatedBuildInputs. If a standalone
- program is being built instead, use buildInputs. If a library's tests require
- additional dependencies that are not propagated, they should be listed in buildInputs.
-
-
-
-
-
- buildFlags is a list of flags passed to the go build command.
-
-
-
-
-
- If disabled is true,
- nix will refuse to build this package.
-
-
- In this example the package will not be built for go 1.3. The isGo13
- is an utility function that returns true if go used to build the
- package has version 1.3.x.
-
-
-
-
-
-
-
-
-Reusable Go libraries may be found in the goPackages set. You can test
-build a Go package as follows:
-
-
-$ nix-build -A goPackages.net
-
-
-
-
-
-You may use Go packages installed into the active Nix profiles by adding
-the following to your ~/.bashrc:
-
-
-for p in $NIX_PROFILES; do
- GOPATH="$p/share/go:$GOPATH"
-done
-
-
-
- To extract dependency information from a Go package in automated way use go2nix.
-
-
-
-Java
-
-Ant-based Java packages are typically built from source as follows:
-
-
-stdenv.mkDerivation {
- name = "...";
- src = fetchurl { ... };
-
- buildInputs = [ jdk ant ];
-
- buildPhase = "ant";
-}
-
-
-Note that jdk is an alias for the OpenJDK.
-
-JAR files that are intended to be used by other packages should
-be installed in $out/share/java. The OpenJDK has
-a stdenv setup hook that adds any JARs in the
-share/java directories of the build inputs to the
-CLASSPATH environment variable. For instance, if the
-package libfoo installs a JAR named
-foo.jar in its share/java
-directory, and another package declares the attribute
-
-
-buildInputs = [ jdk libfoo ];
-
-
-then CLASSPATH will be set to
-/nix/store/...-libfoo/share/java/foo.jar.
-
-Private JARs
-should be installed in a location like
-$out/share/package-name.
-
-If your Java package provides a program, you need to generate a
-wrapper script to run it using the OpenJRE. You can use
-makeWrapper for this:
-
-
-buildInputs = [ makeWrapper ];
-
-installPhase =
- ''
- mkdir -p $out/bin
- makeWrapper ${jre}/bin/java $out/bin/foo \
- --add-flags "-cp $out/share/java/foo.jar org.foo.Main"
- '';
-
-
-Note the use of jre, which is the part of the
-OpenJDK package that contains the Java Runtime Environment. By using
-${jre}/bin/java instead of
-${jdk}/bin/java, you prevent your package from
-depending on the JDK at runtime.
-
-It is possible to use a different Java compiler than
-javac from the OpenJDK. For instance, to use the
-Eclipse Java Compiler:
-
-
-buildInputs = [ jre ant ecj ];
-
-
-(Note that here you don’t need the full JDK as an input, but just the
-JRE.) The ECJ has a stdenv setup hook that sets some environment
-variables to cause Ant to use ECJ, but this doesn’t work with all Ant
-files. Similarly, you can use the GNU Java Compiler:
-
-
-buildInputs = [ gcj ant ];
-
-
-Here, Ant will automatically use gij (the GNU Java
-Runtime) instead of the OpenJRE.
-
-
-
-
-Lua
-
-
- Lua packages are built by the buildLuaPackage function. This function is
- implemented
- in
- pkgs/development/lua-modules/generic/default.nix
- and works similarly to buildPerlPackage. (See
- for details.)
-
-
-
- Lua packages are defined
- in pkgs/top-level/lua-packages.nix.
- Most of them are simple. For example:
-
-
-fileSystem = buildLuaPackage {
- name = "filesystem-1.6.2";
- src = fetchurl {
- url = "https://github.com/keplerproject/luafilesystem/archive/v1_6_2.tar.gz";
- sha256 = "1n8qdwa20ypbrny99vhkmx8q04zd2jjycdb5196xdhgvqzk10abz";
- };
- meta = {
- homepage = "https://github.com/keplerproject/luafilesystem";
- hydraPlatforms = stdenv.lib.platforms.linux;
- maintainers = with maintainers; [ flosse ];
- };
-};
-
-
-
-
- Though, more complicated package should be placed in a seperate file in
- pkgs/development/lua-modules.
-
-
- Lua packages accept additional parameter disabled, which defines
- the condition of disabling package from luaPackages. For example, if package has
- disabled assigned to lua.luaversion != "5.1",
- it will not be included in any luaPackages except lua51Packages, making it
- only be built for lua 5.1.
-
-
-
-
-Coq
-
- Coq libraries should be installed in
- $(out)/lib/coq/${coq.coq-version}/user-contrib/.
- Such directories are automatically added to the
- $COQPATH environment variable by the hook defined
- in the Coq derivation.
-
-
- Some libraries require OCaml and sometimes also Camlp5. The exact
- versions that were used to build Coq are saved in the
- coq.ocaml and coq.camlp5
- attributes.
-
-
- Here is a simple package example. It is a pure Coq library, thus it
- only depends on Coq. Its makefile has been
- generated using coq_makefile so we only have to
- set the $COQLIB variable at install time.
-
-
-{stdenv, fetchurl, coq}:
-stdenv.mkDerivation {
- src = fetchurl {
- url = http://coq.inria.fr/pylons/contribs/files/Karatsuba/v8.4/Karatsuba.tar.gz;
- sha256 = "0ymfpv4v49k4fm63nq6gcl1hbnnxrvjjp7yzc4973n49b853c5b1";
- };
-
- name = "coq-karatsuba";
-
- buildInputs = [ coq ];
-
- installFlags = "COQLIB=$(out)/lib/coq/${coq.coq-version}/";
-}
-
-
-
-Qt
-
-The information in this section applies to Qt 5.5 and later.
-
-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.
-
-Libraries
-
-Packages that provide libraries should be listed in
-qt5LibsFun so that the library is built with each
-Qt version. A set of packages is provided for each version of Qt; for
-example, qt5Libs always provides libraries built
-with the latest version, qt55Libs provides
-libraries built with Qt 5.5, and so on. To avoid version conflicts, no
-top-level attributes are created for these packages.
-
-
-
-Programs
-
-Application packages do not need to be built with every Qt
-version. To ensure consistency between the package's dependencies,
-call the package with qt5Libs.callPackage instead
-of the usual callPackage. An older version may be
-selected in case of incompatibility. For example, to build with Qt
-5.5, call the package with
-qt55Libs.callPackage.
-
-Several environment variables must be set at runtime for Qt
-applications to function correctly, including:
-
-
- QT_PLUGIN_PATH
- QML_IMPORT_PATH
- QML2_IMPORT_PATH
- XDG_DATA_DIRS
-
-
-To ensure that these are set correctly, the program must be wrapped by
-invoking wrapQtProgram program
-during installation (for example, during
-fixupPhase). wrapQtProgram
-accepts the same options as makeWrapper.
-
-
-
-
-KDE
-
-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 wrapKDEProgram
-program during
-installation. wrapKDEProgram also generates a
-ksycoca database so that required data and services
-can be found. Like its Qt counterpart,
-wrapKDEProgram accepts the same options as
-makeWrapper.
-
-
-
-
-
-
-
-
-
diff --git a/doc/languages-frameworks/coq.xml b/doc/languages-frameworks/coq.xml
new file mode 100644
index 000000000000..d16c9f3dc87f
--- /dev/null
+++ b/doc/languages-frameworks/coq.xml
@@ -0,0 +1,41 @@
+
+
+Coq
+
+ Coq libraries should be installed in
+ $(out)/lib/coq/${coq.coq-version}/user-contrib/.
+ Such directories are automatically added to the
+ $COQPATH environment variable by the hook defined
+ in the Coq derivation.
+
+
+ Some libraries require OCaml and sometimes also Camlp5. The exact
+ versions that were used to build Coq are saved in the
+ coq.ocaml and coq.camlp5
+ attributes.
+
+
+ Here is a simple package example. It is a pure Coq library, thus it
+ only depends on Coq. Its makefile has been
+ generated using coq_makefile so we only have to
+ set the $COQLIB variable at install time.
+
+
+{stdenv, fetchurl, coq}:
+stdenv.mkDerivation {
+ src = fetchurl {
+ url = http://coq.inria.fr/pylons/contribs/files/Karatsuba/v8.4/Karatsuba.tar.gz;
+ sha256 = "0ymfpv4v49k4fm63nq6gcl1hbnnxrvjjp7yzc4973n49b853c5b1";
+ };
+
+ name = "coq-karatsuba";
+
+ buildInputs = [ coq ];
+
+ installFlags = "COQLIB=$(out)/lib/coq/${coq.coq-version}/";
+}
+
+
+
diff --git a/doc/languages-frameworks/go.xml b/doc/languages-frameworks/go.xml
new file mode 100644
index 000000000000..89908b3b8ff5
--- /dev/null
+++ b/doc/languages-frameworks/go.xml
@@ -0,0 +1,124 @@
+
+
+Go
+
+The function buildGoPackage builds
+standard Go packages.
+
+
+buildGoPackage
+
+net = buildGoPackage rec {
+ name = "go.net-${rev}";
+ goPackagePath = "golang.org/x/net";
+ subPackages = [ "ipv4" "ipv6" ];
+ rev = "e0403b4e005";
+ src = fetchFromGitHub {
+ inherit rev;
+ owner = "golang";
+ repo = "net";
+ sha256 = "1g7cjzw4g4301a3yqpbk8n1d4s97sfby2aysl275x04g0zh8jxqp";
+ };
+ goPackageAliases = [ "code.google.com/p/go.net" ];
+ propagatedBuildInputs = [ goPackages.text ];
+ buildFlags = "--tags release";
+ disabled = isGo13;
+};
+
+
+
+ is an example expression using buildGoPackage,
+the following arguments are of special significance to the function:
+
+
+
+
+
+ goPackagePath specifies the package's canonical Go import path.
+
+
+
+
+
+ subPackages limits the builder from building child packages that
+ have not been listed. If subPackages is not specified, all child
+ packages will be built.
+
+
+ In this example only code.google.com/p/go.net/ipv4 and
+ code.google.com/p/go.net/ipv6 will be built.
+
+
+
+
+
+ goPackageAliases is a list of alternative import paths
+ that are valid for this library.
+ Packages that depend on this library will automatically rename
+ import paths that match any of the aliases to goPackagePath.
+
+
+ In this example imports will be renamed from
+ code.google.com/p/go.net to
+ golang.org/x/net in every package that depend on the
+ go.net library.
+
+
+
+
+
+ propagatedBuildInputs is where the dependencies of a Go library are
+ listed. Only libraries should list propagatedBuildInputs. If a standalone
+ program is being built instead, use buildInputs. If a library's tests require
+ additional dependencies that are not propagated, they should be listed in buildInputs.
+
+
+
+
+
+ buildFlags is a list of flags passed to the go build command.
+
+
+
+
+
+ If disabled is true,
+ nix will refuse to build this package.
+
+
+ In this example the package will not be built for go 1.3. The isGo13
+ is an utility function that returns true if go used to build the
+ package has version 1.3.x.
+
+
+
+
+
+
+
+
+Reusable Go libraries may be found in the goPackages set. You can test
+build a Go package as follows:
+
+
+$ nix-build -A goPackages.net
+
+
+
+
+
+You may use Go packages installed into the active Nix profiles by adding
+the following to your ~/.bashrc:
+
+
+for p in $NIX_PROFILES; do
+ GOPATH="$p/share/go:$GOPATH"
+done
+
+
+
+ To extract dependency information from a Go package in automated way use go2nix.
+
+
diff --git a/doc/languages-frameworks/index.xml b/doc/languages-frameworks/index.xml
new file mode 100644
index 000000000000..9fd79877e835
--- /dev/null
+++ b/doc/languages-frameworks/index.xml
@@ -0,0 +1,42 @@
+
+
+Support for specific programming languages and frameworks
+
+The standard build
+environment makes it easy to build typical Autotools-based
+packages with very little code. Any other kind of package can be
+accomodated by overriding the appropriate phases of
+stdenv. However, there are specialised functions
+in Nixpkgs to easily build packages for other programming languages,
+such as Perl or Haskell. These are described in this chapter.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/doc/languages-frameworks/java.xml b/doc/languages-frameworks/java.xml
new file mode 100644
index 000000000000..2d40a254cedf
--- /dev/null
+++ b/doc/languages-frameworks/java.xml
@@ -0,0 +1,84 @@
+
+
+Java
+
+Ant-based Java packages are typically built from source as follows:
+
+
+stdenv.mkDerivation {
+ name = "...";
+ src = fetchurl { ... };
+
+ buildInputs = [ jdk ant ];
+
+ buildPhase = "ant";
+}
+
+
+Note that jdk is an alias for the OpenJDK.
+
+JAR files that are intended to be used by other packages should
+be installed in $out/share/java. The OpenJDK has
+a stdenv setup hook that adds any JARs in the
+share/java directories of the build inputs to the
+CLASSPATH environment variable. For instance, if the
+package libfoo installs a JAR named
+foo.jar in its share/java
+directory, and another package declares the attribute
+
+
+buildInputs = [ jdk libfoo ];
+
+
+then CLASSPATH will be set to
+/nix/store/...-libfoo/share/java/foo.jar.
+
+Private JARs
+should be installed in a location like
+$out/share/package-name.
+
+If your Java package provides a program, you need to generate a
+wrapper script to run it using the OpenJRE. You can use
+makeWrapper for this:
+
+
+buildInputs = [ makeWrapper ];
+
+installPhase =
+ ''
+ mkdir -p $out/bin
+ makeWrapper ${jre}/bin/java $out/bin/foo \
+ --add-flags "-cp $out/share/java/foo.jar org.foo.Main"
+ '';
+
+
+Note the use of jre, which is the part of the
+OpenJDK package that contains the Java Runtime Environment. By using
+${jre}/bin/java instead of
+${jdk}/bin/java, you prevent your package from
+depending on the JDK at runtime.
+
+It is possible to use a different Java compiler than
+javac from the OpenJDK. For instance, to use the
+Eclipse Java Compiler:
+
+
+buildInputs = [ jre ant ecj ];
+
+
+(Note that here you don’t need the full JDK as an input, but just the
+JRE.) The ECJ has a stdenv setup hook that sets some environment
+variables to cause Ant to use ECJ, but this doesn’t work with all Ant
+files. Similarly, you can use the GNU Java Compiler:
+
+
+buildInputs = [ gcj ant ];
+
+
+Here, Ant will automatically use gij (the GNU Java
+Runtime) instead of the OpenJRE.
+
+
+
diff --git a/doc/languages-frameworks/lua.xml b/doc/languages-frameworks/lua.xml
new file mode 100644
index 000000000000..39b086af4cb1
--- /dev/null
+++ b/doc/languages-frameworks/lua.xml
@@ -0,0 +1,51 @@
+
+
+Lua
+
+
+ Lua packages are built by the buildLuaPackage function. This function is
+ implemented
+ in
+ pkgs/development/lua-modules/generic/default.nix
+ and works similarly to buildPerlPackage. (See
+ for details.)
+
+
+
+ Lua packages are defined
+ in pkgs/top-level/lua-packages.nix.
+ Most of them are simple. For example:
+
+
+fileSystem = buildLuaPackage {
+ name = "filesystem-1.6.2";
+ src = fetchurl {
+ url = "https://github.com/keplerproject/luafilesystem/archive/v1_6_2.tar.gz";
+ sha256 = "1n8qdwa20ypbrny99vhkmx8q04zd2jjycdb5196xdhgvqzk10abz";
+ };
+ meta = {
+ homepage = "https://github.com/keplerproject/luafilesystem";
+ hydraPlatforms = stdenv.lib.platforms.linux;
+ maintainers = with maintainers; [ flosse ];
+ };
+};
+
+
+
+
+ Though, more complicated package should be placed in a seperate file in
+ pkgs/development/lua-modules.
+
+
+ Lua packages accept additional parameter disabled, which defines
+ the condition of disabling package from luaPackages. For example, if package has
+ disabled assigned to lua.luaversion != "5.1",
+ it will not be included in any luaPackages except lua51Packages, making it
+ only be built for lua 5.1.
+
+
+
+
diff --git a/doc/languages-frameworks/perl.xml b/doc/languages-frameworks/perl.xml
new file mode 100644
index 000000000000..54b82f4a0560
--- /dev/null
+++ b/doc/languages-frameworks/perl.xml
@@ -0,0 +1,181 @@
+
+
+Perl
+
+Nixpkgs provides a function buildPerlPackage,
+a generic package builder function for any Perl package that has a
+standard Makefile.PL. It’s implemented in pkgs/development/perl-modules/generic.
+
+Perl packages from CPAN are defined in pkgs/top-level/perl-packages.nix,
+rather than pkgs/all-packages.nix. Most Perl
+packages are so straight-forward to build that they are defined here
+directly, rather than having a separate function for each package
+called from perl-packages.nix. However, more
+complicated packages should be put in a separate file, typically in
+pkgs/development/perl-modules. Here is an
+example of the former:
+
+
+ClassC3 = buildPerlPackage rec {
+ name = "Class-C3-0.21";
+ src = fetchurl {
+ url = "mirror://cpan/authors/id/F/FL/FLORA/${name}.tar.gz";
+ sha256 = "1bl8z095y4js66pwxnm7s853pi9czala4sqc743fdlnk27kq94gz";
+ };
+};
+
+
+Note the use of mirror://cpan/, and the
+${name} in the URL definition to ensure that the
+name attribute is consistent with the source that we’re actually
+downloading. Perl packages are made available in
+all-packages.nix through the variable
+perlPackages. For instance, if you have a package
+that needs ClassC3, you would typically write
+
+
+foo = import ../path/to/foo.nix {
+ inherit stdenv fetchurl ...;
+ inherit (perlPackages) ClassC3;
+};
+
+
+in all-packages.nix. You can test building a
+Perl package as follows:
+
+
+$ nix-build -A perlPackages.ClassC3
+
+
+buildPerlPackage adds perl- to
+the start of the name attribute, so the package above is actually
+called perl-Class-C3-0.21. So to install it, you
+can say:
+
+
+$ nix-env -i perl-Class-C3
+
+
+(Of course you can also install using the attribute name:
+nix-env -i -A perlPackages.ClassC3.)
+
+So what does buildPerlPackage do? It does
+the following:
+
+
+
+ In the configure phase, it calls perl
+ Makefile.PL to generate a Makefile. You can set the
+ variable makeMakerFlags to pass flags to
+ Makefile.PL
+
+ It adds the contents of the PERL5LIB
+ environment variable to #! .../bin/perl line of
+ Perl scripts as -Idir
+ flags. This ensures that a script can find its
+ dependencies.
+
+ In the fixup phase, it writes the propagated build
+ inputs (propagatedBuildInputs) to the file
+ $out/nix-support/propagated-user-env-packages.
+ nix-env recursively installs all packages listed
+ in this file when you install a package that has it. This ensures
+ that a Perl package can find its dependencies.
+
+
+
+
+
+buildPerlPackage is built on top of
+stdenv, so everything can be customised in the
+usual way. For instance, the BerkeleyDB module has
+a preConfigure hook to generate a configuration
+file used by Makefile.PL:
+
+
+{ buildPerlPackage, fetchurl, db }:
+
+buildPerlPackage rec {
+ name = "BerkeleyDB-0.36";
+
+ src = fetchurl {
+ url = "mirror://cpan/authors/id/P/PM/PMQS/${name}.tar.gz";
+ sha256 = "07xf50riarb60l1h6m2dqmql8q5dij619712fsgw7ach04d8g3z1";
+ };
+
+ preConfigure = ''
+ echo "LIB = ${db}/lib" > config.in
+ echo "INCLUDE = ${db}/include" >> config.in
+ '';
+}
+
+
+
+
+Dependencies on other Perl packages can be specified in the
+buildInputs and
+propagatedBuildInputs attributes. If something is
+exclusively a build-time dependency, use
+buildInputs; if it’s (also) a runtime dependency,
+use propagatedBuildInputs. For instance, this
+builds a Perl module that has runtime dependencies on a bunch of other
+modules:
+
+
+ClassC3Componentised = buildPerlPackage rec {
+ name = "Class-C3-Componentised-1.0004";
+ src = fetchurl {
+ url = "mirror://cpan/authors/id/A/AS/ASH/${name}.tar.gz";
+ sha256 = "0xql73jkcdbq4q9m0b0rnca6nrlvf5hyzy8is0crdk65bynvs8q1";
+ };
+ propagatedBuildInputs = [
+ ClassC3 ClassInspector TestException MROCompat
+ ];
+};
+
+
+
+
+Generation from CPAN
+
+Nix expressions for Perl packages can be generated (almost)
+automatically from CPAN. This is done by the program
+nix-generate-from-cpan, which can be installed
+as follows:
+
+
+$ nix-env -i nix-generate-from-cpan
+
+
+This program takes a Perl module name, looks it up on CPAN,
+fetches and unpacks the corresponding package, and prints a Nix
+expression on standard output. For example:
+
+
+$ nix-generate-from-cpan XML::Simple
+ XMLSimple = buildPerlPackage {
+ name = "XML-Simple-2.20";
+ src = fetchurl {
+ url = mirror://cpan/authors/id/G/GR/GRANTM/XML-Simple-2.20.tar.gz;
+ sha256 = "5cff13d0802792da1eb45895ce1be461903d98ec97c9c953bc8406af7294434a";
+ };
+ propagatedBuildInputs = [ XMLNamespaceSupport XMLSAX XMLSAXExpat ];
+ meta = {
+ description = "Easily read/write XML (esp config files)";
+ license = "perl";
+ };
+ };
+
+
+The output can be pasted into
+pkgs/top-level/perl-packages.nix or wherever else
+you need it.
+
+
+
+
+
diff --git a/doc/languages-frameworks/python.xml b/doc/languages-frameworks/python.xml
new file mode 100644
index 000000000000..57aceeb48685
--- /dev/null
+++ b/doc/languages-frameworks/python.xml
@@ -0,0 +1,447 @@
+
+
+Python
+
+
+ Currently supported interpreters are python26, python27,
+ python33, python34, python35
+ and pypy.
+
+
+
+ python is an alias to python27 and python3 is an alias to python34.
+
+
+
+ python26 and python27 do not include modules that require
+ external dependencies (to reduce dependency bloat). Following modules need to be added as
+ buildInput explicitly:
+
+
+
+ python.modules.bsddb
+ python.modules.curses
+ python.modules.curses_panel
+ python.modules.crypt
+ python.modules.gdbm
+ python.modules.sqlite3
+ python.modules.tkinter
+ python.modules.readline
+
+
+For convenience python27Full and python26Full
+are provided with all modules included.
+
+
+ Python packages that
+ use setuptools or distutils,
+ can be built using the buildPythonPackage function as documented below.
+
+
+
+ All packages depending on any Python interpreter get appended $out/${python.sitePackages}
+ to $PYTHONPATH if such directory exists.
+
+
+
+
+ Useful attributes on interpreters packages:
+
+
+
+ libPrefix
+
+ Name of the folder in ${python}/lib/ for corresponding interpreter.
+
+
+
+
+ interpreter
+
+ Alias for ${python}/bin/${executable}.
+
+
+
+
+ buildEnv
+
+ Function to build python interpreter environments with extra packages bundled together.
+ See for usage and documentation.
+
+
+
+
+ sitePackages
+
+ Alias for lib/${libPrefix}/site-packages.
+
+
+
+
+ executable
+
+ Name of the interpreter executable, ie python3.4.
+
+
+
+
+<varname>buildPythonPackage</varname> function
+
+
+ The function is implemented in
+ pkgs/development/python-modules/generic/default.nix.
+ Example usage:
+
+
+twisted = buildPythonPackage {
+ name = "twisted-8.1.0";
+
+ src = pkgs.fetchurl {
+ url = http://tmrc.mit.edu/mirror/twisted/Twisted/8.1/Twisted-8.1.0.tar.bz2;
+ sha256 = "0q25zbr4xzknaghha72mq57kh53qw1bf8csgp63pm9sfi72qhirl";
+ };
+
+ propagatedBuildInputs = [ self.ZopeInterface ];
+
+ meta = {
+ homepage = http://twistedmatrix.com/;
+ description = "Twisted, an event-driven networking engine written in Python";
+ license = stdenv.lib.licenses.mit;
+ };
+};
+
+
+ Most of Python packages that use buildPythonPackage are defined
+ in pkgs/top-level/python-packages.nix
+ and generated for each python interpreter separately into attribute sets python26Packages,
+ python27Packages, python35Packages, python33Packages,
+ python34Packages and pypyPackages.
+
+
+
+ buildPythonPackage mainly does four things:
+
+
+
+ In the buildPhase, it calls
+ ${python.interpreter} setup.py bdist_wheel to build a wheel binary zipfile.
+
+
+
+ In the installPhase, it installs the wheel file using
+ pip install *.whl.
+
+
+
+ In the postFixup phase, wrapPythonPrograms
+ bash function is called to wrap all programs in $out/bin/*
+ directory to include $PYTHONPATH and $PATH
+ environment variables.
+
+
+
+ In the installCheck phase, ${python.interpreter} setup.py test
+ is ran.
+
+
+
+
+ By default doCheck = true is set
+
+
+ As in Perl, dependencies on other Python packages can be specified in the
+ buildInputs and
+ propagatedBuildInputs attributes. If something is
+ exclusively a build-time dependency, use
+ buildInputs; if it’s (also) a runtime dependency,
+ use propagatedBuildInputs.
+
+
+
+ By default meta.platforms is set to the same value
+ as the interpreter unless overriden otherwise.
+
+
+
+
+ <varname>buildPythonPackage</varname> parameters
+ (all parameters from <varname>mkDerivation</varname> function are still supported)
+
+
+
+ namePrefix
+
+ Prepended text to ${name} parameter.
+ Defaults to "python3.3-" for Python 3.3, etc. Set it to
+ ""
+ if you're packaging an application or a command line tool.
+
+
+
+
+ disabled
+
+ If true, package is not build for
+ particular python interpreter version. Grep around
+ pkgs/top-level/python-packages.nix
+ for examples.
+
+
+
+
+ setupPyBuildFlags
+
+ List of flags passed to setup.py build_ext command.
+
+
+
+
+ pythonPath
+
+ List of packages to be added into $PYTHONPATH.
+ Packages in pythonPath are not propagated
+ (contrary to propagatedBuildInputs).
+
+
+
+
+ preShellHook
+
+ Hook to execute commands before shellHook.
+
+
+
+
+ postShellHook
+
+ Hook to execute commands after shellHook.
+
+
+
+
+ makeWrapperArgs
+
+ A list of strings. Arguments to be passed to
+ makeWrapper, which wraps generated binaries. By
+ default, the arguments to makeWrapper set
+ PATH and PYTHONPATH 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,
+ makeWrapperArgs = ["--set FOO BAR" "--set BAZ QUX"].
+
+
+
+
+
+
+
+<function>python.buildEnv</function> function
+
+ Create Python environments using low-level pkgs.buildEnv function. Example default.nix:
+
+
+ {};
+
+python.buildEnv.override {
+ extraLibs = [ pkgs.pythonPackages.pyramid ];
+ ignoreCollisions = true;
+}]]>
+
+
+ Running nix-build will create
+ /nix/store/cf1xhjwzmdki7fasgr4kz6di72ykicl5-python-2.7.8-env
+ with wrapped binaries in bin/.
+
+
+
+ You can also use env attribute to create local
+ environments with needed packages installed (somewhat comparable to
+ virtualenv). For example, with the following
+ shell.nix:
+
+
+ {};
+
+(python3.buildEnv.override {
+ extraLibs = with python3Packages;
+ [ numpy
+ requests
+ ];
+}).env]]>
+
+
+ Running nix-shell will drop you into a shell where
+ python will have specified packages in its path.
+
+
+
+
+ <function>python.buildEnv</function> arguments
+
+
+
+ extraLibs
+
+ List of packages installed inside the environment.
+
+
+
+
+ postBuild
+
+ Shell command executed after the build of environment.
+
+
+
+
+ ignoreCollisions
+
+ Ignore file collisions inside the environment (default is false).
+
+
+
+
+
+Tools
+
+Packages inside nixpkgs are written by hand. However many tools
+exist in community to help save time. No tool is preferred at the moment.
+
+
+
+
+
+ python2nix
+ by Vladimir Kirillov
+
+
+
+ pypi2nix
+ by Rok Garbas
+
+
+
+ pypi2nix
+ by Jaka Hudoklin
+
+
+
+
+
+
+Development
+
+
+ To develop Python packages buildPythonPackage has
+ additional logic inside shellPhase to run
+ pip install -e . --prefix $TMPDIR/ for the package.
+
+
+ shellPhase is executed only if setup.py
+ exists.
+
+
+ Given a default.nix:
+
+
+ {};
+
+buildPythonPackage {
+ name = "myproject";
+
+ buildInputs = with pkgs.pythonPackages; [ pyramid ];
+
+ src = ./.;
+}]]>
+
+
+ Running nix-shell with no arguments should give you
+ the environment in which the package would be build with
+ nix-build.
+
+
+
+ Shortcut to setup environments with C headers/libraries and python packages:
+
+ $ nix-shell -p pythonPackages.pyramid zlib libjpeg git
+
+
+
+ There is a boolean value lib.inNixShell set to
+ true if nix-shell is invoked.
+
+
+
+
+FAQ
+
+
+
+
+ How to solve circular dependencies?
+
+ If you have packages A and B that
+ depend on each other, when packaging B override package
+ A not to depend on B as input
+ (and also the other way around).
+
+
+
+
+ install_data / data_files problems resulting into error: could not create '/nix/store/6l1bvljpy8gazlsw2aw9skwwp4pmvyxw-python-2.7.8/etc': Permission denied
+
+
+ Known bug in setuptools install_data does not respect --prefix. Example of
+ such package using the feature is pkgs/tools/X11/xpra/default.nix. As workaround
+ install it as an extra preInstall step:
+
+ ${python.interpreter} setup.py install_data --install-dir=$out --root=$out
+sed -i '/ = data_files/d' setup.py
+
+
+
+
+ Rationale of non-existent global site-packages
+
+ There is no need to have global site-packages in Nix. Each package has isolated
+ dependency tree and installing any python package will only populate $PATH
+ inside user environment. See to create self-contained
+ interpreter with a set of packages.
+
+
+
+
+
+
+
+
+Contributing guidelines
+
+ Following rules are desired to be respected:
+
+
+
+
+
+ Make sure package builds for all python interpreters. Use disabled argument to
+ buildPythonPackage to set unsupported interpreters.
+
+
+
+ If tests need to be disabled for a package, make sure you leave a comment about reasoning.
+
+
+
+ Packages in pkgs/top-level/python-packages.nix
+ are sorted quasi-alphabetically to avoid merge conflicts.
+
+
+
+
+
+
+
+
diff --git a/doc/languages-frameworks/qt.xml b/doc/languages-frameworks/qt.xml
new file mode 100644
index 000000000000..093c33c25a17
--- /dev/null
+++ b/doc/languages-frameworks/qt.xml
@@ -0,0 +1,70 @@
+
+
+Qt
+
+The information in this section applies to Qt 5.5 and later.
+
+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.
+
+Libraries
+
+Packages that provide libraries should be listed in
+qt5LibsFun so that the library is built with each
+Qt version. A set of packages is provided for each version of Qt; for
+example, qt5Libs always provides libraries built
+with the latest version, qt55Libs provides
+libraries built with Qt 5.5, and so on. To avoid version conflicts, no
+top-level attributes are created for these packages.
+
+
+
+Programs
+
+Application packages do not need to be built with every Qt
+version. To ensure consistency between the package's dependencies,
+call the package with qt5Libs.callPackage instead
+of the usual callPackage. An older version may be
+selected in case of incompatibility. For example, to build with Qt
+5.5, call the package with
+qt55Libs.callPackage.
+
+Several environment variables must be set at runtime for Qt
+applications to function correctly, including:
+
+
+ QT_PLUGIN_PATH
+ QML_IMPORT_PATH
+ QML2_IMPORT_PATH
+ XDG_DATA_DIRS
+
+
+To ensure that these are set correctly, the program must be wrapped by
+invoking wrapQtProgram program
+during installation (for example, during
+fixupPhase). wrapQtProgram
+accepts the same options as makeWrapper.
+
+
+
+
+KDE
+
+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 wrapKDEProgram
+program during
+installation. wrapKDEProgram also generates a
+ksycoca database so that required data and services
+can be found. Like its Qt counterpart,
+wrapKDEProgram accepts the same options as
+makeWrapper.
+
+
+
+
+
diff --git a/doc/languages-frameworks/ruby.xml b/doc/languages-frameworks/ruby.xml
new file mode 100644
index 000000000000..a2b4475a4a54
--- /dev/null
+++ b/doc/languages-frameworks/ruby.xml
@@ -0,0 +1,46 @@
+
+
+Ruby
+
+ There currently is support to bundle applications that are packaged as Ruby gems. The utility "bundix" allows you to write a Gemfile, let bundler create a Gemfile.lock, and then convert
+ this into a nix expression that contains all Gem dependencies automatically.
+
+ For example, to package sensu, we did:
+
+
+ Gemfile
+source 'https://rubygems.org'
+gem 'sensu'
+$ bundler package --path /tmp/vendor/bundle
+$ $(nix-build '' -A bundix)/bin/bundix
+$ cat > default.nix
+{ lib, bundlerEnv, ruby }:
+
+bundlerEnv {
+ name = "sensu-0.17.1";
+
+ inherit ruby;
+ gemfile = ./Gemfile;
+ lockfile = ./Gemfile.lock;
+ gemset = ./gemset.nix;
+
+ meta = with lib; {
+ description = "A monitoring framework that aims to be simple, malleable,
+and scalable.";
+ homepage = http://sensuapp.org/;
+ license = with licenses; mit;
+ maintainers = with maintainers; [ theuni ];
+ platforms = platforms.unix;
+ };
+}]]>
+
+
+Please check in the Gemfile, Gemfile.lock and the gemset.nix so future updates can be run easily.
+
+
+
+
diff --git a/doc/manual.xml b/doc/manual.xml
index 3ffe7fbb068a..b4c35d1a379d 100644
--- a/doc/manual.xml
+++ b/doc/manual.xml
@@ -15,7 +15,7 @@
-
+