diff options
| author | John Ericson <John.Ericson@Obsidian.Systems> | 2019-11-24 17:25:07 +0000 |
|---|---|---|
| committer | John Ericson <John.Ericson@Obsidian.Systems> | 2019-11-24 17:25:07 +0000 |
| commit | d0d5136cce5e0cbe2305c53090bd4bd886114746 (patch) | |
| tree | 70092947536a3c65e215df9df20e571e34652f7a /doc/languages-frameworks | |
| parent | 9b090ccbca3f7dd26d91db06e96e8bf8282c37ca (diff) | |
| parent | 195c263a812dec532656dcfd5d0360458cdc93fd (diff) | |
Merge remote-tracking branch 'upstream/master' into wrapper-pname-support
Diffstat (limited to 'doc/languages-frameworks')
23 files changed, 512 insertions, 833 deletions
diff --git a/doc/languages-frameworks/android.section.md b/doc/languages-frameworks/android.section.md index f268c55256602..9a5df2523a25a 100644 --- a/doc/languages-frameworks/android.section.md +++ b/doc/languages-frameworks/android.section.md @@ -95,7 +95,7 @@ $ nix-build The Android SDK gets deployed with all desired plugin versions. -We can also deploy subsets of the Android SDK. For example, to only the the +We can also deploy subsets of the Android SDK. For example, to only the `platform-tools` package, you can evaluate the following expression: ```nix diff --git a/doc/languages-frameworks/beam.xml b/doc/languages-frameworks/beam.xml index dee7f2d74191e..278535237c2c6 100644 --- a/doc/languages-frameworks/beam.xml +++ b/doc/languages-frameworks/beam.xml @@ -7,12 +7,7 @@ <title>Introduction</title> <para> - In this document and related Nix expressions, we use the term, - <emphasis>BEAM</emphasis>, to describe the environment. BEAM is the name of - the Erlang Virtual Machine and, as far as we're concerned, from a packaging - perspective, all languages that run on the BEAM are interchangeable. That - which varies, like the build system, is transparent to users of any given - BEAM package, so we make no distinction. + In this document and related Nix expressions, we use the term, <emphasis>BEAM</emphasis>, to describe the environment. BEAM is the name of the Erlang Virtual Machine and, as far as we're concerned, from a packaging perspective, all languages that run on the BEAM are interchangeable. That which varies, like the build system, is transparent to users of any given BEAM package, so we make no distinction. </para> </section> @@ -20,57 +15,32 @@ <title>Structure</title> <para> - All BEAM-related expressions are available via the top-level - <literal>beam</literal> attribute, which includes: + All BEAM-related expressions are available via the top-level <literal>beam</literal> attribute, which includes: </para> <itemizedlist> <listitem> <para> - <literal>interpreters</literal>: a set of compilers running on the BEAM, - including multiple Erlang/OTP versions - (<literal>beam.interpreters.erlangR19</literal>, etc), Elixir - (<literal>beam.interpreters.elixir</literal>) and LFE - (<literal>beam.interpreters.lfe</literal>). + <literal>interpreters</literal>: a set of compilers running on the BEAM, including multiple Erlang/OTP versions (<literal>beam.interpreters.erlangR19</literal>, etc), Elixir (<literal>beam.interpreters.elixir</literal>) and LFE (<literal>beam.interpreters.lfe</literal>). </para> </listitem> <listitem> <para> - <literal>packages</literal>: a set of package sets, each compiled with a - specific Erlang/OTP version, e.g. - <literal>beam.packages.erlangR19</literal>. + <literal>packages</literal>: a set of package builders (Mix and rebar3), each compiled with a specific Erlang/OTP version, e.g. <literal>beam.packages.erlangR19</literal>. </para> </listitem> </itemizedlist> <para> - The default Erlang compiler, defined by - <literal>beam.interpreters.erlang</literal>, is aliased as - <literal>erlang</literal>. The default BEAM package set is defined by - <literal>beam.packages.erlang</literal> and aliased at the top level as - <literal>beamPackages</literal>. + The default Erlang compiler, defined by <literal>beam.interpreters.erlang</literal>, is aliased as <literal>erlang</literal>. The default BEAM package set is defined by <literal>beam.packages.erlang</literal> and aliased at the top level as <literal>beamPackages</literal>. </para> <para> - To create a package set built with a custom Erlang version, use the lambda, - <literal>beam.packagesWith</literal>, which accepts an Erlang/OTP derivation - and produces a package set similar to - <literal>beam.packages.erlang</literal>. + To create a package builder built with a custom Erlang version, use the lambda, <literal>beam.packagesWith</literal>, which accepts an Erlang/OTP derivation and produces a package builder similar to <literal>beam.packages.erlang</literal>. </para> <para> - Many Erlang/OTP distributions available in - <literal>beam.interpreters</literal> have versions with ODBC and/or Java - enabled. For example, there's - <literal>beam.interpreters.erlangR19_odbc_javac</literal>, which corresponds - to <literal>beam.interpreters.erlangR19</literal>. - </para> - - <para xml:id="erlang-call-package"> - We also provide the lambda, - <literal>beam.packages.erlang.callPackage</literal>, which simplifies - writing BEAM package definitions by injecting all packages from - <literal>beam.packages.erlang</literal> into the top-level context. + Many Erlang/OTP distributions available in <literal>beam.interpreters</literal> have versions with ODBC and/or Java enabled or without wx (no observer support). For example, there's <literal>beam.interpreters.erlangR22_odbc_javac</literal>, which corresponds to <literal>beam.interpreters.erlangR22</literal> and <literal>beam.interpreters.erlangR22_nox</literal>, which corresponds to <literal>beam.interpreters.erlangR22</literal>. </para> </section> @@ -81,28 +51,7 @@ <title>Rebar3</title> <para> - By default, Rebar3 wants to manage its own dependencies. This is perfectly - acceptable in the normal, non-Nix setup, but in the Nix world, it is not. - To rectify this, we provide two versions of Rebar3: - <itemizedlist> - <listitem> - <para> - <literal>rebar3</literal>: patched to remove the ability to download - anything. When not running it via <literal>nix-shell</literal> or - <literal>nix-build</literal>, it's probably not going to work as - desired. - </para> - </listitem> - <listitem> - <para> - <literal>rebar3-open</literal>: the normal, unmodified Rebar3. It should - work exactly as would any other version of Rebar3. Any Erlang package - should rely on <literal>rebar3</literal> instead. See - <xref - linkend="rebar3-packages"/>. - </para> - </listitem> - </itemizedlist> + We provide a version of Rebar3, under <literal>rebar3</literal>. We also provide a helper to fetch Rebar3 dependencies from a lockfile under <literal>fetchRebar3Deps</literal>. </para> </section> @@ -110,10 +59,7 @@ <title>Mix & Erlang.mk</title> <para> - Both Mix and Erlang.mk work exactly as expected. There is a bootstrap - process that needs to be run for both, however, which is supported by the - <literal>buildMix</literal> and <literal>buildErlangMk</literal> - derivations, respectively. + Both Mix and Erlang.mk work exactly as expected. There is a bootstrap process that needs to be run for both, however, which is supported by the <literal>buildMix</literal> and <literal>buildErlangMk</literal> derivations, respectively. </para> </section> </section> @@ -122,41 +68,14 @@ <title>How to Install BEAM Packages</title> <para> - BEAM packages are not registered at the top level, simply because they are - not relevant to the vast majority of Nix users. They are installable using - the <literal>beam.packages.erlang</literal> attribute set (aliased as - <literal>beamPackages</literal>), which points to packages built by the - default Erlang/OTP version in Nixpkgs, as defined by - <literal>beam.interpreters.erlang</literal>. To list the available packages - in <literal>beamPackages</literal>, use the following command: - </para> - -<screen> -<prompt>$ </prompt>nix-env -f "<nixpkgs>" -qaP -A beamPackages -beamPackages.esqlite esqlite-0.2.1 -beamPackages.goldrush goldrush-0.1.7 -beamPackages.ibrowse ibrowse-4.2.2 -beamPackages.jiffy jiffy-0.14.5 -beamPackages.lager lager-3.0.2 -beamPackages.meck meck-0.8.3 -beamPackages.rebar3-pc pc-1.1.0 -</screen> - - <para> - To install any of those packages into your profile, refer to them by their - attribute path (first column): + BEAM builders are not registered at the top level, simply because they are not relevant to the vast majority of Nix users. + To install any of those builders into your profile, refer to them by their attribute path <literal>beamPackages.rebar3</literal>: </para> -<screen> -<prompt>$ </prompt>nix-env -f "<nixpkgs>" -iA beamPackages.ibrowse -</screen> - - <para> - The attribute path of any BEAM package corresponds to the name of that - particular package in <link xlink:href="https://hex.pm">Hex</link> or its - OTP Application/Release name. - </para> - </section> + <screen> + <prompt>$ </prompt>nix-env -f "<nixpkgs>" -iA beamPackages.rebar3 + </screen> +</section> <section xml:id="packaging-beam-applications"> <title>Packaging BEAM Applications</title> @@ -168,53 +87,11 @@ beamPackages.rebar3-pc pc-1.1.0 <title>Rebar3 Packages</title> <para> - The Nix function, <literal>buildRebar3</literal>, defined in - <literal>beam.packages.erlang.buildRebar3</literal> and aliased at the top - level, can be used to build a derivation that understands how to build a - Rebar3 project. For example, we can build - <link - xlink:href="https://github.com/erlang-nix/hex2nix">hex2nix</link> - as follows: - </para> - -<programlisting> -{ stdenv, fetchFromGitHub, buildRebar3, ibrowse, jsx, erlware_commons }: - -buildRebar3 rec { - name = "hex2nix"; - version = "0.0.1"; - - src = fetchFromGitHub { - owner = "ericbmerritt"; - repo = "hex2nix"; - rev = "${version}"; - sha256 = "1w7xjidz1l5yjmhlplfx7kphmnpvqm67w99hd2m7kdixwdxq0zqg"; - }; - - beamDeps = [ ibrowse jsx erlware_commons ]; -} -</programlisting> - - <para> - Such derivations are callable with - <literal>beam.packages.erlang.callPackage</literal> (see - <xref - linkend="erlang-call-package"/>). To call this package using - the normal <literal>callPackage</literal>, refer to dependency packages - via <literal>beamPackages</literal>, e.g. - <literal>beamPackages.ibrowse</literal>. - </para> - - <para> - Notably, <literal>buildRebar3</literal> includes - <literal>beamDeps</literal>, while <literal>stdenv.mkDerivation</literal> - does not. BEAM dependencies added there will be correctly handled by the - system. + The Nix function, <literal>buildRebar3</literal>, defined in <literal>beam.packages.erlang.buildRebar3</literal> and aliased at the top level, can be used to build a derivation that understands how to build a Rebar3 project. </para> <para> - If a package needs to compile native code via Rebar3's port compilation - mechanism, add <literal>compilePort = true;</literal> to the derivation. + If a package needs to compile native code via Rebar3's port compilation mechanism, add <literal>compilePort = true;</literal> to the derivation. </para> </section> @@ -222,96 +99,21 @@ buildRebar3 rec { <title>Erlang.mk Packages</title> <para> - Erlang.mk functions similarly to Rebar3, except we use - <literal>buildErlangMk</literal> instead of - <literal>buildRebar3</literal>. + Erlang.mk functions similarly to Rebar3, except we use <literal>buildErlangMk</literal> instead of <literal>buildRebar3</literal>. </para> -<programlisting> -{ buildErlangMk, fetchHex, cowlib, ranch }: - -buildErlangMk { - name = "cowboy"; - version = "1.0.4"; - - src = fetchHex { - pkg = "cowboy"; - version = "1.0.4"; - sha256 = "6a0edee96885fae3a8dd0ac1f333538a42e807db638a9453064ccfdaa6b9fdac"; - }; - - beamDeps = [ cowlib ranch ]; - - meta = { - description = '' - Small, fast, modular HTTP server written in Erlang - ''; - license = stdenv.lib.licenses.isc; - homepage = https://github.com/ninenines/cowboy; - }; -} -</programlisting> </section> <section xml:id="mix-packages"> <title>Mix Packages</title> <para> - Mix functions similarly to Rebar3, except we use - <literal>buildMix</literal> instead of <literal>buildRebar3</literal>. + Mix functions similarly to Rebar3, except we use <literal>buildMix</literal> instead of <literal>buildRebar3</literal>. </para> -<programlisting> -{ buildMix, fetchHex, plug, absinthe }: - -buildMix { - name = "absinthe_plug"; - version = "1.0.0"; - - src = fetchHex { - pkg = "absinthe_plug"; - version = "1.0.0"; - sha256 = "08459823fe1fd4f0325a8bf0c937a4520583a5a26d73b193040ab30a1dfc0b33"; - }; - - beamDeps = [ plug absinthe ]; - - meta = { - description = '' - A plug for Absinthe, an experimental GraphQL toolkit - ''; - license = stdenv.lib.licenses.bsd3; - homepage = https://github.com/CargoSense/absinthe_plug; - }; -} -</programlisting> - <para> Alternatively, we can use <literal>buildHex</literal> as a shortcut: </para> - -<programlisting> -{ buildHex, buildMix, plug, absinthe }: - -buildHex { - name = "absinthe_plug"; - version = "1.0.0"; - - sha256 = "08459823fe1fd4f0325a8bf0c937a4520583a5a26d73b193040ab30a1dfc0b33"; - - builder = buildMix; - - beamDeps = [ plug absinthe ]; - - meta = { - description = '' - A plug for Absinthe, an experimental GraphQL toolkit - ''; - license = stdenv.lib.licenses.bsd3; - homepage = https://github.com/CargoSense/absinthe_plug; - }; -} -</programlisting> </section> </section> </section> @@ -319,75 +121,13 @@ buildHex { <section xml:id="how-to-develop"> <title>How to Develop</title> - <section xml:id="accessing-an-environment"> - <title>Accessing an Environment</title> - - <para> - Often, we simply want to access a valid environment that contains a - specific package and its dependencies. We can accomplish that with the - <literal>env</literal> attribute of a derivation. For example, let's say we - want to access an Erlang REPL with <literal>ibrowse</literal> loaded up. We - could do the following: - </para> - -<screen> -<prompt>$ </prompt><userinput>nix-shell -A beamPackages.ibrowse.env --run "erl"</userinput> -<computeroutput>Erlang/OTP 18 [erts-7.0] [source] [64-bit] [smp:4:4] [async-threads:10] [hipe] [kernel-poll:false] - -Eshell V7.0 (abort with ^G)</computeroutput> -<prompt>1> </prompt><userinput>m(ibrowse).</userinput> -<computeroutput>Module: ibrowse -MD5: 3b3e0137d0cbb28070146978a3392945 -Compiled: January 10 2016, 23:34 -Object file: /nix/store/g1rlf65rdgjs4abbyj4grp37ry7ywivj-ibrowse-4.2.2/lib/erlang/lib/ibrowse-4.2.2/ebin/ibrowse.beam -Compiler options: [{outdir,"/tmp/nix-build-ibrowse-4.2.2.drv-0/hex-source-ibrowse-4.2.2/_build/default/lib/ibrowse/ebin"}, -debug_info,debug_info,nowarn_shadow_vars, -warn_unused_import,warn_unused_vars,warnings_as_errors, -{i,"/tmp/nix-build-ibrowse-4.2.2.drv-0/hex-source-ibrowse-4.2.2/_build/default/lib/ibrowse/include"}] -Exports: -add_config/1 send_req_direct/7 -all_trace_off/0 set_dest/3 -code_change/3 set_max_attempts/3 -get_config_value/1 set_max_pipeline_size/3 -get_config_value/2 set_max_sessions/3 -get_metrics/0 show_dest_status/0 -get_metrics/2 show_dest_status/1 -handle_call/3 show_dest_status/2 -handle_cast/2 spawn_link_worker_process/1 -handle_info/2 spawn_link_worker_process/2 -init/1 spawn_worker_process/1 -module_info/0 spawn_worker_process/2 -module_info/1 start/0 -rescan_config/0 start_link/0 -rescan_config/1 stop/0 -send_req/3 stop_worker_process/1 -send_req/4 stream_close/1 -send_req/5 stream_next/1 -send_req/6 terminate/2 -send_req_direct/4 trace_off/0 -send_req_direct/5 trace_off/2 -send_req_direct/6 trace_on/0 -trace_on/2 -ok</computeroutput> -<prompt>2></prompt> -</screen> - - <para> - Notice the <literal>-A beamPackages.ibrowse.env</literal>. That is the key - to this functionality. - </para> - </section> - <section xml:id="creating-a-shell"> <title>Creating a Shell</title> - <para> - Getting access to an environment often isn't enough to do real development. - Usually, we need to create a <literal>shell.nix</literal> file and do our - development inside of the environment specified therein. This file looks a - lot like the packaging described above, except that <literal>src</literal> - points to the project root and we call the package directly. - </para> + <para> + Usually, we need to create a <literal>shell.nix</literal> file and do our development inside of the environment specified therein. Just install your version of erlang and other interpreter, and then user your normal build tools. + As an example with elixir: + </para> <programlisting> { pkgs ? import "<nixpkgs"> {} }: @@ -396,133 +136,24 @@ with pkgs; let - f = { buildRebar3, ibrowse, jsx, erlware_commons }: - buildRebar3 { - name = "hex2nix"; - version = "0.1.0"; - src = ./.; - beamDeps = [ ibrowse jsx erlware_commons ]; - }; - drv = beamPackages.callPackage f {}; + elixir = beam.packages.erlangR22.elixir_1_9; in +mkShell { + buildInputs = [ elixir ]; - drv + ERL_INCLUDE_PATH="${erlang}/lib/erlang/usr/include"; +} </programlisting> <section xml:id="building-in-a-shell"> <title>Building in a Shell (for Mix Projects)</title> <para> - We can leverage the support of the derivation, irrespective of the build - derivation, by calling the commands themselves. - </para> - -<programlisting> -# ============================================================================= -# Variables -# ============================================================================= - -NIX_TEMPLATES := "$(CURDIR)/nix-templates" - -TARGET := "$(PREFIX)" - -PROJECT_NAME := thorndyke - -NIXPKGS=../nixpkgs -NIX_PATH=nixpkgs=$(NIXPKGS) -NIX_SHELL=nix-shell -I "$(NIX_PATH)" --pure -# ============================================================================= -# Rules -# ============================================================================= -.PHONY= all test clean repl shell build test analyze configure install \ - test-nix-install publish plt analyze - -all: build - -guard-%: - @ if [ "${${*}}" == "" ]; then \ - echo "Environment variable $* not set"; \ - exit 1; \ - fi - -clean: - rm -rf _build - rm -rf .cache - -repl: - $(NIX_SHELL) --run "iex -pa './_build/prod/lib/*/ebin'" - -shell: - $(NIX_SHELL) - -configure: - $(NIX_SHELL) --command 'eval "$$configurePhase"' - -build: configure - $(NIX_SHELL) --command 'eval "$$buildPhase"' - -install: - $(NIX_SHELL) --command 'eval "$$installPhase"' - -test: - $(NIX_SHELL) --command 'mix test --no-start --no-deps-check' - -plt: - $(NIX_SHELL) --run "mix dialyzer.plt --no-deps-check" - -analyze: build plt - $(NIX_SHELL) --run "mix dialyzer --no-compile" - -</programlisting> - - <para> - Using a <literal>shell.nix</literal> as described (see - <xref - linkend="creating-a-shell"/>) should just work. Aside from - <literal>test</literal>, <literal>plt</literal>, and - <literal>analyze</literal>, the Make targets work just fine for all of the - build derivations. + Using a <literal>shell.nix</literal> as described (see <xref + linkend="creating-a-shell"/>) should just work. </para> </section> </section> </section> - - <section xml:id="generating-packages-from-hex-with-hex2nix"> - <title>Generating Packages from Hex with <literal>hex2nix</literal></title> - - <para> - Updating the <link xlink:href="https://hex.pm">Hex</link> package set - requires - <link - xlink:href="https://github.com/erlang-nix/hex2nix">hex2nix</link>. - Given the path to the Erlang modules (usually - <literal>pkgs/development/erlang-modules</literal>), it will dump a file - called <literal>hex-packages.nix</literal>, containing all the packages that - use a recognized build system in - <link - xlink:href="https://hex.pm">Hex</link>. It can't be determined, - however, whether every package is buildable. - </para> - - <para> - To make life easier for our users, try to build every - <link - xlink:href="https://hex.pm">Hex</link> package and remove those - that fail. To do that, simply run the following command in the root of your - <literal>nixpkgs</literal> repository: - </para> - -<screen> -<prompt>$ </prompt>nix-build -A beamPackages -</screen> - - <para> - That will attempt to build every package in <literal>beamPackages</literal>. - Then manually remove those that fail. Hopefully, someone will improve - <link - xlink:href="https://github.com/erlang-nix/hex2nix">hex2nix</link> - in the future to automate the process. - </para> - </section> </section> diff --git a/doc/languages-frameworks/bower.xml b/doc/languages-frameworks/bower.xml index 118f6e10473ab..b0738cad293bc 100644 --- a/doc/languages-frameworks/bower.xml +++ b/doc/languages-frameworks/bower.xml @@ -4,32 +4,22 @@ <title>Bower</title> <para> - <link xlink:href="http://bower.io">Bower</link> is a package manager for web - site front-end components. Bower packages (comprising of build artefacts and - sometimes sources) are stored in <command>git</command> repositories, - typically on Github. The package registry is run by the Bower team with - package metadata coming from the <filename>bower.json</filename> file within - each package. + <link xlink:href="http://bower.io">Bower</link> is a package manager for web site front-end components. Bower packages (comprising of build artefacts and sometimes sources) are stored in <command>git</command> repositories, typically on Github. The package registry is run by the Bower team with package metadata coming from the <filename>bower.json</filename> file within each package. </para> <para> - The end result of running Bower is a <filename>bower_components</filename> - directory which can be included in the web app's build process. + The end result of running Bower is a <filename>bower_components</filename> directory which can be included in the web app's build process. </para> <para> - Bower can be run interactively, by installing - <varname>nodePackages.bower</varname>. More interestingly, the Bower - components can be declared in a Nix derivation, with the help of - <varname>nodePackages.bower2nix</varname>. + Bower can be run interactively, by installing <varname>nodePackages.bower</varname>. More interestingly, the Bower components can be declared in a Nix derivation, with the help of <varname>nodePackages.bower2nix</varname>. </para> <section xml:id="ssec-bower2nix-usage"> <title><command>bower2nix</command> usage</title> <para> - Suppose you have a <filename>bower.json</filename> with the following - contents: + Suppose you have a <filename>bower.json</filename> with the following contents: <example xml:id="ex-bowerJson"> <title><filename>bower.json</filename></title> <programlisting language="json"> @@ -45,8 +35,7 @@ </para> <para> - Running <command>bower2nix</command> will produce something like the - following output: + Running <command>bower2nix</command> will produce something like the following output: <programlisting language="nix"> <: An LLVM-to-JavaScript Compiler diff --git a/doc/languages-frameworks/gnome.xml b/doc/languages-frameworks/gnome.xml new file mode 100644 index 0000000000000..3d69d77a1c845 --- /dev/null +++ b/doc/languages-frameworks/gnome.xml @@ -0,0 +1,282 @@ +<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-language-gnome"> + <title>GNOME</title> + + <section xml:id="ssec-gnome-packaging"> + <title>Packaging GNOME applications</title> + + <para> + Programs in the GNOME universe are written in various languages but they all use GObject-based libraries like GLib, GTK or GStreamer. These libraries are often modular, relying on looking into certain directories to find their modules. However, due to Nix’s specific file system organization, this will fail without our intervention. Fortunately, the libraries usually allow overriding the directories through environment variables, either natively or thanks to a patch in nixpkgs. <link xlink:href="#fun-wrapProgram">Wrapping</link> the executables to ensure correct paths are available to the application constitutes a significant part of packaging a modern desktop application. In this section, we will describe various modules needed by such applications, environment variables needed to make the modules load, and finally a script that will do the work for us. + </para> + + <section xml:id="ssec-gnome-settings"> + <title>Settings</title> + + <para> + <link xlink:href="https://developer.gnome.org/gio/stable/GSettings.html">GSettings</link> API is often used for storing settings. GSettings schemas are required, to know the type and other metadata of the stored values. GLib looks for <filename>glib-2.0/schemas/gschemas.compiled</filename> files inside the directories of <envar>XDG_DATA_DIRS</envar>. + </para> + + <para> + On Linux, GSettings API is implemented using <link xlink:href="https://wiki.gnome.org/Projects/dconf">dconf</link> backend. You will need to add <literal>dconf</literal> GIO module to <envar>GIO_EXTRA_MODULES</envar> variable, otherwise the <literal>memory</literal> backend will be used and the saved settings will not be persistent. + </para> + + <para> + Last you will need the dconf database D-Bus service itself. You can enable it using <option>programs.dconf.enable</option>. + </para> + + <para> + Some applications will also require <package>gsettings-desktop-schemas</package> for things like reading proxy configuration or user interface customization. This dependency is often not mentioned by upstream, you should grep for <literal>org.gnome.desktop</literal> and <literal>org.gnome.system</literal> to see if the schemas are needed. + </para> + </section> + + <section xml:id="ssec-gnome-icons"> + <title>Icons</title> + + <para> + When an application uses icons, an icon theme should be available in <envar>XDG_DATA_DIRS</envar> during runtime. The package for the default, icon-less <link xlink:href="https://www.freedesktop.org/wiki/Software/icon-theme/">hicolor-icon-theme</link> (should be propagated by every icon theme) contains <link linkend="ssec-gnome-hooks-hicolor-icon-theme">a setup hook</link> that will pick up icon themes from <literal>buildInputs</literal> and pass it to our wrapper. Unfortunately, relying on that would mean every user has to download the theme included in the package expression no matter their preference. For that reason, we leave the installation of icon theme on the user. If you use one of the desktop environments, you probably already have an icon theme installed. + </para> + + <para> + To avoid costly file system access when locating icons, GTK, <link xlink:href="https://woboq.com/blog/qicon-reads-gtk-icon-cache-in-qt57.html">as well as Qt</link>, can rely on <filename>icon-theme.cache</filename> files from the themes’ top-level directories. These files are generated using <command>gtk-update-icon-cache</command>, which is expected to be run whenever an icon is added or removed to an icon theme (typically an application icon into <literal>hicolor</literal> theme) and some programs do indeed run this after icon installation. However, since packages are installed into their own prefix by Nix, this would lead to conflicts. For that reason, <package>gtk3</package> provides a <link xlink:href="#ssec-gnome-hooks-gtk-drop-icon-theme-cache">setup hook</link> that will clean the file from installation. Since most applications only ship their own icon that will be loaded on start-up, it should not affect them too much. On the other hand, icon themes are much larger and more widely used so we need to cache them. Because we recommend installing icon themes globally, we will generate the cache files from all packages in a profile using a NixOS module. You can enable the cache generation using <option>gtk.iconCache.enable</option> option if your desktop environment does not already do that. + </para> + </section> + + <section xml:id="ssec-gnome-themes"> + <title>GTK Themes</title> + + <para> + Previously, a GTK theme needed to be in <envar>XDG_DATA_DIRS</envar>. This is no longer necessary for most programs since GTK incorporated Adwaita theme. Some programs (for example, those designed for <link xlink:href="https://elementary.io/docs/human-interface-guidelines#human-interface-guidelines">elementary HIG</link>) might require a special theme like <package>pantheon.elementary-gtk-theme</package>. + </para> + </section> + + <section xml:id="ssec-gnome-typelibs"> + <title>GObject introspection typelibs</title> + + <para> + <link xlink:href="https://wiki.gnome.org/Projects/GObjectIntrospection">GObject introspection</link> allows applications to use C libraries in other languages easily. It does this through <literal>typelib</literal> files searched in <envar>GI_TYPELIB_PATH</envar>. + </para> + </section> + + <section xml:id="ssec-gnome-plugins"> + <title>Various plug-ins</title> + + <para> + If your application uses <link xlink:href="https://gstreamer.freedesktop.org/">GStreamer</link> or <link xlink:href="https://wiki.gnome.org/Projects/Grilo">Grilo</link>, you should set <envar>GST_PLUGIN_SYSTEM_PATH_1_0</envar> and <envar>GRL_PLUGIN_PATH</envar>, respectively. + </para> + </section> + </section> + + <section xml:id="ssec-gnome-hooks"> + <title>Onto <package>wrapGAppsHook</package></title> + + <para> + Given the requirements above, the package expression would become messy quickly: +<programlisting> +preFixup = '' + for f in $(find $out/bin/ $out/libexec/ -type f -executable); do + wrapProgram "$f" \ + --prefix GIO_EXTRA_MODULES : "${getLib gnome3.dconf}/lib/gio/modules" \ + --prefix XDG_DATA_DIRS : "$out/share" \ + --prefix XDG_DATA_DIRS : "$out/share/gsettings-schemas/${name}" \ + --prefix XDG_DATA_DIRS : "${gsettings-desktop-schemas}/share/gsettings-schemas/${gsettings-desktop-schemas.name}" \ + --prefix XDG_DATA_DIRS : "${hicolor-icon-theme}/share" \ + --prefix GI_TYPELIB_PATH : "${lib.makeSearchPath "lib/girepository-1.0" [ pango json-glib ]}" + done +''; +</programlisting> + Fortunately, there is <package>wrapGAppsHook</package>, that does the wrapping for us. In particular, it works in conjunction with other setup hooks that will populate the variable: + <itemizedlist> + <listitem xml:id="ssec-gnome-hooks-wrapgappshook"> + <para> + <package>wrapGAppsHook</package> itself will add the package’s <filename>share</filename> directory to <envar>XDG_DATA_DIRS</envar>. + </para> + </listitem> + <listitem xml:id="ssec-gnome-hooks-glib"> + <para> + <package>glib</package> setup hook will populate <envar>GSETTINGS_SCHEMAS_PATH</envar> and then <package>wrapGAppsHook</package> will prepend it to <envar>XDG_DATA_DIRS</envar>. + </para> + </listitem> + <listitem xml:id="ssec-gnome-hooks-gtk-drop-icon-theme-cache"> + <para> + One of <package>gtk3</package>’s setup hooks will remove <filename>icon-theme.cache</filename> files from package’s icon theme directories to avoid conflicts. Icon theme packages should prevent this with <code>dontDropIconThemeCache = true;</code>. + </para> + </listitem> + <listitem xml:id="ssec-gnome-hooks-dconf"> + <para> + <package>gnome3.dconf.lib</package> is a dependency of <package>wrapGAppsHook</package>, which then also adds it to the <envar>GIO_EXTRA_MODULES</envar> variable. + </para> + </listitem> + <listitem xml:id="ssec-gnome-hooks-hicolor-icon-theme"> + <para> + <package>hicolor-icon-theme</package>’s setup hook will add icon themes to <envar>XDG_ICON_DIRS</envar> which is prepended to <envar>XDG_DATA_DIRS</envar> by <package>wrapGAppsHook</package>. + </para> + </listitem> + <listitem xml:id="ssec-gnome-hooks-gobject-introspection"> + <para> + <package>gobject-introspection</package> setup hook populates <envar>GI_TYPELIB_PATH</envar> variable with <filename>lib/girepository-1.0</filename> directories of dependencies, which is then added to wrapper by <package>wrapGAppsHook</package>. It also adds <filename>share</filename> directories of dependencies to <envar>XDG_DATA_DIRS</envar>, which is intended to promote GIR files but it also <link xlink:href="https://github.com/NixOS/nixpkgs/issues/32790">pollutes the closures</link> of packages using <package>wrapGAppsHook</package>. + </para> + <warning> + <para> + The setup hook <link xlink:href="https://github.com/NixOS/nixpkgs/issues/56943">currently</link> does not work in expressions with <literal>strictDeps</literal> enabled, like Python packages. In those cases, you will need to disable it with <code>strictDeps = false;</code>. + </para> + </warning> + </listitem> + <listitem xml:id="ssec-gnome-hooks-gst-grl-plugins"> + <para> + Setup hooks of <package>gst_all_1.gstreamer</package> and <package>gnome3.grilo</package> will populate the <envar>GST_PLUGIN_SYSTEM_PATH_1_0</envar> and <envar>GRL_PLUGIN_PATH</envar> variables, respectively, which will then be added to the wrapper by <literal>wrapGAppsHook</literal>. + </para> + </listitem> + </itemizedlist> + </para> + + <para> + You can also pass additional arguments to <literal>makeWrapper</literal> using <literal>gappsWrapperArgs</literal> in <literal>preFixup</literal> hook: +<programlisting> +preFixup = '' + gappsWrapperArgs+=( + # Thumbnailers + --prefix XDG_DATA_DIRS : "${gdk-pixbuf}/share" + --prefix XDG_DATA_DIRS : "${librsvg}/share" + --prefix XDG_DATA_DIRS : "${shared-mime-info}/share" + ) +''; +</programlisting> + </para> + </section> + + <section xml:id="ssec-gnome-updating"> + <title>Updating GNOME packages</title> + + <para> + Most GNOME package offer <link linkend="var-passthru-updateScript"><literal>updateScript</literal></link>, it is therefore possible to update to latest source tarball by running <command>nix-shell maintainers/scripts/update.nix --argstr package gnome3.nautilus</command> or even en masse with <command>nix-shell maintainers/scripts/update.nix --argstr path gnome3</command>. Read the package’s <filename>NEWS</filename> file to see what changed. + </para> + </section> + + <section xml:id="ssec-gnome-common-issues"> + <title>Frequently encountered issues</title> + + <variablelist> + <varlistentry xml:id="ssec-gnome-common-issues-no-schemas"> + <term> + <computeroutput>GLib-GIO-ERROR **: <replaceable>06:04:50.903</replaceable>: No GSettings schemas are installed on the system</computeroutput> + </term> + <listitem> + <para> + There are no schemas avalable in <envar>XDG_DATA_DIRS</envar>. Temporarily add a random package containing schemas like <package>gsettings-desktop-schemas</package> to <literal>buildInputs</literal>. <link linkend="ssec-gnome-hooks-glib"><package>glib</package></link> and <link linkend="ssec-gnome-hooks-wrapgappshook"><package>wrapGAppsHook</package></link> setup hooks will take care of making the schemas available to application and you will see the actual missing schemas with the <link linkend="ssec-gnome-common-issues-missing-schema">next error</link>. Or you can try looking through the source code for the actual schemas used. + </para> + </listitem> + </varlistentry> + <varlistentry xml:id="ssec-gnome-common-issues-missing-schema"> + <term> + <computeroutput>GLib-GIO-ERROR **: <replaceable>06:04:50.903</replaceable>: Settings schema ‘<replaceable>org.gnome.foo</replaceable>’ is not installed</computeroutput> + </term> + <listitem> + <para> + Package is missing some GSettings schemas. You can find out the package containing the schema with <command>nix-locate <replaceable>org.gnome.foo</replaceable>.gschema.xml</command> and let the hooks handle the wrapping as <link linkend="ssec-gnome-common-issues-no-schemas">above</link>. + </para> + </listitem> + </varlistentry> + <varlistentry xml:id="ssec-gnome-common-issues-double-wrapped"> + <term> + When using <package>wrapGAppsHook</package> with special derivers you can end up with double wrapped binaries. + </term> + <listitem> + <para> + This is because derivers like <function>python.pkgs.buildPythonApplication</function> or <function>qt5.mkDerivation</function> have setup-hooks automatically added that produce wrappers with <package>makeWrapper</package>. The simplest way to workaround that is to disable the <package>wrapGAppsHook</package> automatic wrapping with <code>dontWrapGApps = true;</code> and pass the arguments it intended to pass to <package>makeWrapper</package> to another. + </para> + <para> + In the case of a Python application it could look like: +<programlisting> +python3.pkgs.buildPythonApplication { + pname = "gnome-music"; + version = "3.32.2"; + + nativeBuildInputs = [ + wrapGAppsHook + gobject-introspection + ... + ]; + + dontWrapGApps = true; + + # Arguments to be passed to `makeWrapper`, only used by buildPython* + makeWrapperArgs = [ + "\${gappsWrapperArgs[@]}" + ]; +} +</programlisting> + And for a QT app like: +<programlisting> +mkDerivation { + pname = "calibre"; + version = "3.47.0"; + + nativeBuildInputs = [ + wrapGAppsHook + qmake + ... + ]; + + dontWrapGApps = true; + + # Arguments to be passed to `makeWrapper`, only used by qt5’s mkDerivation + qtWrapperArgs = [ + "\${gappsWrapperArgs[@]}" + ]; +} +</programlisting> + </para> + </listitem> + </varlistentry> + <varlistentry xml:id="ssec-gnome-common-issues-unwrappable-package"> + <term> + I am packaging a project that cannot be wrapped, like a library or GNOME Shell extension. + </term> + <listitem> + <para> + You can rely on applications depending on the library set the necessary environment variables but that it often easy to miss. Instead we recommend to patch the paths in the source code whenever possible. Here are some examples: + <itemizedlist> + <listitem xml:id="ssec-gnome-common-issues-unwrappable-package-gnome-shell-ext"> + <para> + <link xlink:href="https://github.com/NixOS/nixpkgs/blob/7bb8f05f12ca3cff9da72b56caa2f7472d5732bc/pkgs/desktops/gnome-3/core/gnome-shell-extensions/default.nix#L21-L24">Replacing a <envar>GI_TYPELIB_PATH</envar> in GNOME Shell extension</link> – we are using <function>substituteAll</function> to include the path to a typelib into a patch. + </para> + </listitem> + <listitem xml:id="ssec-gnome-common-issues-unwrappable-package-gsettings"> + <para> + The following examples are hardcoding GSettings schema paths. To get the schema paths we use the functions + <itemizedlist> + <listitem> + <para> + <function>glib.getSchemaPath</function> Takes a nix package attribute as an argument. + </para> + </listitem> + <listitem> + <para> + <function>glib.makeSchemaPath</function> Takes a package output like <literal>$out</literal> and a derivation name. You should use this if the schemas you need to hardcode are in the same derivation. + </para> + </listitem> + </itemizedlist> + </para> + <para xml:id="ssec-gnome-common-issues-unwrappable-package-gsettings-vala"> + <link xlink:href="https://github.com/NixOS/nixpkgs/blob/7bb8f05f12ca3cff9da72b56caa2f7472d5732bc/pkgs/desktops/pantheon/apps/elementary-files/default.nix#L78-L86">Hard-coding GSettings schema path in Vala plug-in (dynamically loaded library)</link> – here, <function>substituteAll</function> cannot be used since the schema comes from the same package preventing us from pass its path to the function, probably due to a <link xlink:href="https://github.com/NixOS/nix/issues/1846">Nix bug</link>. + </para> + <para xml:id="ssec-gnome-common-issues-unwrappable-package-gsettings-c"> + <link xlink:href="https://github.com/NixOS/nixpkgs/blob/29c120c065d03b000224872251bed93932d42412/pkgs/development/libraries/glib-networking/default.nix#L31-L34">Hard-coding GSettings schema path in C library</link> – nothing special other than using <link xlink:href="https://github.com/NixOS/nixpkgs/pull/67957#issuecomment-527717467">Coccinelle patch</link> to generate the patch itself. + </para> + </listitem> + </itemizedlist> + </para> + </listitem> + </varlistentry> + <varlistentry xml:id="ssec-gnome-common-issues-weird-location"> + <term> + I need to wrap a binary outside <filename>bin</filename> and <filename>libexec</filename> directories. + </term> + <listitem> + <para> + You can manually trigger the wrapping with <function>wrapGApp</function> in <literal>preFixup</literal> phase. It takes a path to a program as a first argument; the remaining arguments are passed directly to <function xlink:href="#fun-wrapProgram">wrapProgram</function> function. + </para> + </listitem> + </varlistentry> + </variablelist> + </section> +</section> diff --git a/doc/languages-frameworks/go.xml b/doc/languages-frameworks/go.xml index b2b4962cb5f63..288a902986316 100644 --- a/doc/languages-frameworks/go.xml +++ b/doc/languages-frameworks/go.xml @@ -7,21 +7,16 @@ <title>Go modules</title> <para> - The function <varname> buildGoModule </varname> builds Go programs managed - with Go modules. It builds a - <link xlink:href="https://github.com/golang/go/wiki/Modules">Go - modules</link> through a two phase build: + The function <varname> buildGoModule </varname> builds Go programs managed with Go modules. It builds a <link xlink:href="https://github.com/golang/go/wiki/Modules">Go modules</link> through a two phase build: <itemizedlist> <listitem> <para> - An intermediate fetcher derivation. This derivation will be used to fetch - all of the dependencies of the Go module. + An intermediate fetcher derivation. This derivation will be used to fetch all of the dependencies of the Go module. </para> </listitem> <listitem> <para> - A final derivation will use the output of the intermediate derivation to - build the binaries and produce the final output. + A final derivation will use the output of the intermediate derivation to build the binaries and produce the final output. </para> </listitem> </itemizedlist> @@ -57,21 +52,16 @@ pet = buildGoModule rec { </example> <para> - <xref linkend='ex-buildGoModule'/> is an example expression using - buildGoModule, the following arguments are of special significance to the - function: + <xref linkend='ex-buildGoModule'/> is an example expression using buildGoModule, the following arguments are of special significance to the function: <calloutlist> <callout arearefs='ex-buildGoModule-1'> <para> - <varname>modSha256</varname> is the hash of the output of the - intermediate fetcher derivation. + <varname>modSha256</varname> is the hash of the output of the intermediate fetcher derivation. </para> </callout> <callout arearefs='ex-buildGoModule-2'> <para> - <varname>subPackages</varname> limits the builder from building child - packages that have not been listed. If <varname>subPackages</varname> is - not specified, all child packages will be built. + <varname>subPackages</varname> limits the builder from building child packages that have not been listed. If <varname>subPackages</varname> is not specified, all child packages will be built. </para> </callout> </calloutlist> @@ -82,8 +72,7 @@ pet = buildGoModule rec { <title>Go legacy</title> <para> - The function <varname> buildGoPackage </varname> builds legacy Go programs, - not supporting Go modules. + The function <varname> buildGoPackage </varname> builds legacy Go programs, not supporting Go modules. </para> <example xml:id='ex-buildGoPackage'> @@ -111,49 +100,36 @@ deis = buildGoPackage rec { </example> <para> - <xref linkend='ex-buildGoPackage'/> is an example expression using - buildGoPackage, the following arguments are of special significance to the - function: + <xref linkend='ex-buildGoPackage'/> is an example expression using buildGoPackage, the following arguments are of special significance to the function: <calloutlist> <callout arearefs='ex-buildGoPackage-1'> <para> - <varname>goPackagePath</varname> specifies the package's canonical Go - import path. + <varname>goPackagePath</varname> specifies the package's canonical Go import path. </para> </callout> <callout arearefs='ex-buildGoPackage-2'> <para> - <varname>subPackages</varname> limits the builder from building child - packages that have not been listed. If <varname>subPackages</varname> is - not specified, all child packages will be built. + <varname>subPackages</varname> limits the builder from building child packages that have not been listed. If <varname>subPackages</varname> is not specified, all child packages will be built. </para> <para> - In this example only <literal>github.com/deis/deis/client</literal> will - be built. + In this example only <literal>github.com/deis/deis/client</literal> will be built. </para> </callout> <callout arearefs='ex-buildGoPackage-3'> <para> - <varname>goDeps</varname> is where the Go dependencies of a Go program - are listed as a list of package source identified by Go import path. It - could be imported as a separate <varname>deps.nix</varname> file for - readability. The dependency data structure is described below. + <varname>goDeps</varname> is where the Go dependencies of a Go program are listed as a list of package source identified by Go import path. It could be imported as a separate <varname>deps.nix</varname> file for readability. The dependency data structure is described below. </para> </callout> <callout arearefs='ex-buildGoPackage-4'> <para> - <varname>buildFlags</varname> is a list of flags passed to the go build - command. + <varname>buildFlags</varname> is a list of flags passed to the go build command. </para> </callout> </calloutlist> </para> <para> - The <varname>goDeps</varname> attribute can be imported from a separate - <varname>nix</varname> file that defines which Go libraries are needed and - should be included in <varname>GOPATH</varname> for - <varname>buildPhase</varname>. + The <varname>goDeps</varname> attribute can be imported from a separate <varname>nix</varname> file that defines which Go libraries are needed and should be included in <varname>GOPATH</varname> for <varname>buildPhase</varname>. </para> <example xml:id='ex-goDeps'> @@ -196,27 +172,18 @@ deis = buildGoPackage rec { </callout> <callout arearefs='ex-goDeps-3'> <para> - <varname>fetch type</varname> that needs to be used to get package - source. If <varname>git</varname> is used there should be - <varname>url</varname>, <varname>rev</varname> and - <varname>sha256</varname> defined next to it. + <varname>fetch type</varname> that needs to be used to get package source. If <varname>git</varname> is used there should be <varname>url</varname>, <varname>rev</varname> and <varname>sha256</varname> defined next to it. </para> </callout> </calloutlist> </para> <para> - To extract dependency information from a Go package in automated way use - <link xlink:href="https://github.com/kamilchm/go2nix">go2nix</link>. It can - produce complete derivation and <varname>goDeps</varname> file for Go - programs. + To extract dependency information from a Go package in automated way use <link xlink:href="https://github.com/kamilchm/go2nix">go2nix</link>. It can produce complete derivation and <varname>goDeps</varname> file for Go programs. </para> <para> - <varname>buildGoPackage</varname> produces - <xref linkend='chap-multiple-output' xrefstyle="select: title" /> where - <varname>bin</varname> includes program binaries. You can test build a Go - binary as follows: + <varname>buildGoPackage</varname> produces <xref linkend='chap-multiple-output' xrefstyle="select: title" /> where <varname>bin</varname> includes program binaries. You can test build a Go binary as follows: <screen> <prompt>$ </prompt>nix-build -A deis.bin </screen> @@ -224,13 +191,11 @@ deis = buildGoPackage rec { <screen> <prompt>$ </prompt>nix-build -A deis.all </screen> - <varname>bin</varname> output will be installed by default with - <varname>nix-env -i</varname> or <varname>systemPackages</varname>. + <varname>bin</varname> output will be installed by default with <varname>nix-env -i</varname> or <varname>systemPackages</varname>. </para> <para> - You may use Go packages installed into the active Nix profiles by adding the - following to your ~/.bashrc: + You may use Go packages installed into the active Nix profiles by adding the following to your ~/.bashrc: <screen> for p in $NIX_PROFILES; do GOPATH="$p/share/go:$GOPATH" diff --git a/doc/languages-frameworks/haskell.section.md b/doc/languages-frameworks/haskell.section.md index 48d22831cd9b0..7cbac95f7d432 100644 --- a/doc/languages-frameworks/haskell.section.md +++ b/doc/languages-frameworks/haskell.section.md @@ -3,7 +3,7 @@ title: User's Guide for Haskell in Nixpkgs author: Peter Simons date: 2015-06-01 --- -# User's Guide to the Haskell Infrastructure +# Haskell ## How to install Haskell packages @@ -398,7 +398,9 @@ nix: For more on how to write a `shell.nix` file see the below section. You'll need to express a derivation. Note that Nixpkgs ships with a convenience wrapper function around `mkDerivation` called `haskell.lib.buildStackProject` to help you -create this derivation in exactly the way Stack expects. All of the same inputs +create this derivation in exactly the way Stack expects. However for this to work +you need to disable the sandbox, which you can do by using `--option sandbox relaxed` +or `--option sandbox false` to the Nix command. All of the same inputs as `mkDerivation` can be provided. For example, to build a Stack project that including packages that link against a version of the R library compiled with special options turned on: diff --git a/doc/languages-frameworks/idris.section.md b/doc/languages-frameworks/idris.section.md index e88015f08e3f8..8d7962d7fb9b2 100644 --- a/doc/languages-frameworks/idris.section.md +++ b/doc/languages-frameworks/idris.section.md @@ -1,4 +1,4 @@ -# Idris packages +# Idris ## Installing Idris diff --git a/doc/languages-frameworks/index.xml b/doc/languages-frameworks/index.xml index cd4e95cfae69a..9364c764bbf9f 100644 --- a/doc/languages-frameworks/index.xml +++ b/doc/languages-frameworks/index.xml @@ -1,19 +1,17 @@ <chapter xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude" xml:id="chap-language-support"> - <title>Support for specific programming languages and frameworks</title> + <title>Languages and frameworks</title> <para> - The <link linkend="chap-stdenv">standard build environment</link> 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 <literal>stdenv</literal>. 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. + The <link linkend="chap-stdenv">standard build environment</link> 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 <literal>stdenv</literal>. 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. </para> <xi:include href="android.section.xml" /> <xi:include href="beam.xml" /> <xi:include href="bower.xml" /> <xi:include href="coq.xml" /> + <xi:include href="crystal.section.xml" /> + <xi:include href="emscripten.section.xml" /> + <xi:include href="gnome.xml" /> <xi:include href="go.xml" /> <xi:include href="haskell.section.xml" /> <xi:include href="idris.section.xml" /> @@ -31,6 +29,4 @@ <xi:include href="texlive.xml" /> <xi:include href="titanium.section.xml" /> <xi:include href="vim.section.xml" /> - <xi:include href="emscripten.section.xml" /> - <xi:include href="crystal.section.xml" /> </chapter> diff --git a/doc/languages-frameworks/ios.section.md b/doc/languages-frameworks/ios.section.md index 6684b809ffe61..5a81795c004a5 100644 --- a/doc/languages-frameworks/ios.section.md +++ b/doc/languages-frameworks/ios.section.md @@ -1,7 +1,7 @@ --- title: iOS author: Sander van der Burg -date: 2018-11-18 +date: 2019-11-10 --- # iOS @@ -217,3 +217,13 @@ xcode.simulateApp { By providing the result of an `xcode.buildApp {}` function and configuring the app bundle id, the app gets deployed automatically and started. + +Troubleshooting +--------------- +In some rare cases, it may happen that after a failure, changes are not picked +up. Most likely, this is caused by a derived data cache that Xcode maintains. +To wipe it you can run: + +```bash +$ rm -rf ~/Library/Developer/Xcode/DerivedData +``` diff --git a/doc/languages-frameworks/java.xml b/doc/languages-frameworks/java.xml index 68a1a097984de..bf0fc48839223 100644 --- a/doc/languages-frameworks/java.xml +++ b/doc/languages-frameworks/java.xml @@ -15,37 +15,24 @@ stdenv.mkDerivation { buildPhase = "ant"; } </programlisting> - Note that <varname>jdk</varname> is an alias for the OpenJDK (self-built - where available, or pre-built via Zulu). Platforms with OpenJDK not (yet) in - Nixpkgs (<literal>Aarch32</literal>, <literal>Aarch64</literal>) point to the - (unfree) <literal>oraclejdk</literal>. + Note that <varname>jdk</varname> is an alias for the OpenJDK (self-built where available, or pre-built via Zulu). Platforms with OpenJDK not (yet) in Nixpkgs (<literal>Aarch32</literal>, <literal>Aarch64</literal>) point to the (unfree) <literal>oraclejdk</literal>. </para> <para> - JAR files that are intended to be used by other packages should be installed - in <filename>$out/share/java</filename>. JDKs have a stdenv setup hook that - add any JARs in the <filename>share/java</filename> directories of the build - inputs to the <envar>CLASSPATH</envar> environment variable. For instance, if - the package <literal>libfoo</literal> installs a JAR named - <filename>foo.jar</filename> in its <filename>share/java</filename> - directory, and another package declares the attribute + JAR files that are intended to be used by other packages should be installed in <filename>$out/share/java</filename>. JDKs have a stdenv setup hook that add any JARs in the <filename>share/java</filename> directories of the build inputs to the <envar>CLASSPATH</envar> environment variable. For instance, if the package <literal>libfoo</literal> installs a JAR named <filename>foo.jar</filename> in its <filename>share/java</filename> directory, and another package declares the attribute <programlisting> buildInputs = [ libfoo ]; nativeBuildInputs = [ jdk ]; </programlisting> - then <envar>CLASSPATH</envar> will be set to - <filename>/nix/store/...-libfoo/share/java/foo.jar</filename>. + then <envar>CLASSPATH</envar> will be set to <filename>/nix/store/...-libfoo/share/java/foo.jar</filename>. </para> <para> - Private JARs should be installed in a location like - <filename>$out/share/<replaceable>package-name</replaceable></filename>. + Private JARs should be installed in a location like <filename>$out/share/<replaceable>package-name</replaceable></filename>. </para> <para> - If your Java package provides a program, you need to generate a wrapper - script to run it using the OpenJRE. You can use - <literal>makeWrapper</literal> for this: + If your Java package provides a program, you need to generate a wrapper script to run it using the OpenJRE. You can use <literal>makeWrapper</literal> for this: <programlisting> nativeBuildInputs = [ makeWrapper ]; @@ -56,30 +43,21 @@ installPhase = --add-flags "-cp $out/share/java/foo.jar org.foo.Main" ''; </programlisting> - Note the use of <literal>jre</literal>, which is the part of the OpenJDK - package that contains the Java Runtime Environment. By using - <literal>${jre}/bin/java</literal> instead of - <literal>${jdk}/bin/java</literal>, you prevent your package from depending - on the JDK at runtime. + Note the use of <literal>jre</literal>, which is the part of the OpenJDK package that contains the Java Runtime Environment. By using <literal>${jre}/bin/java</literal> instead of <literal>${jdk}/bin/java</literal>, you prevent your package from depending on the JDK at runtime. </para> <para> - Note all JDKs passthru <literal>home</literal>, so if your application - requires environment variables like <envar>JAVA_HOME</envar> being set, that - can be done in a generic fashion with the <literal>--set</literal> argument - of <literal>makeWrapper</literal>: + Note all JDKs passthru <literal>home</literal>, so if your application requires environment variables like <envar>JAVA_HOME</envar> being set, that can be done in a generic fashion with the <literal>--set</literal> argument of <literal>makeWrapper</literal>: <programlisting> --set JAVA_HOME ${jdk.home} </programlisting> </para> <para> - It is possible to use a different Java compiler than <command>javac</command> - from the OpenJDK. For instance, to use the GNU Java Compiler: + It is possible to use a different Java compiler than <command>javac</command> from the OpenJDK. For instance, to use the GNU Java Compiler: <programlisting> nativeBuildInputs = [ gcj ant ]; </programlisting> - Here, Ant will automatically use <command>gij</command> (the GNU Java - Runtime) instead of the OpenJRE. + Here, Ant will automatically use <command>gij</command> (the GNU Java Runtime) instead of the OpenJRE. </para> </section> diff --git a/doc/languages-frameworks/lua.xml b/doc/languages-frameworks/lua.xml index 5144bb24ff6e7..bcca6b7375391 100644 --- a/doc/languages-frameworks/lua.xml +++ b/doc/languages-frameworks/lua.xml @@ -4,18 +4,11 @@ <title>Lua</title> <para> - Lua packages are built by the <varname>buildLuaPackage</varname> function. - This function is implemented in - <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/lua-modules/generic/default.nix"> - <filename>pkgs/development/lua-modules/generic/default.nix</filename></link> - and works similarly to <varname>buildPerlPackage</varname>. (See - <xref linkend="sec-language-perl"/> for details.) + Lua packages are built by the <varname>buildLuaPackage</varname> function. This function is implemented in <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/lua-modules/generic/default.nix"> <filename>pkgs/development/lua-modules/generic/default.nix</filename></link> and works similarly to <varname>buildPerlPackage</varname>. (See <xref linkend="sec-language-perl"/> for details.) </para> <para> - Lua packages are defined in - <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/top-level/lua-packages.nix"><filename>pkgs/top-level/lua-packages.nix</filename></link>. - Most of them are simple. For example: + Lua packages are defined in <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/top-level/lua-packages.nix"><filename>pkgs/top-level/lua-packages.nix</filename></link>. Most of them are simple. For example: <programlisting> fileSystem = buildLuaPackage { name = "filesystem-1.6.2"; @@ -33,16 +26,11 @@ fileSystem = buildLuaPackage { </para> <para> - Though, more complicated package should be placed in a seperate file in - <link + Though, more complicated package should be placed in a seperate file in <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/lua-modules"><filename>pkgs/development/lua-modules</filename></link>. </para> <para> - Lua packages accept additional parameter <varname>disabled</varname>, which - defines the condition of disabling package from luaPackages. For example, if - package has <varname>disabled</varname> assigned to <literal>lua.luaversion - != "5.1"</literal>, it will not be included in any luaPackages except - lua51Packages, making it only be built for lua 5.1. + Lua packages accept additional parameter <varname>disabled</varname>, which defines the condition of disabling package from luaPackages. For example, if package has <varname>disabled</varname> assigned to <literal>lua.luaversion != "5.1"</literal>, it will not be included in any luaPackages except lua51Packages, making it only be built for lua 5.1. </para> </section> diff --git a/doc/languages-frameworks/node.section.md b/doc/languages-frameworks/node.section.md index c6dce04c7b8b0..4dc95fc1dd98f 100644 --- a/doc/languages-frameworks/node.section.md +++ b/doc/languages-frameworks/node.section.md @@ -1,5 +1,5 @@ -Node.js packages -================ +Node.js +======= The `pkgs/development/node-packages` folder contains a generated collection of [NPM packages](https://npmjs.com/) that can be installed with the Nix package manager. diff --git a/doc/languages-frameworks/ocaml.xml b/doc/languages-frameworks/ocaml.xml index b7006ecba9981..a0ea209b493c0 100644 --- a/doc/languages-frameworks/ocaml.xml +++ b/doc/languages-frameworks/ocaml.xml @@ -4,35 +4,15 @@ <title>OCaml</title> <para> - OCaml libraries should be installed in - <literal>$(out)/lib/ocaml/${ocaml.version}/site-lib/</literal>. Such - directories are automatically added to the <literal>$OCAMLPATH</literal> - environment variable when building another package that depends on them or - when opening a <literal>nix-shell</literal>. + OCaml libraries should be installed in <literal>$(out)/lib/ocaml/${ocaml.version}/site-lib/</literal>. Such directories are automatically added to the <literal>$OCAMLPATH</literal> environment variable when building another package that depends on them or when opening a <literal>nix-shell</literal>. </para> <para> - Given that most of the OCaml ecosystem is now built with dune, nixpkgs - includes a convenience build support function called - <literal>buildDunePackage</literal> that will build an OCaml package using - dune, OCaml and findlib and any additional dependencies provided as - <literal>buildInputs</literal> or <literal>propagatedBuildInputs</literal>. + Given that most of the OCaml ecosystem is now built with dune, nixpkgs includes a convenience build support function called <literal>buildDunePackage</literal> that will build an OCaml package using dune, OCaml and findlib and any additional dependencies provided as <literal>buildInputs</literal> or <literal>propagatedBuildInputs</literal>. </para> <para> - Here is a simple package example. It defines an (optional) attribute - <literal>minimumOCamlVersion</literal> that will be used to throw a - descriptive evaluation error if building with an older OCaml is attempted. It - uses the <literal>fetchFromGitHub</literal> fetcher to get its source. It - sets the <literal>doCheck</literal> (optional) attribute to - <literal>true</literal> which means that tests will be run with <literal>dune - runtest -p angstrom</literal> after the build (<literal>dune build -p - angstrom</literal>) is complete. It uses <literal>alcotest</literal> as a - build input (because it is needed to run the tests) and - <literal>bigstringaf</literal> and <literal>result</literal> as propagated - build inputs (thus they will also be available to libraries depending on this - library). The library will be installed using the - <literal>angstrom.install</literal> file that dune generates. + Here is a simple package example. It defines an (optional) attribute <literal>minimumOCamlVersion</literal> that will be used to throw a descriptive evaluation error if building with an older OCaml is attempted. It uses the <literal>fetchFromGitHub</literal> fetcher to get its source. It sets the <literal>doCheck</literal> (optional) attribute to <literal>true</literal> which means that tests will be run with <literal>dune runtest -p angstrom</literal> after the build (<literal>dune build -p angstrom</literal>) is complete. It uses <literal>alcotest</literal> as a build input (because it is needed to run the tests) and <literal>bigstringaf</literal> and <literal>result</literal> as propagated build inputs (thus they will also be available to libraries depending on this library). The library will be installed using the <literal>angstrom.install</literal> file that dune generates. </para> <programlisting> @@ -65,11 +45,7 @@ buildDunePackage rec { </programlisting> <para> - Here is a second example, this time using a source archive generated with - <literal>dune-release</literal>. It is a good idea to use this archive when - it is available as it will usually contain substituted variables such as a - <literal>%%VERSION%%</literal> field. This library does not depend on any - other OCaml library and no tests are run after building it. + Here is a second example, this time using a source archive generated with <literal>dune-release</literal>. It is a good idea to use this archive when it is available as it will usually contain substituted variables such as a <literal>%%VERSION%%</literal> field. This library does not depend on any other OCaml library and no tests are run after building it. </para> <programlisting> diff --git a/doc/languages-frameworks/perl.xml b/doc/languages-frameworks/perl.xml index 065212a0e1807..d9b6b2721c675 100644 --- a/doc/languages-frameworks/perl.xml +++ b/doc/languages-frameworks/perl.xml @@ -4,24 +4,13 @@ <title>Perl</title> <para> - Nixpkgs provides a function <varname>buildPerlPackage</varname>, a generic - package builder function for any Perl package that has a standard - <varname>Makefile.PL</varname>. It’s implemented in - <link + Nixpkgs provides a function <varname>buildPerlPackage</varname>, a generic package builder function for any Perl package that has a standard <varname>Makefile.PL</varname>. It’s implemented in <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/perl-modules/generic"><filename>pkgs/development/perl-modules/generic</filename></link>. </para> <para> - Perl packages from CPAN are defined in - <link -xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/top-level/perl-packages.nix"><filename>pkgs/top-level/perl-packages.nix</filename></link>, - rather than <filename>pkgs/all-packages.nix</filename>. 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 - <filename>perl-packages.nix</filename>. However, more complicated packages - should be put in a separate file, typically in - <filename>pkgs/development/perl-modules</filename>. Here is an example of the - former: + Perl packages from CPAN are defined in <link +xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/top-level/perl-packages.nix"><filename>pkgs/top-level/perl-packages.nix</filename></link>, rather than <filename>pkgs/all-packages.nix</filename>. 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 <filename>perl-packages.nix</filename>. However, more complicated packages should be put in a separate file, typically in <filename>pkgs/development/perl-modules</filename>. Here is an example of the former: <programlisting> ClassC3 = buildPerlPackage rec { name = "Class-C3-0.21"; @@ -31,32 +20,22 @@ ClassC3 = buildPerlPackage rec { }; }; </programlisting> - Note the use of <literal>mirror://cpan/</literal>, and the - <literal>${name}</literal> 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 <filename>all-packages.nix</filename> - through the variable <varname>perlPackages</varname>. For instance, if you - have a package that needs <varname>ClassC3</varname>, you would typically - write + Note the use of <literal>mirror://cpan/</literal>, and the <literal>${name}</literal> 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 <filename>all-packages.nix</filename> through the variable <varname>perlPackages</varname>. For instance, if you have a package that needs <varname>ClassC3</varname>, you would typically write <programlisting> foo = import ../path/to/foo.nix { inherit stdenv fetchurl ...; inherit (perlPackages) ClassC3; }; </programlisting> - in <filename>all-packages.nix</filename>. You can test building a Perl - package as follows: + in <filename>all-packages.nix</filename>. You can test building a Perl package as follows: <screen> <prompt>$ </prompt>nix-build -A perlPackages.ClassC3 </screen> - <varname>buildPerlPackage</varname> adds <literal>perl-</literal> to the - start of the name attribute, so the package above is actually called - <literal>perl-Class-C3-0.21</literal>. So to install it, you can say: + <varname>buildPerlPackage</varname> adds <literal>perl-</literal> to the start of the name attribute, so the package above is actually called <literal>perl-Class-C3-0.21</literal>. So to install it, you can say: <screen> <prompt>$ </prompt>nix-env -i perl-Class-C3 </screen> - (Of course you can also install using the attribute name: <literal>nix-env -i - -A perlPackages.ClassC3</literal>.) + (Of course you can also install using the attribute name: <literal>nix-env -i -A perlPackages.ClassC3</literal>.) </para> <para> @@ -64,40 +43,24 @@ foo = import ../path/to/foo.nix { <orderedlist> <listitem> <para> - In the configure phase, it calls <literal>perl Makefile.PL</literal> to - generate a Makefile. You can set the variable - <varname>makeMakerFlags</varname> to pass flags to - <filename>Makefile.PL</filename> + In the configure phase, it calls <literal>perl Makefile.PL</literal> to generate a Makefile. You can set the variable <varname>makeMakerFlags</varname> to pass flags to <filename>Makefile.PL</filename> </para> </listitem> <listitem> <para> - It adds the contents of the <envar>PERL5LIB</envar> environment variable - to <literal>#! .../bin/perl</literal> line of Perl scripts as - <literal>-I<replaceable>dir</replaceable></literal> flags. This ensures - that a script can find its dependencies. (This can cause this shebang line - to become too long for Darwin to handle; see the note below.) + It adds the contents of the <envar>PERL5LIB</envar> environment variable to <literal>#! .../bin/perl</literal> line of Perl scripts as <literal>-I<replaceable>dir</replaceable></literal> flags. This ensures that a script can find its dependencies. (This can cause this shebang line to become too long for Darwin to handle; see the note below.) </para> </listitem> <listitem> <para> - In the fixup phase, it writes the propagated build inputs - (<varname>propagatedBuildInputs</varname>) to the file - <filename>$out/nix-support/propagated-user-env-packages</filename>. - <command>nix-env</command> 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. + In the fixup phase, it writes the propagated build inputs (<varname>propagatedBuildInputs</varname>) to the file <filename>$out/nix-support/propagated-user-env-packages</filename>. <command>nix-env</command> 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. </para> </listitem> </orderedlist> </para> <para> - <varname>buildPerlPackage</varname> is built on top of - <varname>stdenv</varname>, so everything can be customised in the usual way. - For instance, the <literal>BerkeleyDB</literal> module has a - <varname>preConfigure</varname> hook to generate a configuration file used by - <filename>Makefile.PL</filename>: + <varname>buildPerlPackage</varname> is built on top of <varname>stdenv</varname>, so everything can be customised in the usual way. For instance, the <literal>BerkeleyDB</literal> module has a <varname>preConfigure</varname> hook to generate a configuration file used by <filename>Makefile.PL</filename>: <programlisting> { buildPerlPackage, fetchurl, db }: @@ -118,12 +81,7 @@ buildPerlPackage rec { </para> <para> - Dependencies on other Perl packages can be specified in the - <varname>buildInputs</varname> and <varname>propagatedBuildInputs</varname> - attributes. If something is exclusively a build-time dependency, use - <varname>buildInputs</varname>; if it’s (also) a runtime dependency, use - <varname>propagatedBuildInputs</varname>. For instance, this builds a Perl - module that has runtime dependencies on a bunch of other modules: + Dependencies on other Perl packages can be specified in the <varname>buildInputs</varname> and <varname>propagatedBuildInputs</varname> attributes. If something is exclusively a build-time dependency, use <varname>buildInputs</varname>; if it’s (also) a runtime dependency, use <varname>propagatedBuildInputs</varname>. For instance, this builds a Perl module that has runtime dependencies on a bunch of other modules: <programlisting> ClassC3Componentised = buildPerlPackage rec { name = "Class-C3-Componentised-1.0004"; @@ -139,11 +97,7 @@ ClassC3Componentised = buildPerlPackage rec { </para> <para> - On Darwin, if a script has too many - <literal>-I<replaceable>dir</replaceable></literal> flags in its first line - (its “shebang line”), it will not run. This can be worked around by calling - the <literal>shortenPerlShebang</literal> function from the - <literal>postInstall</literal> phase: + On Darwin, if a script has too many <literal>-I<replaceable>dir</replaceable></literal> flags in its first line (its “shebang line”), it will not run. This can be worked around by calling the <literal>shortenPerlShebang</literal> function from the <literal>postInstall</literal> phase: <programlisting> { stdenv, buildPerlPackage, fetchurl, shortenPerlShebang }: @@ -162,20 +116,14 @@ ImageExifTool = buildPerlPackage { ''; }; </programlisting> - This will remove the <literal>-I</literal> flags from the shebang line, - rewrite them in the <literal>use lib</literal> form, and put them on the next - line instead. This function can be given any number of Perl scripts as - arguments; it will modify them in-place. + This will remove the <literal>-I</literal> flags from the shebang line, rewrite them in the <literal>use lib</literal> form, and put them on the next line instead. This function can be given any number of Perl scripts as arguments; it will modify them in-place. </para> <section xml:id="ssec-generation-from-CPAN"> <title>Generation from CPAN</title> <para> - Nix expressions for Perl packages can be generated (almost) automatically - from CPAN. This is done by the program - <command>nix-generate-from-cpan</command>, which can be installed as - follows: + Nix expressions for Perl packages can be generated (almost) automatically from CPAN. This is done by the program <command>nix-generate-from-cpan</command>, which can be installed as follows: </para> <screen> @@ -183,9 +131,7 @@ ImageExifTool = buildPerlPackage { </screen> <para> - 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: + 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: <screen> <prompt>$ </prompt>nix-generate-from-cpan XML::Simple XMLSimple = buildPerlPackage rec { @@ -201,9 +147,7 @@ ImageExifTool = buildPerlPackage { }; }; </screen> - The output can be pasted into - <filename>pkgs/top-level/perl-packages.nix</filename> or wherever else you - need it. + The output can be pasted into <filename>pkgs/top-level/perl-packages.nix</filename> or wherever else you need it. </para> </section> @@ -211,13 +155,7 @@ ImageExifTool = buildPerlPackage { <title>Cross-compiling modules</title> <para> - Nixpkgs has experimental support for cross-compiling Perl modules. In many - cases, it will just work out of the box, even for modules with native - extensions. Sometimes, however, the Makefile.PL for a module may - (indirectly) import a native module. In that case, you will need to make a - stub for that module that will satisfy the Makefile.PL and install it into - <filename>lib/perl5/site_perl/cross_perl/${perl.version}</filename>. See the - <varname>postInstall</varname> for <varname>DBI</varname> for an example. + Nixpkgs has experimental support for cross-compiling Perl modules. In many cases, it will just work out of the box, even for modules with native extensions. Sometimes, however, the Makefile.PL for a module may (indirectly) import a native module. In that case, you will need to make a stub for that module that will satisfy the Makefile.PL and install it into <filename>lib/perl5/site_perl/cross_perl/${perl.version}</filename>. See the <varname>postInstall</varname> for <varname>DBI</varname> for an example. </para> </section> </section> diff --git a/doc/languages-frameworks/python.section.md b/doc/languages-frameworks/python.section.md index 88dc42ebc6c23..1bedebd119029 100644 --- a/doc/languages-frameworks/python.section.md +++ b/doc/languages-frameworks/python.section.md @@ -144,6 +144,24 @@ What's happening here? 2. Then we create a Python 3.5 environment with the `withPackages` function. 3. The `withPackages` function expects us to provide a function as an argument that takes the set of all python packages and returns a list of packages to include in the environment. Here, we select the packages `numpy` and `toolz` from the package set. +To combine this with `mkShell` you can: + +```nix +with import <nixpkgs> {}; + +let + pythonEnv = python35.withPackages (ps: [ + ps.numpy + ps.toolz + ]); +in mkShell { + buildInputs = [ + pythonEnv + hello + ]; +} +``` + ##### Execute command with `--run` A convenient option with `nix-shell` is the `--run` option, with which you can execute a command in the `nix-shell`. We can @@ -593,7 +611,7 @@ as the interpreter unless overridden otherwise. All parameters from `stdenv.mkDerivation` function are still supported. The following are specific to `buildPythonPackage`: * `catchConflicts ? true`: If `true`, abort package build if a package name appears more than once in dependency tree. Default is `true`. -* `disabled` ? false: If `true`, package is not build for the particular Python interpreter version. +* `disabled` ? false: If `true`, package is not built for the particular Python interpreter version. * `dontWrapPythonPrograms ? false`: Skip wrapping of python programs. * `permitUserSite ? false`: Skip setting the `PYTHONNOUSERSITE` environment variable in wrapped programs. * `installFlags ? []`: A list of strings. Arguments to be passed to `pip install`. To pass options to `python setup.py install`, use `--install-option`. E.g., `installFlags=["--install-option='--cpp_implementation'"]`. @@ -850,9 +868,8 @@ Note: There is a boolean value `lib.inNixShell` set to `true` if nix-shell is in 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](https://github.com/proger/python2nix) by Vladimir Kirillov -- [pypi2nix](https://github.com/garbas/pypi2nix) by Rok Garbas -- [pypi2nix](https://github.com/offlinehacker/pypi2nix) by Jaka Hudoklin +- [pypi2nix](https://github.com/nix-community/pypi2nix): Generate Nix expressions for your Python project. Note that [sharing derivations from pypi2nix with nixpkgs is possible but not encouraged](https://github.com/nix-community/pypi2nix/issues/222#issuecomment-443497376). +- [python2nix](https://github.com/proger/python2nix) by Vladimir Kirillov. ### Deterministic builds diff --git a/doc/languages-frameworks/qt.xml b/doc/languages-frameworks/qt.xml index 3332ce8c06e42..8d97de504ad34 100644 --- a/doc/languages-frameworks/qt.xml +++ b/doc/languages-frameworks/qt.xml @@ -4,16 +4,12 @@ <title>Qt</title> <para> - This section describes the differences between Nix expressions for Qt - libraries and applications and Nix expressions for other C++ software. Some - knowledge of the latter is assumed. There are primarily two problems which - the Qt infrastructure is designed to address: ensuring consistent versioning - of all dependencies and finding dependencies at runtime. + This section describes the differences between Nix expressions for Qt libraries and applications and Nix expressions for other C++ software. Some knowledge of the latter is assumed. There are primarily two problems which the Qt infrastructure is designed to address: ensuring consistent versioning of all dependencies and finding dependencies at runtime. </para> <example xml:id='qt-default-nix'> - <title>Nix expression for a Qt package (<filename>default.nix</filename>)</title> - <programlisting> + <title>Nix expression for a Qt package (<filename>default.nix</filename>)</title> +<programlisting> { mkDerivation, lib, qtbase }: <co xml:id='qt-default-nix-co-1' /> mkDerivation { <co xml:id='qt-default-nix-co-2' /> @@ -26,53 +22,36 @@ mkDerivation { <co xml:id='qt-default-nix-co-2' /> </example> <calloutlist> - <callout arearefs='qt-default-nix-co-1'> - <para> - Import <literal>mkDerivation</literal> and Qt (such as - <literal>qtbase</literal> modules directly. <emphasis>Do not</emphasis> - import Qt package sets; the Qt versions of dependencies may not be - coherent, causing build and runtime failures. - </para> - </callout> - <callout arearefs='qt-default-nix-co-2'> - <para> - Use <literal>mkDerivation</literal> instead of - <literal>stdenv.mkDerivation</literal>. <literal>mkDerivation</literal> - is a wrapper around <literal>stdenv.mkDerivation</literal> which - applies some Qt-specific settings. - This deriver accepts the same arguments as - <literal>stdenv.mkDerivation</literal>; refer to - <xref linkend='chap-stdenv' /> for details. - </para> - <para> - To use another deriver instead of - <literal>stdenv.mkDerivation</literal>, use - <literal>mkDerivationWith</literal>: + <callout arearefs='qt-default-nix-co-1'> + <para> + Import <literal>mkDerivation</literal> and Qt (such as <literal>qtbase</literal> modules directly. <emphasis>Do not</emphasis> import Qt package sets; the Qt versions of dependencies may not be coherent, causing build and runtime failures. + </para> + </callout> + <callout arearefs='qt-default-nix-co-2'> + <para> + Use <literal>mkDerivation</literal> instead of <literal>stdenv.mkDerivation</literal>. <literal>mkDerivation</literal> is a wrapper around <literal>stdenv.mkDerivation</literal> which applies some Qt-specific settings. This deriver accepts the same arguments as <literal>stdenv.mkDerivation</literal>; refer to <xref linkend='chap-stdenv' /> for details. + </para> + <para> + To use another deriver instead of <literal>stdenv.mkDerivation</literal>, use <literal>mkDerivationWith</literal>: <programlisting> mkDerivationWith myDeriver { # ... } </programlisting> - If you cannot use <literal>mkDerivationWith</literal>, please refer to - <xref linkend='qt-runtime-dependencies' />. - </para> - </callout> - <callout arearefs='qt-default-nix-co-3'> - <para> - <literal>mkDerivation</literal> accepts the same arguments as - <literal>stdenv.mkDerivation</literal>, such as - <literal>buildInputs</literal>. - </para> - </callout> + If you cannot use <literal>mkDerivationWith</literal>, please refer to <xref linkend='qt-runtime-dependencies' />. + </para> + </callout> + <callout arearefs='qt-default-nix-co-3'> + <para> + <literal>mkDerivation</literal> accepts the same arguments as <literal>stdenv.mkDerivation</literal>, such as <literal>buildInputs</literal>. + </para> + </callout> </calloutlist> <formalpara xml:id='qt-runtime-dependencies'> - <title>Locating runtime dependencies</title> - <para> - Qt applications need to be wrapped to find runtime dependencies. If you - cannot use <literal>mkDerivation</literal> or - <literal>mkDerivationWith</literal> above, include - <literal>wrapQtAppsHook</literal> in <literal>nativeBuildInputs</literal>: + <title>Locating runtime dependencies</title> + <para> + Qt applications need to be wrapped to find runtime dependencies. If you cannot use <literal>mkDerivation</literal> or <literal>mkDerivationWith</literal> above, include <literal>wrapQtAppsHook</literal> in <literal>nativeBuildInputs</literal>: <programlisting> stdenv.mkDerivation { # ... @@ -80,13 +59,11 @@ stdenv.mkDerivation { nativeBuildInputs = [ wrapQtAppsHook ]; } </programlisting> - </para> + </para> </formalpara> <para> - Entries added to <literal>qtWrapperArgs</literal> are used to modify the - wrappers created by <literal>wrapQtAppsHook</literal>. The entries are - passed as arguments to <xref linkend='fun-wrapProgram' />. + Entries added to <literal>qtWrapperArgs</literal> are used to modify the wrappers created by <literal>wrapQtAppsHook</literal>. The entries are passed as arguments to <xref linkend='fun-wrapProgram' />. <programlisting> mkDerivation { # ... @@ -97,10 +74,7 @@ mkDerivation { </para> <para> - Set <literal>dontWrapQtApps</literal> to stop applications from being - wrapped automatically. It is required to wrap applications manually with - <literal>wrapQtApp</literal>, using the syntax of - <xref linkend='fun-wrapProgram' />: + Set <literal>dontWrapQtApps</literal> to stop applications from being wrapped automatically. It is required to wrap applications manually with <literal>wrapQtApp</literal>, using the syntax of <xref linkend='fun-wrapProgram' />: <programlisting> mkDerivation { # ... @@ -115,16 +89,12 @@ mkDerivation { <note> <para> - <literal>wrapQtAppsHook</literal> ignores files that are non-ELF executables. - This means that scripts won't be automatically wrapped so you'll need to manually - wrap them as previously mentioned. An example of when you'd always need to do this - is with Python applications that use PyQT. + <literal>wrapQtAppsHook</literal> ignores files that are non-ELF executables. This means that scripts won't be automatically wrapped so you'll need to manually wrap them as previously mentioned. An example of when you'd always need to do this is with Python applications that use PyQT. </para> </note> <para> - Libraries are built with every available version of Qt. Use the <literal>meta.broken</literal> - attribute to disable the package for unsupported Qt versions: + Libraries are built with every available version of Qt. Use the <literal>meta.broken</literal> attribute to disable the package for unsupported Qt versions: <programlisting> mkDerivation { # ... @@ -136,13 +106,11 @@ mkDerivation { </para> <formalpara> - <title>Adding a library to Nixpkgs</title> - <para> - Add a Qt library to <filename>all-packages.nix</filename> by adding it to the - collection inside <literal>mkLibsForQt5</literal>. This ensures that the - library is built with every available version of Qt as needed. - <example xml:id='qt-library-all-packages-nix'> - <title>Adding a Qt library to <filename>all-packages.nix</filename></title> + <title>Adding a library to Nixpkgs</title> + <para> + Add a Qt library to <filename>all-packages.nix</filename> by adding it to the collection inside <literal>mkLibsForQt5</literal>. This ensures that the library is built with every available version of Qt as needed. + <example xml:id='qt-library-all-packages-nix'> + <title>Adding a Qt library to <filename>all-packages.nix</filename></title> <programlisting> { # ... @@ -156,19 +124,16 @@ mkDerivation { # ... } </programlisting> - </example> - </para> + </example> + </para> </formalpara> <formalpara> - <title>Adding an application to Nixpkgs</title> - <para> - Add a Qt application to <filename>all-packages.nix</filename> using - <literal>libsForQt5.callPackage</literal> instead of the usual - <literal>callPackage</literal>. The former ensures that all dependencies - are built with the same version of Qt. - <example xml:id='qt-application-all-packages-nix'> - <title>Adding a Qt application to <filename>all-packages.nix</filename></title> + <title>Adding an application to Nixpkgs</title> + <para> + Add a Qt application to <filename>all-packages.nix</filename> using <literal>libsForQt5.callPackage</literal> instead of the usual <literal>callPackage</literal>. The former ensures that all dependencies are built with the same version of Qt. + <example xml:id='qt-application-all-packages-nix'> + <title>Adding a Qt application to <filename>all-packages.nix</filename></title> <programlisting> { # ... @@ -178,8 +143,7 @@ mkDerivation { # ... } </programlisting> - </example> - </para> + </example> + </para> </formalpara> - </section> diff --git a/doc/languages-frameworks/r.section.md b/doc/languages-frameworks/r.section.md index c8f02bd147806..d4e1617779ce4 100644 --- a/doc/languages-frameworks/r.section.md +++ b/doc/languages-frameworks/r.section.md @@ -1,5 +1,5 @@ -R packages -========== +R += ## Installation diff --git a/doc/languages-frameworks/ruby.xml b/doc/languages-frameworks/ruby.xml index df4e5acb22cb9..b28745fd6e275 100644 --- a/doc/languages-frameworks/ruby.xml +++ b/doc/languages-frameworks/ruby.xml @@ -4,11 +4,7 @@ <title>Ruby</title> <para> - There currently is support to bundle applications that are packaged as Ruby - gems. The utility "bundix" allows you to write a - <filename>Gemfile</filename>, let bundler create a - <filename>Gemfile.lock</filename>, and then convert this into a nix - expression that contains all Gem dependencies automatically. + There currently is support to bundle applications that are packaged as Ruby gems. The utility "bundix" allows you to write a <filename>Gemfile</filename>, let bundler create a <filename>Gemfile.lock</filename>, and then convert this into a nix expression that contains all Gem dependencies automatically. </para> <para> @@ -45,9 +41,7 @@ bundlerEnv rec { </screen> <para> - Please check in the <filename>Gemfile</filename>, - <filename>Gemfile.lock</filename> and the <filename>gemset.nix</filename> so - future updates can be run easily. + Please check in the <filename>Gemfile</filename>, <filename>Gemfile.lock</filename> and the <filename>gemset.nix</filename> so future updates can be run easily. </para> <para> @@ -62,10 +56,7 @@ $ nix-shell -p bundix --run 'bundix' </screen> <para> - For tools written in Ruby - i.e. where the desire is to install a package and - then execute e.g. <command>rake</command> at the command line, there is an - alternative builder called <literal>bundlerApp</literal>. Set up the - <filename>gemset.nix</filename> the same way, and then, for example: + For tools written in Ruby - i.e. where the desire is to install a package and then execute e.g. <command>rake</command> at the command line, there is an alternative builder called <literal>bundlerApp</literal>. Set up the <filename>gemset.nix</filename> the same way, and then, for example: </para> <screen> @@ -87,29 +78,11 @@ bundlerApp { </screen> <para> - The chief advantage of <literal>bundlerApp</literal> over - <literal>bundlerEnv</literal> is the executables introduced in the - environment are precisely those selected in the <literal>exes</literal> list, - as opposed to <literal>bundlerEnv</literal> which adds all the executables - made available by gems in the gemset, which can mean e.g. - <command>rspec</command> or <command>rake</command> in unpredictable versions - available from various packages. + The chief advantage of <literal>bundlerApp</literal> over <literal>bundlerEnv</literal> is the executables introduced in the environment are precisely those selected in the <literal>exes</literal> list, as opposed to <literal>bundlerEnv</literal> which adds all the executables made available by gems in the gemset, which can mean e.g. <command>rspec</command> or <command>rake</command> in unpredictable versions available from various packages. </para> <para> - Resulting derivations for both builders also have two helpful attributes, - <literal>env</literal> and <literal>wrappedRuby</literal>. The first one - allows one to quickly drop into <command>nix-shell</command> with the - specified environment present. E.g. <command>nix-shell -A sensu.env</command> - would give you an environment with Ruby preset so it has all the libraries - necessary for <literal>sensu</literal> in its paths. The second one can be - used to make derivations from custom Ruby scripts which have - <filename>Gemfile</filename>s with their dependencies specified. It is a - derivation with <command>ruby</command> wrapped so it can find all the needed - dependencies. For example, to make a derivation <literal>my-script</literal> - for a <filename>my-script.rb</filename> (which should be placed in - <filename>bin</filename>) you should run <command>bundix</command> as - specified above and then use <literal>bundlerEnv</literal> like this: + Resulting derivations for both builders also have two helpful attributes, <literal>env</literal> and <literal>wrappedRuby</literal>. The first one allows one to quickly drop into <command>nix-shell</command> with the specified environment present. E.g. <command>nix-shell -A sensu.env</command> would give you an environment with Ruby preset so it has all the libraries necessary for <literal>sensu</literal> in its paths. The second one can be used to make derivations from custom Ruby scripts which have <filename>Gemfile</filename>s with their dependencies specified. It is a derivation with <command>ruby</command> wrapped so it can find all the needed dependencies. For example, to make a derivation <literal>my-script</literal> for a <filename>my-script.rb</filename> (which should be placed in <filename>bin</filename>) you should run <command>bundix</command> as specified above and then use <literal>bundlerEnv</literal> like this: </para> <programlisting> diff --git a/doc/languages-frameworks/rust.section.md b/doc/languages-frameworks/rust.section.md index 2d9338f2e89bf..709a0d504cf73 100644 --- a/doc/languages-frameworks/rust.section.md +++ b/doc/languages-frameworks/rust.section.md @@ -4,7 +4,7 @@ author: Matthias Beyer date: 2017-03-05 --- -# User's Guide to the Rust Infrastructure +# Rust To install the rust compiler and cargo put @@ -43,6 +43,7 @@ rustPlatform.buildRustPackage rec { }; cargoSha256 = "0q68qyl2h6i0qsz82z840myxlnjay8p1w5z7hfyr8fqp7wgwa9cx"; + verifyCargoDeps = true; meta = with stdenv.lib; { description = "A fast line-oriented regex search tool, similar to ag and ack"; @@ -64,6 +65,20 @@ When the `Cargo.lock`, provided by upstream, is not in sync with the added in `cargoPatches` will also be prepended to the patches in `patches` at build-time. +When `verifyCargoDeps` is set to `true`, the build will also verify that the +`cargoSha256` is not out of date by comparing the `Cargo.lock` file in both the `cargoDeps` and `src`. Note that this option changes the value of `cargoSha256` since it also copies the `Cargo.lock` in it. To avoid breaking backward-compatibility this option is not enabled by default but hopefully will be in the future. + +### Building a crate for a different target + +To build your crate with a different cargo `--target` simply specify the `target` attribute: + +```nix +pkgs.rustPlatform.buildRustPackage { + (...) + target = "x86_64-fortanix-unknown-sgx"; +} +``` + ## Compiling Rust crates using Nix instead of Cargo ### Simple operation @@ -188,7 +203,7 @@ argument and returns a set that contains all attribute that should be overwritten. For more complicated cases, such as when parts of the crate's -derivation depend on the the crate's version, the `attrs` argument of +derivation depend on the crate's version, the `attrs` argument of the override above can be read, as in the following example, which patches the derivation: diff --git a/doc/languages-frameworks/texlive.xml b/doc/languages-frameworks/texlive.xml index 97f274933bef2..7876cc213b667 100644 --- a/doc/languages-frameworks/texlive.xml +++ b/doc/languages-frameworks/texlive.xml @@ -4,8 +4,7 @@ <title>TeX Live</title> <para> - Since release 15.09 there is a new TeX Live packaging that lives entirely - under attribute <varname>texlive</varname>. + Since release 15.09 there is a new TeX Live packaging that lives entirely under attribute <varname>texlive</varname>. </para> <section xml:id="sec-language-texlive-users-guide"> @@ -14,28 +13,23 @@ <itemizedlist> <listitem> <para> - For basic usage just pull <varname>texlive.combined.scheme-basic</varname> - for an environment with basic LaTeX support. + For basic usage just pull <varname>texlive.combined.scheme-basic</varname> for an environment with basic LaTeX support. </para> </listitem> <listitem> <para> - It typically won't work to use separately installed packages together. - Instead, you can build a custom set of packages like this: + It typically won't work to use separately installed packages together. Instead, you can build a custom set of packages like this: <programlisting> texlive.combine { inherit (texlive) scheme-small collection-langkorean algorithms cm-super; } </programlisting> - There are all the schemes, collections and a few thousand packages, as - defined upstream (perhaps with tiny differences). + There are all the schemes, collections and a few thousand packages, as defined upstream (perhaps with tiny differences). </para> </listitem> <listitem> <para> - By default you only get executables and files needed during runtime, and a - little documentation for the core packages. To change that, you need to - add <varname>pkgFilter</varname> function to <varname>combine</varname>. + By default you only get executables and files needed during runtime, and a little documentation for the core packages. To change that, you need to add <varname>pkgFilter</varname> function to <varname>combine</varname>. <programlisting> texlive.combine { # inherit (texlive) whatever-you-want; @@ -59,10 +53,7 @@ nix-repl> texlive.collection-<TAB> </listitem> <listitem> <para> - Note that the wrapper assumes that the result has a chance to be useful. - For example, the core executables should be present, as well as some core - data files. The supported way of ensuring this is by including some - scheme, for example <varname>scheme-basic</varname>, into the combination. + Note that the wrapper assumes that the result has a chance to be useful. For example, the core executables should be present, as well as some core data files. The supported way of ensuring this is by including some scheme, for example <varname>scheme-basic</varname>, into the combination. </para> </listitem> </itemizedlist> @@ -84,14 +75,12 @@ nix-repl> texlive.collection-<TAB> </listitem> <listitem> <para> - feature/bug: when a package is rejected by <varname>pkgFilter</varname>, - its dependencies are still propagated; + feature/bug: when a package is rejected by <varname>pkgFilter</varname>, its dependencies are still propagated; </para> </listitem> <listitem> <para> - in case of any bugs or feature requests, file a github issue or better a - pull request and /cc @vcunat. + in case of any bugs or feature requests, file a github issue or better a pull request and /cc @vcunat. </para> </listitem> </itemizedlist> diff --git a/doc/languages-frameworks/vim.section.md b/doc/languages-frameworks/vim.section.md index 537e7b93e5230..05a23d26cf2f7 100644 --- a/doc/languages-frameworks/vim.section.md +++ b/doc/languages-frameworks/vim.section.md @@ -3,7 +3,7 @@ title: User's Guide for Vim in Nixpkgs author: Marc Weber date: 2016-06-25 --- -# User's Guide to Vim Plugins/Addons/Bundles/Scripts in Nixpkgs +# Vim Both Neovim and Vim can be configured to include your favorite plugins and additional libraries. |