diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/builders/packages/firefox.section.md | 13 | ||||
| -rw-r--r-- | doc/builders/packages/index.xml | 2 | ||||
| -rw-r--r-- | doc/builders/packages/shell-helpers.section.md | 12 | ||||
| -rw-r--r-- | doc/builders/packages/shell-helpers.xml | 21 | ||||
| -rw-r--r-- | doc/languages-frameworks/gnome.xml | 34 | ||||
| -rw-r--r-- | doc/languages-frameworks/index.xml | 2 | ||||
| -rw-r--r-- | doc/languages-frameworks/ocaml.section.md | 70 | ||||
| -rw-r--r-- | doc/languages-frameworks/ocaml.xml | 73 | ||||
| -rw-r--r-- | doc/stdenv/stdenv.xml | 2 |
9 files changed, 127 insertions, 102 deletions
diff --git a/doc/builders/packages/firefox.section.md b/doc/builders/packages/firefox.section.md index 2f89da2d4595..28fa3f0dbd7c 100644 --- a/doc/builders/packages/firefox.section.md +++ b/doc/builders/packages/firefox.section.md @@ -1,4 +1,4 @@ -# Firefox +# Firefox {#sec-firefox} ## Build wrapped Firefox with extensions and policies @@ -7,7 +7,7 @@ The `wrapFirefox` function allows to pass policies, preferences and extension th ```nix { myFirefox = wrapFirefox firefox-unwrapped { - extraExtensions = [ + nixExtensions = [ (fetchFirefoxAddon { name = "ublock"; url = "https://addons.mozilla.org/firefox/downloads/file/3679754/ublock_origin-1.31.0-an+fx.xpi"; @@ -38,3 +38,12 @@ The `wrapFirefox` function allows to pass policies, preferences and extension th }; } ``` + +If `nixExtensions != null` then all manually installed addons will be uninstalled from your browser profile. +To view available enterprise policies visit [enterprise policies](https://github.com/mozilla/policy-templates#enterprisepoliciesenabled) +or type into the Firefox url bar: `about:policies#documentation`. +Nix installed addons do not have a valid signature, which is why signature verification is disabled. This does not compromise security because downloaded addons are checksumed and manual addons can't be installed. + +## Troubleshooting {#sec-firefox-troubleshooting} +If addons do not appear installed although they have been defined in your nix configuration file reset the local addon state of your Firefox profile by clicking `help -> restart with addons disabled -> restart -> refresh firefox`. This can happen if you switch from manual addon mode to nix addon mode and then back to manual mode and then again to nix addon mode. + diff --git a/doc/builders/packages/index.xml b/doc/builders/packages/index.xml index 38d72a4748f6..c7a4aa9f47dc 100644 --- a/doc/builders/packages/index.xml +++ b/doc/builders/packages/index.xml @@ -17,7 +17,7 @@ <xi:include href="locales.xml" /> <xi:include href="nginx.section.xml" /> <xi:include href="opengl.section.xml" /> - <xi:include href="shell-helpers.xml" /> + <xi:include href="shell-helpers.section.xml" /> <xi:include href="steam.xml" /> <xi:include href="cataclysm-dda.section.xml" /> <xi:include href="urxvt.section.xml" /> diff --git a/doc/builders/packages/shell-helpers.section.md b/doc/builders/packages/shell-helpers.section.md new file mode 100644 index 000000000000..57b8619c5007 --- /dev/null +++ b/doc/builders/packages/shell-helpers.section.md @@ -0,0 +1,12 @@ +# Interactive shell helpers {#sec-shell-helpers} + +Some packages provide the shell integration to be more useful. But unlike other systems, nix doesn't have a standard `share` directory location. This is why a bunch `PACKAGE-share` scripts are shipped that print the location of the corresponding shared folder. Current list of such packages is as following: + +- `fzf` : `fzf-share` + +E.g. `fzf` can then used in the `.bashrc` like this: + +```bash +source "$(fzf-share)/completion.bash" +source "$(fzf-share)/key-bindings.bash" +``` diff --git a/doc/builders/packages/shell-helpers.xml b/doc/builders/packages/shell-helpers.xml deleted file mode 100644 index a4ac9022c4ce..000000000000 --- a/doc/builders/packages/shell-helpers.xml +++ /dev/null @@ -1,21 +0,0 @@ -<section xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xml:id="sec-shell-helpers"> - <title>Interactive shell helpers</title> - - <para> - Some packages provide the shell integration to be more useful. But unlike other systems, nix doesn't have a standard share directory location. This is why a bunch <command>PACKAGE-share</command> scripts are shipped that print the location of the corresponding shared folder. Current list of such packages is as following: - <itemizedlist> - <listitem> - <para> - <literal>fzf</literal>: <command>fzf-share</command> - </para> - </listitem> - </itemizedlist> - E.g. <literal>fzf</literal> can then used in the .bashrc like this: -<screen> - source "$(fzf-share)/completion.bash" - source "$(fzf-share)/key-bindings.bash" -</screen> - </para> -</section> diff --git a/doc/languages-frameworks/gnome.xml b/doc/languages-frameworks/gnome.xml index 159216ca981f..f555cacbd2c4 100644 --- a/doc/languages-frameworks/gnome.xml +++ b/doc/languages-frameworks/gnome.xml @@ -28,6 +28,22 @@ </para> </section> + <section xml:id="ssec-gnome-gdk-pixbuf-loaders"> + <title>GdkPixbuf loaders</title> + + <para> + GTK applications typically use <link xlink:href="https://developer.gnome.org/gdk-pixbuf/stable/">GdkPixbuf</link> to load images. But <package>gdk-pixbuf</package> package only supports basic bitmap formats like JPEG, PNG or TIFF, requiring to use third-party loader modules for other formats. This is especially painful since GTK itself includes SVG icons, which cannot be rendered without a loader provided by <package>librsvg</package>. + </para> + + <para> + Unlike other libraries mentioned in this section, GdkPixbuf only supports a single value in its controlling environment variable <envar>GDK_PIXBUF_MODULE_FILE</envar>. It is supposed to point to a cache file containing information about the available loaders. Each loader package will contain a <filename>lib/gdk-pixbuf-2.0/2.10.0/loaders.cache</filename> file describing the default loaders in <package>gdk-pixbuf</package> package plus the loader contained in the package itself. If you want to use multiple third-party loaders, you will need to create your own cache file manually. Fortunately, this is pretty rare as <link xlink:href="https://gitlab.gnome.org/federico/gdk-pixbuf-survey/blob/master/src/modules.md">not many loaders exist</link>. + </para> + + <para> + <package>gdk-pixbuf</package> contains <link linkend="ssec-gnome-hooks-gdk-pixbuf">a setup hook</link> that sets <envar>GDK_PIXBUF_MODULE_FILE</envar> from dependencies but as mentioned in further section, it is pretty limited. Loaders should propagate this setup hook. + </para> + </section> + <section xml:id="ssec-gnome-icons"> <title>Icons</title> @@ -100,9 +116,16 @@ preFixup = '' 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: + </para> + <para> + Fortunately, there is <package xml:id="ssec-gnome-hooks-wrapgappshook">wrapGAppsHook</package>. It works in conjunction with other setup hooks that populate environment variables, and it will then wrap all executables in <filename>bin</filename> and <filename>libexec</filename> directories using said variables. + </para> + <para> + For convenience, it also adds <package>dconf.lib</package> for a GIO module implementing a GSettings backend using <package>dconf</package>, <package>gtk3</package> for GSettings schemas, and <package>librsvg</package> for GdkPixbuf loader to the closure. In case you are packaging a program without a graphical interface, you might want to use <package xml:id="ssec-gnome-hooks-wrapgappsnoguihook">wrapGAppsNoGuiHook</package>, which runs the same script as <package>wrapGAppsHook</package> but does not bring <package>gtk3</package> and <package>librsvg</package> into the closure. + </para> + <para> <itemizedlist> - <listitem xml:id="ssec-gnome-hooks-wrapgappshook"> + <listitem> <para> <package>wrapGAppsHook</package> itself will add the package’s <filename>share</filename> directory to <envar>XDG_DATA_DIRS</envar>. </para> @@ -112,6 +135,11 @@ preFixup = '' <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-gdk-pixbuf"> + <para> + <package>gdk-pixbuf</package> setup hook will populate <envar>GDK_PIXBUF_MODULE_FILE</envar> with the path to biggest <filename>loaders.cache</filename> file from the dependencies containing <link xlink:href="ssec-gnome-gdk-pixbuf-loaders">GdkPixbuf loaders</link>. This works fine when there are only two packages containing loaders (<package>gdk-pixbuf</package> and e.g. <package>librsvg</package>) – it will choose the second one, reasonably expecting that it will be bigger since it describes extra loader in addition to the default ones. But when there are more than two loader packages, this logic will break. One possible solution would be constructing a custom cache file for each package containing a program like <filename>services/x11/gdk-pixbuf.nix</filename> NixOS module does. <package>wrapGAppsHook</package> copies the <envar>GDK_PIXBUF_MODULE_FILE</envar> environment variable into the produced wrapper. + </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>. @@ -178,7 +206,7 @@ preFixup = '' </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. + There are no schemas available 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> diff --git a/doc/languages-frameworks/index.xml b/doc/languages-frameworks/index.xml index 5046ce00b9a9..daa57cf1f865 100644 --- a/doc/languages-frameworks/index.xml +++ b/doc/languages-frameworks/index.xml @@ -21,7 +21,7 @@ <xi:include href="lua.section.xml" /> <xi:include href="maven.section.xml" /> <xi:include href="node.section.xml" /> - <xi:include href="ocaml.xml" /> + <xi:include href="ocaml.section.xml" /> <xi:include href="perl.xml" /> <xi:include href="php.section.xml" /> <xi:include href="python.section.xml" /> diff --git a/doc/languages-frameworks/ocaml.section.md b/doc/languages-frameworks/ocaml.section.md new file mode 100644 index 000000000000..1c5a5473a05e --- /dev/null +++ b/doc/languages-frameworks/ocaml.section.md @@ -0,0 +1,70 @@ +# OCaml {#sec-language-ocaml} + +OCaml libraries should be installed in `$(out)/lib/ocaml/${ocaml.version}/site-lib/`. Such directories are automatically added to the `$OCAMLPATH` environment variable when building another package that depends on them or when opening a `nix-shell`. + +Given that most of the OCaml ecosystem is now built with dune, nixpkgs includes a convenience build support function called `buildDunePackage` that will build an OCaml package using dune, OCaml and findlib and any additional dependencies provided as `buildInputs` or `propagatedBuildInputs`. + +Here is a simple package example. It defines an (optional) attribute `minimumOCamlVersion` that will be used to throw a descriptive evaluation error if building with an older OCaml is attempted. It uses the `fetchFromGitHub` fetcher to get its source. It sets the `doCheck` (optional) attribute to `true` which means that tests will be run with `dune runtest -p angstrom` after the build (`dune build -p angstrom`) is complete. It uses `alcotest` as a build input (because it is needed to run the tests) and `bigstringaf` and `result` as propagated build inputs (thus they will also be available to libraries depending on this library). The library will be installed using the `angstrom.install` file that dune generates. + +```nix +{ stdenv +, fetchFromGitHub +, buildDunePackage +, alcotest +, result +, bigstringaf +}: + +buildDunePackage rec { + pname = "angstrom"; + version = "0.10.0"; + + minimumOCamlVersion = "4.03"; + + src = fetchFromGitHub { + owner = "inhabitedtype"; + repo = pname; + rev = version; + sha256 = "0lh6024yf9ds0nh9i93r9m6p5psi8nvrqxl5x7jwl13zb0r9xfpw"; + }; + + buildInputs = [ alcotest ]; + propagatedBuildInputs = [ bigstringaf result ]; + doCheck = true; + + meta = { + homepage = "https://github.com/inhabitedtype/angstrom"; + description = "OCaml parser combinators built for speed and memory efficiency"; + license = stdenv.lib.licenses.bsd3; + maintainers = with stdenv.lib.maintainers; [ sternenseemann ]; + }; +} +``` + +Here is a second example, this time using a source archive generated with `dune-release`. It is a good idea to use this archive when it is available as it will usually contain substituted variables such as a `%%VERSION%%` field. This library does not depend on any other OCaml library and no tests are run after building it. + +```nix +{ stdenv +, fetchurl +, buildDunePackage +}: + +buildDunePackage rec { + pname = "wtf8"; + version = "1.0.1"; + + minimumOCamlVersion = "4.01"; + + src = fetchurl { + url = "https://github.com/flowtype/ocaml-${pname}/releases/download/v${version}/${pname}-${version}.tbz"; + sha256 = "1msg3vycd3k8qqj61sc23qks541cxpb97vrnrvrhjnqxsqnh6ygq"; + }; + + meta = with stdenv.lib; { + homepage = "https://github.com/flowtype/ocaml-wtf8"; + description = "WTF-8 is a superset of UTF-8 that allows unpaired surrogates."; + license = licenses.mit; + maintainers = [ maintainers.eqyiel ]; + }; +} +``` diff --git a/doc/languages-frameworks/ocaml.xml b/doc/languages-frameworks/ocaml.xml deleted file mode 100644 index 3f72092ec150..000000000000 --- a/doc/languages-frameworks/ocaml.xml +++ /dev/null @@ -1,73 +0,0 @@ -<section xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xml:id="sec-language-ocaml"> - <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>. - </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>. - </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. - </para> - -<programlisting> -{ stdenv, fetchFromGitHub, buildDunePackage, alcotest, result, bigstringaf }: - -buildDunePackage rec { - pname = "angstrom"; - version = "0.10.0"; - - minimumOCamlVersion = "4.03"; - - src = fetchFromGitHub { - owner = "inhabitedtype"; - repo = pname; - rev = version; - sha256 = "0lh6024yf9ds0nh9i93r9m6p5psi8nvrqxl5x7jwl13zb0r9xfpw"; - }; - - buildInputs = [ alcotest ]; - propagatedBuildInputs = [ bigstringaf result ]; - doCheck = true; - - meta = { - homepage = "https://github.com/inhabitedtype/angstrom"; - description = "OCaml parser combinators built for speed and memory efficiency"; - license = stdenv.lib.licenses.bsd3; - maintainers = with stdenv.lib.maintainers; [ sternenseemann ]; - }; -} -</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. - </para> - -<programlisting> -{ stdenv, fetchurl, buildDunePackage }: - -buildDunePackage rec { - pname = "wtf8"; - version = "1.0.1"; - - minimumOCamlVersion = "4.01"; - - src = fetchurl { - url = "https://github.com/flowtype/ocaml-${pname}/releases/download/v${version}/${pname}-${version}.tbz"; - sha256 = "1msg3vycd3k8qqj61sc23qks541cxpb97vrnrvrhjnqxsqnh6ygq"; - }; - - meta = with stdenv.lib; { - homepage = "https://github.com/flowtype/ocaml-wtf8"; - description = "WTF-8 is a superset of UTF-8 that allows unpaired surrogates."; - license = licenses.mit; - maintainers = [ maintainers.eqyiel ]; - }; -} -</programlisting> -</section> diff --git a/doc/stdenv/stdenv.xml b/doc/stdenv/stdenv.xml index 46ee97927eac..282893b0ca2b 100644 --- a/doc/stdenv/stdenv.xml +++ b/doc/stdenv/stdenv.xml @@ -1989,7 +1989,7 @@ addEnvHooks "$hostOffset" myBashFunction </term> <listitem> <para> - Exports <envar>GDK_PIXBUF_MODULE_FILE</envar> environment variable to the builder. Add librsvg package to <varname>buildInputs</varname> to get svg support. + Exports <envar>GDK_PIXBUF_MODULE_FILE</envar> environment variable to the builder. Add librsvg package to <varname>buildInputs</varname> to get svg support. See also <xref linkend="ssec-gnome-hooks-gdk-pixbuf" />. </para> </listitem> </varlistentry> |