From cd518845e2ca008f5a00b38ffa0f1c99f154f6cc Mon Sep 17 00:00:00 2001 From: worldofpeace Date: Mon, 5 Aug 2019 21:53:07 -0400 Subject: [PATCH] doc/stdenv: document meson variables --- doc/cross-compilation.xml | 40 +++--- doc/functions/dockertools.xml | 34 +++-- doc/functions/ocitools.xml | 12 +- doc/languages-frameworks/gnome.xml | 185 +++++++++++++++++++++++----- doc/languages-frameworks/perl.xml | 12 +- doc/languages-frameworks/qt.xml | 154 ++++++++++++----------- doc/meta.xml | 10 +- doc/package-notes.xml | 66 +++++----- doc/package-specific-user-notes.xml | 88 ++++++------- doc/quick-start.xml | 8 +- doc/stdenv.xml | 126 ++++++++++++++----- 11 files changed, 456 insertions(+), 279 deletions(-) diff --git a/doc/cross-compilation.xml b/doc/cross-compilation.xml index b7844da195d7..d212706e1713 100644 --- a/doc/cross-compilation.xml +++ b/doc/cross-compilation.xml @@ -485,10 +485,10 @@ nix-build <nixpkgs> --arg crossSystem '{ config = "<arch>-<os> are specified as lists of derivations given to mkDerivation, as - documented in . In short, - each list of dependencies for "host → target" of "foo → bar" is called - depsFooBar, with exceptions for backwards - compatibility that depsBuildHost is instead called + documented in . In short, each + list of dependencies for "host → target" of "foo → bar" is called + depsFooBar, with exceptions for backwards compatibility + that depsBuildHost is instead called nativeBuildInputs and depsHostTarget is instead called buildInputs. Nixpkgs is now structured so that each depsFooBar is automatically taken from @@ -507,9 +507,8 @@ nix-build <nixpkgs> --arg crossSystem '{ config = "<arch>-<os> buildPackages, pkgs, and targetPackages. Those are now redefined as aliases to pkgsBuildHost, pkgsHostTarget, and - pkgsTargetTarget. It is acceptable, even - recommended, to use them for libraries to show that the host platform is - irrelevant. + pkgsTargetTarget. It is acceptable, even recommended, to + use them for libraries to show that the host platform is irrelevant. @@ -581,14 +580,15 @@ nix-build <nixpkgs> --arg crossSystem '{ config = "<arch>-<os> pkgsHostTarget refers to the current one, and pkgsTargetTarget refers to the next one. When there is no previous or next stage, they instead refer to the current stage. Note - how all the invariants regarding the mapping between dependency and depending - packages' build host and target platforms are preserved. + how all the invariants regarding the mapping between dependency and + depending packages' build host and target platforms are preserved. pkgsBuildTarget and pkgsHostHost are more complex in that the stage fitting the requirements isn't always a fixed chain of "prevs" and "nexts" away (modulo the "saturating" - self-references at the ends). We just special case each instead. All the primary - edges are implemented is in pkgs/stdenv/booter.nix, - and secondarily aliases in pkgs/top-level/stage.nix. + self-references at the ends). We just special case each instead. All the + primary edges are implemented is in + pkgs/stdenv/booter.nix, and secondarily aliases in + pkgs/top-level/stage.nix. @@ -645,19 +645,19 @@ nix-build <nixpkgs> --arg crossSystem '{ config = "<arch>-<os> "infinite recursions" / cycles. When only package sets that don't mention target are used, the package set forms a directed acyclic graph. This means that all cycles that exist are confined to one stage. This means - they are a lot smaller, and easier to follow in the code or a backtrace. It - also means they are present in native and cross builds alike, and so more - likely to be caught by CI and other users. + they are a lot smaller, and easier to follow in the code or a backtrace. + It also means they are present in native and cross builds alike, and so + more likely to be caught by CI and other users. Thirdly, it is because everything target-mentioning only exists to accommodate compilers with lousy build systems that insist on the compiler itself and standard library being built together. Of course that is bad - because bigger derivations means longer rebuilds. It is also problematic because - it tends to make the standard libraries less like other libraries than - they could be, complicating code and build systems alike. Because of the - other problems, and because of these innate disadvantages, compilers ought - to be packaged another way where possible. + because bigger derivations means longer rebuilds. It is also problematic + because it tends to make the standard libraries less like other libraries + than they could be, complicating code and build systems alike. Because of + the other problems, and because of these innate disadvantages, compilers + ought to be packaged another way where possible. diff --git a/doc/functions/dockertools.xml b/doc/functions/dockertools.xml index a284182bb047..6b293a2e7787 100644 --- a/doc/functions/dockertools.xml +++ b/doc/functions/dockertools.xml @@ -325,10 +325,9 @@ hello latest de2bf4786de6 About a minute ago 25.2MB - Shell commands to run while building the final layer, without access - to most of the layer contents. Changes to this layer are "on top" - of all the other layers, so can create additional directories - and files. + Shell commands to run while building the final layer, without access to + most of the layer contents. Changes to this layer are "on top" of all the + other layers, so can create additional directories and files. @@ -493,28 +492,23 @@ pullImage { - nix-prefetch-docker command can be used to get required - image parameters: - + nix-prefetch-docker command can be used to get required + image parameters: $ nix run nixpkgs.nix-prefetch-docker -c nix-prefetch-docker --image-name mysql --image-tag 5 - - Since a given imageName may transparently refer to a - manifest list of images which support multiple architectures and/or - operating systems, you can supply the and - arguments to specify exactly which image you want. - By default it will match the OS and architecture of the host the command is - run on. - + Since a given imageName may transparently refer to a + manifest list of images which support multiple architectures and/or + operating systems, you can supply the and + arguments to specify exactly which image you want. + By default it will match the OS and architecture of the host the command is + run on. $ nix-prefetch-docker --image-name mysql --image-tag 5 --arch x86_64 --os linux - - Desired image name and tag can be set using - and - arguments: - + Desired image name and tag can be set using + and + arguments: $ nix-prefetch-docker --image-name mysql --image-tag 5 --final-image-name eu.gcr.io/my-project/mysql --final-image-tag prod diff --git a/doc/functions/ocitools.xml b/doc/functions/ocitools.xml index 163bee2382e6..56de0c22ec61 100644 --- a/doc/functions/ocitools.xml +++ b/doc/functions/ocitools.xml @@ -51,10 +51,10 @@ buildContainer { - args specifies a set of arguments to run inside the container. - This is the only required argument for buildContainer. - All referenced packages inside the derivation will be made available - inside the container + args specifies a set of arguments to run inside the + container. This is the only required argument for + buildContainer. All referenced packages inside the + derivation will be made available inside the container @@ -66,8 +66,8 @@ buildContainer { - readonly makes the container's rootfs read-only if it is set to true. - The default value is false false. + readonly makes the container's rootfs read-only if it + is set to true. The default value is false false. diff --git a/doc/languages-frameworks/gnome.xml b/doc/languages-frameworks/gnome.xml index 9e0f21a6c74f..42b4ae04322f 100644 --- a/doc/languages-frameworks/gnome.xml +++ b/doc/languages-frameworks/gnome.xml @@ -5,26 +5,53 @@ Packaging GNOME applications - 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. Wrapping 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. + 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. + Wrapping 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.
Settings - GSettings 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 glib-2.0/schemas/gschemas.compiled files inside the directories of XDG_DATA_DIRS. + GSettings + 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 + glib-2.0/schemas/gschemas.compiled files inside the + directories of XDG_DATA_DIRS. - On Linux, GSettings API is implemented using dconf backend. You will need to add dconf GIO module to GIO_EXTRA_MODULES variable, otherwise the memory backend will be used and the saved settings will not be persistent. + On Linux, GSettings API is implemented using + dconf + backend. You will need to add dconf GIO module to + GIO_EXTRA_MODULES variable, otherwise the + memory backend will be used and the saved settings will + not be persistent. - Last you will need the dconf database D-Bus service itself. You can enable it using . + Last you will need the dconf database D-Bus service itself. You can enable + it using . - Some applications will also require gsettings-desktop-schemas for things like reading proxy configuration or user interface customization. This dependency is often not mentioned by upstream, you should grep for org.gnome.desktop and org.gnome.system to see if the schemas are needed. + Some applications will also require + gsettings-desktop-schemas for things like reading proxy + configuration or user interface customization. This dependency is often not + mentioned by upstream, you should grep for + org.gnome.desktop and + org.gnome.system to see if the schemas are needed.
@@ -32,7 +59,16 @@ Icons - When an application uses icons, an icon theme should be available in XDG_DATA_DIRS. The package for the default, icon-less hicolor-icon-theme contains a setup hook that will pick up icon themes from buildInputs 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. + When an application uses icons, an icon theme should be available in + XDG_DATA_DIRS. The package for the default, icon-less + hicolor-icon-theme + contains a setup + hook that will pick up icon themes from + buildInputs 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. @@ -40,7 +76,12 @@ GTK Themes - Previously, a GTK theme needed to be in XDG_DATA_DIRS. This is no longer necessary for most programs since GTK incorporated Adwaita theme. Some programs (for example, those designed for elementary HIG) might require a special theme like pantheon.elementary-gtk-theme. + Previously, a GTK theme needed to be in XDG_DATA_DIRS. This + is no longer necessary for most programs since GTK incorporated Adwaita + theme. Some programs (for example, those designed for + elementary + HIG) might require a special theme like + pantheon.elementary-gtk-theme. @@ -48,7 +89,10 @@ GObject introspection typelibs - GObject introspection allows applications to use C libraries in other languages easily. It does this through typelib files searched in GI_TYPELIB_PATH. + GObject + introspection allows applications to use C libraries in other + languages easily. It does this through typelib files + searched in GI_TYPELIB_PATH. @@ -56,7 +100,11 @@ Various plug-ins - If your application uses GStreamer or Grilo, you should set GST_PLUGIN_SYSTEM_PATH_1_0 and GRL_PLUGIN_PATH, respectively. + If your application uses + GStreamer or + Grilo, you + should set GST_PLUGIN_SYSTEM_PATH_1_0 and + GRL_PLUGIN_PATH, respectively. @@ -65,7 +113,8 @@ Onto <package>wrapGAppsHook</package> - Given the requirements above, the package expression would become messy quickly: + Given the requirements above, the package expression would become messy + quickly: preFixup = '' for f in $(find $out/bin/ $out/libexec/ -type f -executable); do @@ -79,48 +128,76 @@ preFixup = '' done ''; - Fortunately, there is wrapGAppsHook, that does the wrapping for us. In particular, it works in conjunction with other setup hooks that will populate the variable: + Fortunately, there is wrapGAppsHook, that does the + wrapping for us. In particular, it works in conjunction with other setup + hooks that will populate the variable: - wrapGAppsHook itself will add the package’s share directory to XDG_DATA_DIRS. + wrapGAppsHook itself will add the package’s + share directory to XDG_DATA_DIRS. - glib setup hook will populate GSETTINGS_SCHEMAS_PATH and then wrapGAppsHook will prepend it to XDG_DATA_DIRS. + glib setup hook will populate + GSETTINGS_SCHEMAS_PATH and then + wrapGAppsHook will prepend it to + XDG_DATA_DIRS. - gnome3.dconf.lib is a dependency of wrapGAppsHook, which then also adds it to the GIO_EXTRA_MODULES variable. + gnome3.dconf.lib is a dependency of + wrapGAppsHook, which then also adds it to the + GIO_EXTRA_MODULES variable. - hicolor-icon-theme’s setup hook will add icon themes to XDG_ICON_DIRS which is prepended to XDG_DATA_DIRS by wrapGAppsHook. + hicolor-icon-theme’s setup hook will add icon themes + to XDG_ICON_DIRS which is prepended to + XDG_DATA_DIRS by wrapGAppsHook. - gobject-introspection setup hook populates GI_TYPELIB_PATH variable with lib/girepository-1.0 directories of dependencies, which is then added to wrapper by wrapGAppsHook. It also adds share directories of dependencies to XDG_DATA_DIRS, which is intended to promote GIR files but it also pollutes the closures of packages using wrapGAppsHook. + gobject-introspection setup hook populates + GI_TYPELIB_PATH variable with + lib/girepository-1.0 directories of dependencies, + which is then added to wrapper by wrapGAppsHook. It + also adds share directories of dependencies to + XDG_DATA_DIRS, which is intended to promote GIR files but + it also + pollutes + the closures of packages using wrapGAppsHook. - The setup hook currently does not work in expressions with strictDeps enabled, like Python packages. In those cases, you will need to disable it with strictDeps = false;. + The setup hook + currently + does not work in expressions with strictDeps enabled, + like Python packages. In those cases, you will need to disable it with + strictDeps = false;. - Setup hooks of gst_all_1.gstreamer and gnome3.grilo will populate the GST_PLUGIN_SYSTEM_PATH_1_0 and GRL_PLUGIN_PATH variables, respectively, which will then be added to the wrapper by wrapGAppsHook. + Setup hooks of gst_all_1.gstreamer and + gnome3.grilo will populate the + GST_PLUGIN_SYSTEM_PATH_1_0 and + GRL_PLUGIN_PATH variables, respectively, which will then + be added to the wrapper by wrapGAppsHook. - You can also pass additional arguments to makeWrapper using gappsWrapperArgs in preFixup hook: + You can also pass additional arguments to makeWrapper + using gappsWrapperArgs in preFixup + hook: preFixup = '' gappsWrapperArgs+=( @@ -138,7 +215,13 @@ preFixup = '' Updating GNOME packages - Most GNOME package offer updateScript, it is therefore possible to update to latest source tarball by running nix-shell maintainers/scripts/update.nix --argstr package gnome3.nautilus or even en masse with nix-shell maintainers/scripts/update.nix --argstr path gnome3. Read the package’s NEWS file to see what changed. + Most GNOME package offer + updateScript, + it is therefore possible to update to latest source tarball by running + nix-shell maintainers/scripts/update.nix --argstr package + gnome3.nautilus or even en masse with nix-shell + maintainers/scripts/update.nix --argstr path gnome3. Read the + package’s NEWS file to see what changed. @@ -152,7 +235,17 @@ preFixup = '' - There are no schemas avalable in XDG_DATA_DIRS. Temporarily add a random package containing schemas like gsettings-desktop-schemas to buildInputs. glib and wrapGAppsHook setup hooks will take care of making the schemas available to application and you will see the actual missing schemas with the next error. Or you can try looking through the source code for the actual schemas used. + There are no schemas avalable in XDG_DATA_DIRS. + Temporarily add a random package containing schemas like + gsettings-desktop-schemas to + buildInputs. + glib and + wrapGAppsHook + setup hooks will take care of making the schemas available to application + and you will see the actual missing schemas with the + next + error. Or you can try looking through the source code for the + actual schemas used. @@ -162,7 +255,11 @@ preFixup = '' - Package is missing some GSettings schemas. You can find out the package containing the schema with nix-locate org.gnome.foo.gschema.xml and let the hooks handle the wrapping as above. + Package is missing some GSettings schemas. You can find out the package + containing the schema with nix-locate + org.gnome.foo.gschema.xml and let + the hooks handle the wrapping as + above. @@ -172,7 +269,14 @@ preFixup = '' - This is because derivers like python.pkgs.buildPythonApplication or qt5.mkDerivation have setup-hooks automatically added that produce wrappers with makeWrapper. The simplest way to workaround that is to disable the wrapGAppsHook automatic wrapping with dontWrapGApps = true; and pass the arguments it intended to pass to makeWrapper to another. + This is because derivers like + python.pkgs.buildPythonApplication or + qt5.mkDerivation have setup-hooks automatically + added that produce wrappers with makeWrapper. The + simplest way to workaround that is to disable the + wrapGAppsHook automatic wrapping with + dontWrapGApps = true; and pass the arguments it intended to + pass to makeWrapper to another. In the case of a Python application it could look like: @@ -224,34 +328,55 @@ mkDerivation { - 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: + 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: - Replacing a GI_TYPELIB_PATH in GNOME Shell extension – we are using substituteAll to include the path to a typelib into a patch. + Replacing + a GI_TYPELIB_PATH in GNOME Shell extension – + we are using substituteAll to include the path to + a typelib into a patch. - The following examples are hardcoding GSettings schema paths. To get the schema paths we use the functions + The following examples are hardcoding GSettings schema paths. To get + the schema paths we use the functions - glib.getSchemaPath Takes a nix package attribute as an argument. + glib.getSchemaPath Takes a nix package + attribute as an argument. - glib.makeSchemaPath Takes a package output like $out and a derivation name. You should use this if the schemas you need to hardcode are in the same derivation. + glib.makeSchemaPath Takes a package output + like $out and a derivation name. You should use + this if the schemas you need to hardcode are in the same + derivation. - Hard-coding GSettings schema path in Vala plug-in (dynamically loaded library) – here, substituteAll cannot be used since the schema comes from the same package preventing us from pass its path to the function, probably due to a Nix bug. + Hard-coding + GSettings schema path in Vala plug-in (dynamically loaded + library) – here, substituteAll cannot be + used since the schema comes from the same package preventing us from + pass its path to the function, probably due to a + Nix + bug. - Hard-coding GSettings schema path in C library – nothing special other than using Coccinelle patch to generate the patch itself. + Hard-coding + GSettings schema path in C library – nothing special other + than using + Coccinelle + patch to generate the patch itself. diff --git a/doc/languages-frameworks/perl.xml b/doc/languages-frameworks/perl.xml index 065212a0e180..d5911cf67fd7 100644 --- a/doc/languages-frameworks/perl.xml +++ b/doc/languages-frameworks/perl.xml @@ -141,8 +141,8 @@ ClassC3Componentised = buildPerlPackage rec { On Darwin, if a script has too many -Idir flags in its first line - (its “shebang line”), it will not run. This can be worked around by calling - the shortenPerlShebang function from the + (its “shebang line”), it will not run. This can be worked around by + calling the shortenPerlShebang function from the postInstall phase: { stdenv, buildPerlPackage, fetchurl, shortenPerlShebang }: @@ -162,10 +162,10 @@ ImageExifTool = buildPerlPackage { ''; }; - This will remove the -I flags from the shebang line, - rewrite them in the use lib 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 -I flags from the shebang line, + rewrite them in the use lib 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.
diff --git a/doc/languages-frameworks/qt.xml b/doc/languages-frameworks/qt.xml index 3332ce8c06e4..d6f3314ab08d 100644 --- a/doc/languages-frameworks/qt.xml +++ b/doc/languages-frameworks/qt.xml @@ -4,16 +4,16 @@ Qt - 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. - Nix expression for a Qt package (<filename>default.nix</filename>) - + Nix expression for a Qt package (<filename>default.nix</filename>) + { mkDerivation, lib, qtbase }: mkDerivation { @@ -26,53 +26,51 @@ mkDerivation { - - - Import mkDerivation and Qt (such as - qtbase modules directly. Do not - import Qt package sets; the Qt versions of dependencies may not be - coherent, causing build and runtime failures. - - - - - Use mkDerivation instead of - stdenv.mkDerivation. mkDerivation - is a wrapper around stdenv.mkDerivation which - applies some Qt-specific settings. - This deriver accepts the same arguments as - stdenv.mkDerivation; refer to - for details. - - - To use another deriver instead of - stdenv.mkDerivation, use - mkDerivationWith: + + + Import mkDerivation and Qt (such as + qtbase modules directly. Do not + import Qt package sets; the Qt versions of dependencies may not be + coherent, causing build and runtime failures. + + + + + Use mkDerivation instead of + stdenv.mkDerivation. mkDerivation is + a wrapper around stdenv.mkDerivation which applies some + Qt-specific settings. This deriver accepts the same arguments as + stdenv.mkDerivation; refer to + for details. + + + To use another deriver instead of stdenv.mkDerivation, + use mkDerivationWith: mkDerivationWith myDeriver { # ... } - If you cannot use mkDerivationWith, please refer to - . - - - - - mkDerivation accepts the same arguments as - stdenv.mkDerivation, such as - buildInputs. - - + If you cannot use mkDerivationWith, please refer to + . + + + + + mkDerivation accepts the same arguments as + stdenv.mkDerivation, such as + buildInputs. + + - Locating runtime dependencies - - Qt applications need to be wrapped to find runtime dependencies. If you - cannot use mkDerivation or - mkDerivationWith above, include - wrapQtAppsHook in nativeBuildInputs: + Locating runtime dependencies + + Qt applications need to be wrapped to find runtime dependencies. If you + cannot use mkDerivation or + mkDerivationWith above, include + wrapQtAppsHook in nativeBuildInputs: stdenv.mkDerivation { # ... @@ -80,13 +78,13 @@ stdenv.mkDerivation { nativeBuildInputs = [ wrapQtAppsHook ]; } - + - Entries added to qtWrapperArgs are used to modify the - wrappers created by wrapQtAppsHook. The entries are - passed as arguments to . + Entries added to qtWrapperArgs are used to modify the + wrappers created by wrapQtAppsHook. The entries are passed + as arguments to . mkDerivation { # ... @@ -97,8 +95,8 @@ mkDerivation { - Set dontWrapQtApps to stop applications from being - wrapped automatically. It is required to wrap applications manually with + Set dontWrapQtApps to stop applications from being wrapped + automatically. It is required to wrap applications manually with wrapQtApp, using the syntax of : @@ -115,16 +113,17 @@ mkDerivation { - wrapQtAppsHook 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. + wrapQtAppsHook 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. - Libraries are built with every available version of Qt. Use the meta.broken - attribute to disable the package for unsupported Qt versions: + Libraries are built with every available version of Qt. Use the + meta.broken attribute to disable the package for + unsupported Qt versions: mkDerivation { # ... @@ -136,13 +135,13 @@ mkDerivation { - Adding a library to Nixpkgs - - Add a Qt library to all-packages.nix by adding it to the - collection inside mkLibsForQt5. This ensures that the - library is built with every available version of Qt as needed. - - Adding a Qt library to <filename>all-packages.nix</filename> + Adding a library to Nixpkgs + + Add a Qt library to all-packages.nix by adding it to + the collection inside mkLibsForQt5. This ensures that the + library is built with every available version of Qt as needed. + + Adding a Qt library to <filename>all-packages.nix</filename> { # ... @@ -156,19 +155,19 @@ mkDerivation { # ... } - - + + - Adding an application to Nixpkgs - - Add a Qt application to all-packages.nix using - libsForQt5.callPackage instead of the usual - callPackage. The former ensures that all dependencies - are built with the same version of Qt. - - Adding a Qt application to <filename>all-packages.nix</filename> + Adding an application to Nixpkgs + + Add a Qt application to all-packages.nix using + libsForQt5.callPackage instead of the usual + callPackage. The former ensures that all dependencies are + built with the same version of Qt. + + Adding a Qt application to <filename>all-packages.nix</filename> { # ... @@ -178,8 +177,7 @@ mkDerivation { # ... } - - + + -
diff --git a/doc/meta.xml b/doc/meta.xml index 58c390a68b84..49db73ab79e6 100644 --- a/doc/meta.xml +++ b/doc/meta.xml @@ -156,9 +156,9 @@ hello-2.3 A program that produces a familiar, friendly greeting - A link or a list of links to the location of Changelog for a package. - A link may use expansion to refer to the correct changelog version. - Example: + A link or a list of links to the location of Changelog for a package. A + link may use expansion to refer to the correct changelog version. + Example: "https://git.savannah.gnu.org/cgit/hello.git/plain/NEWS?h=v${version}" @@ -273,8 +273,8 @@ meta.platforms = stdenv.lib.platforms.linux; This attribute is special in that it is not actually under the meta attribute set but rather under the passthru attribute set. This is due to how - meta attributes work, and the fact that they - are supposed to contain only metadata, not derivations. + meta attributes work, and the fact that they are + supposed to contain only metadata, not derivations. diff --git a/doc/package-notes.xml b/doc/package-notes.xml index d2c660e22a9b..ef3c2a7c848a 100644 --- a/doc/package-notes.xml +++ b/doc/package-notes.xml @@ -311,7 +311,8 @@ packageOverrides = pkgs: { Elm - To start a development environment do nix-shell -p elmPackages.elm elmPackages.elm-format + To start a development environment do nix-shell -p elmPackages.elm + elmPackages.elm-format @@ -506,10 +507,11 @@ stdenv.mkDerivation { The IBus engine is based on hunspell to support completion in many languages. By default the dictionaries - de-de, en-us, fr-moderne - es-es, it-it, - sv-se and sv-fi are in use. To add - another dictionary, the package can be overridden like this: + de-de, en-us, + fr-moderne es-es, + it-it, sv-se and + sv-fi are in use. To add another dictionary, the package + can be overridden like this: ibus-engines.typing-booster.override { langs = [ "de-at" "en-gb" ]; } @@ -543,47 +545,45 @@ stdenv.mkDerivation { Nginx - Nginx is a - reverse proxy and lightweight webserver. + Nginx is a reverse proxy and + lightweight webserver.
ETags on static files served from the Nix store - HTTP has a couple different mechanisms for caching to prevent - clients from having to download the same content repeatedly - if a resource has not changed since the last time it was requested. - When nginx is used as a server for static files, it implements - the caching mechanism based on the - Last-Modified - response header automatically; unfortunately, it works by using - filesystem timestamps to determine the value of the - Last-Modified header. This doesn't give the - desired behavior when the file is in the Nix store, because all - file timestamps are set to 0 (for reasons related to build - reproducibility). + HTTP has a couple different mechanisms for caching to prevent clients from + having to download the same content repeatedly if a resource has not + changed since the last time it was requested. When nginx is used as a + server for static files, it implements the caching mechanism based on the + Last-Modified + response header automatically; unfortunately, it works by using filesystem + timestamps to determine the value of the Last-Modified + header. This doesn't give the desired behavior when the file is in the Nix + store, because all file timestamps are set to 0 (for reasons related to + build reproducibility). - Fortunately, HTTP supports an alternative (and more effective) - caching mechanism: the + Fortunately, HTTP supports an alternative (and more effective) caching + mechanism: the ETag - response header. The value of the ETag header - specifies some identifier for the particular content that the - server is sending (e.g. a hash). When a client makes a second - request for the same resource, it sends that value back in an - If-None-Match header. If the ETag value is - unchanged, then the server does not need to resend the content. + response header. The value of the ETag header specifies + some identifier for the particular content that the server is sending (e.g. + a hash). When a client makes a second request for the same resource, it + sends that value back in an If-None-Match header. If the + ETag value is unchanged, then the server does not need to resend the + content. - As of NixOS 19.09, the nginx package in Nixpkgs is patched such - that when nginx serves a file out of /nix/store, - the hash in the store path is used as the ETag - header in the HTTP response, thus providing proper caching functionality. - This happens automatically; you do not need to do modify any - configuration to get this behavior. + As of NixOS 19.09, the nginx package in Nixpkgs is patched such that when + nginx serves a file out of /nix/store, the hash in the + store path is used as the ETag header in the HTTP + response, thus providing proper caching functionality. This happens + automatically; you do not need to do modify any configuration to get this + behavior.
diff --git a/doc/package-specific-user-notes.xml b/doc/package-specific-user-notes.xml index ef23b022c887..09af69bb15d8 100644 --- a/doc/package-specific-user-notes.xml +++ b/doc/package-specific-user-notes.xml @@ -1,14 +1,10 @@ Package-specific usage notes - These chapters includes some notes - that apply to specific packages and should - answer some of the frequently asked questions - related to Nixpkgs use. - - Some useful information related to package use - can be found in package-specific development notes. - + These chapters includes some notes that apply to specific packages and should + answer some of the frequently asked questions related to Nixpkgs use. Some + useful information related to package use can be found in + package-specific development notes.
OpenGL @@ -47,7 +43,6 @@ locales of the package.
-
Emacs @@ -204,46 +199,43 @@ overrides = self: super: rec {
-
DLib - DLib is a modern, C++-based toolkit which - provides several machine learning algorithms. + DLib is a modern, C++-based + toolkit which provides several machine learning algorithms.
Compiling without AVX support - Especially older CPUs don't support - AVX - (Advanced Vector Extensions) instructions that are used by DLib to - optimize their algorithms. + Especially older CPUs don't support + AVX + (Advanced Vector Extensions) instructions that are used by + DLib to optimize their algorithms. - On the affected hardware errors like Illegal instruction will occur. - In those cases AVX support needs to be disabled: + On the affected hardware errors like Illegal instruction + will occur. In those cases AVX support needs to be disabled: self: super: { dlib = super.dlib.override { avxSupport = false; }; }
-
Unfree software All users of Nixpkgs are free software users, and many users (and developers) of Nixpkgs want to limit and tightly control their exposure to - unfree software. At the same time, many users need (or want) - to run some specific - pieces of proprietary software. Nixpkgs includes some expressions for unfree - software packages. By default unfree software cannot be installed and - doesn’t show up in searches. To allow installing unfree software in a + unfree software. At the same time, many users need (or want) to run some + specific pieces of proprietary software. Nixpkgs includes some expressions + for unfree software packages. By default unfree software cannot be installed + and doesn’t show up in searches. To allow installing unfree software in a single Nix invocation one can export NIXPKGS_ALLOW_UNFREE=1. For a persistent solution, users can set allowUnfree in the Nixpkgs configuration. @@ -256,7 +248,6 @@ overrides = self: super: rec { true for unfree packages that should be allowed.
-
Steam @@ -407,21 +398,24 @@ overrides = self: super: rec {
-
Citrix Receiver & Citrix Workspace App - Please note that the citrix_receiver package has been deprecated since its - development was discontinued by upstream - and has been replaced by the citrix workspace app. + Please note that the citrix_receiver package has been + deprecated since its development was + discontinued + by upstream and has been replaced by + the + citrix workspace app. - Citrix Receiver and - Citrix Workspace App - are a remote desktop viewers which provide access to + Citrix + Receiver and + Citrix + Workspace App are a remote desktop viewers which provide access to XenDesktop installations. @@ -432,24 +426,24 @@ overrides = self: super: rec { The tarball archive needs to be downloaded manually as the license agreements of the vendor for - Citrix Receiver - or Citrix Workspace - need to be accepted first. - Then run nix-prefetch-url file://$PWD/linuxx64-$version.tar.gz. - With the archive available - in the store the package can be built and installed with Nix. + Citrix + Receiver or + Citrix + Workspace need to be accepted first. Then run + nix-prefetch-url file://$PWD/linuxx64-$version.tar.gz. + With the archive available in the store the package can be built and + installed with Nix. Caution with <command>nix-shell</command> installs - It's recommended to install Citrix Receiver - and/or Citrix Workspace using - nix-env -i or globally to - ensure that the .desktop files are installed properly - into $XDG_CONFIG_DIRS. Otherwise it won't be possible to - open .ica files automatically from the browser to start - a Citrix connection. + It's recommended to install Citrix Receiver and/or + Citrix Workspace using nix-env -i or + globally to ensure that the .desktop files are + installed properly into $XDG_CONFIG_DIRS. Otherwise it + won't be possible to open .ica files automatically from + the browser to start a Citrix connection.
@@ -458,8 +452,8 @@ overrides = self: super: rec { Custom certificates - The Citrix Workspace App - in nixpkgs trust several certificates + The Citrix Workspace App in nixpkgs + trust several certificates from the Mozilla database by default. However several companies using Citrix might require their own corporate certificate. On distros with imperative diff --git a/doc/quick-start.xml b/doc/quick-start.xml index 292d66864a4c..39e3e7396bd5 100644 --- a/doc/quick-start.xml +++ b/doc/quick-start.xml @@ -210,9 +210,11 @@ - Optionally commit the new package and open a pull request to nixpkgs, or - use to + nixpkgs, or use + the Patches category on Discourse for sending a patch without a GitHub account. diff --git a/doc/stdenv.xml b/doc/stdenv.xml index f8c2aff97854..a4bc2809be05 100644 --- a/doc/stdenv.xml +++ b/doc/stdenv.xml @@ -736,8 +736,8 @@ passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ] commit or any other commands that cannot handle that. - For information about how to run the updates, execute - nix-shell maintainers/scripts/update.nix. + For information about how to run the updates, execute nix-shell + maintainers/scripts/update.nix. @@ -764,7 +764,8 @@ passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ] to add some commands to a phase, e.g. by defining postInstall or preFixup, as skipping some of the default actions may have unexpected consequences. The default - script for each phase is defined in the file pkgs/stdenv/generic/setup.sh. + script for each phase is defined in the file + pkgs/stdenv/generic/setup.sh.
@@ -786,7 +787,8 @@ passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ] set, the default value is used, which is $prePhases unpackPhase patchPhase $preConfigurePhases configurePhase $preBuildPhases buildPhase checkPhase $preInstallPhases installPhase - fixupPhase installCheckPhase $preDistPhases distPhase $postPhases. + fixupPhase installCheckPhase $preDistPhases distPhase + $postPhases. Usually, if you just want to add a few phases, it’s more convenient @@ -1605,7 +1607,7 @@ installTargets = "install-bin install-doc"; - Set to true to skip the fixup phase. + Set to true to skip the fixup phase. @@ -2411,12 +2413,12 @@ addEnvHooks "$hostOffset" myBashFunction The Bintools Wrapper was only just recently split off from CC Wrapper, so the division of labor is still being worked out. For example, it - shouldn't care about the C standard library, but just take a - derivation with the dynamic loader (which happens to be the glibc on - linux). Dependency finding however is a task both wrappers will continue - to need to share, and probably the most important to understand. It is - currently accomplished by collecting directories of host-platform - dependencies (i.e. buildInputs and + shouldn't care about the C standard library, but just take a derivation + with the dynamic loader (which happens to be the glibc on linux). + Dependency finding however is a task both wrappers will continue to need + to share, and probably the most important to understand. It is currently + accomplished by collecting directories of host-platform dependencies + (i.e. buildInputs and nativeBuildInputs) in environment variables. The Bintools Wrapper's setup hook causes any lib and lib64 subdirectories to be added to @@ -2633,7 +2635,8 @@ addEnvHooks "$hostOffset" myBashFunction - Hooks related to GNOME platform and related libraries like GLib, GTK and GStreamer are described in . + Hooks related to GNOME platform and related libraries like GLib, GTK and + GStreamer are described in . @@ -2688,12 +2691,12 @@ addEnvHooks "$hostOffset" myBashFunction At /var/lib/cntr the sandboxed filesystem is mounted. All commands and files of the system are still accessible within the shell. To execute commands from the sandbox use the cntr exec - subcommand. cntr is only supported - on Linux-based platforms. To use it first add cntr to - your environment.systemPackages on NixOS or - alternatively to the root user on non-NixOS systems. Then in the package - that is supposed to be inspected, add breakpointHook - to nativeBuildInputs. + subcommand. cntr is only supported on Linux-based + platforms. To use it first add cntr to your + environment.systemPackages on NixOS or alternatively + to the root user on non-NixOS systems. Then in the package that is + supposed to be inspected, add breakpointHook to + nativeBuildInputs. nativeBuildInputs = [ breakpointHook ]; @@ -2703,11 +2706,11 @@ nativeBuildInputs = [ breakpointHook ]; Caution with remote builds - This won't work with remote builds as the build environment is on - a different machine and can't be accessed by cntr. - Remote builds can be turned off by setting --option builders '' - for nix-build or --builders '' for - nix build. + This won't work with remote builds as the build environment is on a + different machine and can't be accessed by cntr. + Remote builds can be turned off by setting --option builders + '' for nix-build or --builders + '' for nix build. @@ -2806,17 +2809,78 @@ postInstall = '' - meson + Meson - Overrides the configure phase to run meson to generate Ninja files. You - can disable this behavior by setting configurePhase to a custom value, - or by setting dontUseMesonConfigure. To run these files, you should - accompany meson with ninja. mesonFlags controls only the flags passed to - meson. By default, parallel building is enabled as Meson supports + Overrides the configure phase to run meson to generate Ninja files. To + run these files, you should accompany Meson with ninja. By default, + enableParallelBuilding is enabled as Meson supports parallel building almost everywhere. + + Variables controlling Meson + + + mesonFlags + + + + Controls the flags passed to meson. + + + + + + mesonBuildType + + + + Which + --buildtype + to pass to Meson. We default to plain. + + + + + + mesonAutoFeatures + + + + What value to set + -Dauto_features= + to. We default to enabled. + + + + + + mesonWrapMode + + + + What value to set + -Dwrap_mode= + to. We default to nodownload as we disallow + network access. + + + + + + dontUseMesonConfigure + + + + Disables using Meson's configurePhase. + + + + @@ -2851,8 +2915,8 @@ postInstall = '' Overrides the configure, build, and install phases. This will run the "waf" script used by many projects. If wafPath (default ./waf) doesn’t - exist, it will copy the version of waf available in Nixpkgs. wafFlags can - be used to pass flags to the waf script. + exist, it will copy the version of waf available in Nixpkgs. wafFlags + can be used to pass flags to the waf script.