about summary refs log tree commit diff
path: root/nixpkgs/doc/languages-frameworks
diff options
context:
space:
mode:
authorAlyssa Ross <hi@alyssa.is>2021-09-27 16:00:58 +0000
committerAlyssa Ross <hi@alyssa.is>2021-09-27 16:00:58 +0000
commitc504e5d19d940926b3ddcf62c983d66f49f3cbb2 (patch)
treeec955e58bcac2cb93b9f8c10786b23f61d40cd7e /nixpkgs/doc/languages-frameworks
parent72789cefce7b17419815f600fbd18238d89afcc9 (diff)
parent1737f98af6667560e3e4f930312f9b5002649d04 (diff)
downloadnixlib-c504e5d19d940926b3ddcf62c983d66f49f3cbb2.tar
nixlib-c504e5d19d940926b3ddcf62c983d66f49f3cbb2.tar.gz
nixlib-c504e5d19d940926b3ddcf62c983d66f49f3cbb2.tar.bz2
nixlib-c504e5d19d940926b3ddcf62c983d66f49f3cbb2.tar.lz
nixlib-c504e5d19d940926b3ddcf62c983d66f49f3cbb2.tar.xz
nixlib-c504e5d19d940926b3ddcf62c983d66f49f3cbb2.tar.zst
nixlib-c504e5d19d940926b3ddcf62c983d66f49f3cbb2.zip
Merge commit '1737f98af6667560e3e4f930312f9b5002649d04'
Conflicts:
	nixpkgs/nixos/modules/services/networking/ssh/sshd.nix
	nixpkgs/pkgs/applications/networking/irc/weechat/scripts/default.nix
	nixpkgs/pkgs/development/node-packages/default.nix
	nixpkgs/pkgs/development/python-modules/priority/deadline.patch
Diffstat (limited to 'nixpkgs/doc/languages-frameworks')
-rw-r--r--nixpkgs/doc/languages-frameworks/coq.section.md4
-rw-r--r--nixpkgs/doc/languages-frameworks/index.xml2
-rw-r--r--nixpkgs/doc/languages-frameworks/nim.section.md91
-rw-r--r--nixpkgs/doc/languages-frameworks/octave.section.md100
-rw-r--r--nixpkgs/doc/languages-frameworks/python.section.md2
-rw-r--r--nixpkgs/doc/languages-frameworks/rust.section.md34
6 files changed, 224 insertions, 9 deletions
diff --git a/nixpkgs/doc/languages-frameworks/coq.section.md b/nixpkgs/doc/languages-frameworks/coq.section.md
index 39b60d83ac7d..a5155aedaf52 100644
--- a/nixpkgs/doc/languages-frameworks/coq.section.md
+++ b/nixpkgs/doc/languages-frameworks/coq.section.md
@@ -28,12 +28,12 @@ The recommended way of defining a derivation for a Coq library, is to use the `c
 * `domain` (optional, defaults to `"github.com"`), domains including the strings `"github"` or `"gitlab"` in their names are automatically supported, otherwise, one must change the `fetcher` argument to support them (cf `pkgs/development/coq-modules/heq/default.nix` for an example),
 * `releaseRev` (optional, defaults to `(v: v)`), provides a default mapping from release names to revision hashes/branch names/tags,
 * `displayVersion` (optional), provides a way to alter the computation of `name` from `pname`, by explaining how to display version numbers,
-* `namePrefix` (optional), provides a way to alter the computation of `name` from `pname`, by explaining which dependencies must occur in `name`,
+* `namePrefix` (optional, defaults to `[ "coq" ]`), provides a way to alter the computation of `name` from `pname`, by explaining which dependencies must occur in `name`,
 * `extraBuildInputs` (optional), by default `buildInputs` just contains `coq`, this allows to add more build inputs,
 * `mlPlugin` (optional, defaults to `false`). Some extensions (plugins) might require OCaml and sometimes other OCaml packages. Standard dependencies can be added by setting the current option to `true`. For a finer grain control, the `coq.ocamlPackages` attribute can be used in `extraBuildInputs` to depend on the same package set Coq was built against.
 * `useDune2ifVersion` (optional, default to `(x: false)` uses Dune2 to build the package if the provided predicate evaluates to true on the version, e.g. `useDune2if = versions.isGe "1.1"`  will use dune if the version of the package is greater or equal to `"1.1"`,
 * `useDune2` (optional, defaults to `false`) uses Dune2 to build the package if set to true, the presence of this attribute overrides the behavior of the previous one.
-* `opam-name` (optional, defaults to `coq-` followed by the value of `pname`), name of the Dune package to build.
+* `opam-name` (optional, defaults to concatenating with a dash separator the components of `namePrefix` and `pname`), name of the Dune package to build.
 * `enableParallelBuilding` (optional, defaults to `true`), since it is activated by default, we provide a way to disable it.
 * `extraInstallFlags` (optional), allows to extend `installFlags` which initializes the variable `COQMF_COQLIB` so as to install in the proper subdirectory. Indeed Coq libraries should be installed in `$(out)/lib/coq/${coq.coq-version}/user-contrib/`. Such directories are automatically added to the `$COQPATH` environment variable by the hook defined in the Coq derivation.
 * `setCOQBIN` (optional, defaults to `true`), by default, the environment variable `$COQBIN` is set to the current Coq's binary, but one can disable this behavior by setting it to `false`,
diff --git a/nixpkgs/doc/languages-frameworks/index.xml b/nixpkgs/doc/languages-frameworks/index.xml
index 49cdf94a44ab..b010f27cac02 100644
--- a/nixpkgs/doc/languages-frameworks/index.xml
+++ b/nixpkgs/doc/languages-frameworks/index.xml
@@ -23,7 +23,9 @@
  <xi:include href="javascript.section.xml" />
  <xi:include href="lua.section.xml" />
  <xi:include href="maven.section.xml" />
+ <xi:include href="nim.section.xml" />
  <xi:include href="ocaml.section.xml" />
+ <xi:include href="octave.section.xml" />
  <xi:include href="perl.section.xml" />
  <xi:include href="php.section.xml" />
  <xi:include href="python.section.xml" />
diff --git a/nixpkgs/doc/languages-frameworks/nim.section.md b/nixpkgs/doc/languages-frameworks/nim.section.md
new file mode 100644
index 000000000000..16dce61d71c9
--- /dev/null
+++ b/nixpkgs/doc/languages-frameworks/nim.section.md
@@ -0,0 +1,91 @@
+# Nim {#nim}
+
+## Overview {#nim-overview}
+
+The Nim compiler, a builder function, and some packaged libraries are available
+in Nixpkgs. Until now each compiler release has been effectively backwards
+compatible so only the latest version is available.
+
+## Nim program packages in Nixpkgs {#nim-program-packages-in-nixpkgs}
+
+Nim programs can be built using `nimPackages.buildNimPackage`. In the
+case of packages not containing exported library code the attribute
+`nimBinOnly` should be set to `true`.
+
+The following example shows a Nim program that depends only on Nim libraries:
+
+```nix
+{ lib, nimPackages, fetchurl }:
+
+nimPackages.buildNimPackage rec {
+  pname = "hottext";
+  version = "1.4";
+
+  nimBinOnly = true;
+
+  src = fetchurl {
+    url = "https://git.sr.ht/~ehmry/hottext/archive/v${version}.tar.gz";
+    sha256 = "sha256-hIUofi81zowSMbt1lUsxCnVzfJGN3FEiTtN8CEFpwzY=";
+  };
+
+  buildInputs = with nimPackages; [
+    bumpy
+    chroma
+    flatty
+    nimsimd
+    pixie
+    sdl2
+    typography
+    vmath
+    zippy
+  ];
+}
+
+```
+
+## Nim library packages in Nixpkgs {#nim-library-packages-in-nixpkgs}
+
+
+Nim libraries can also be built using `nimPackages.buildNimPackage`, but
+often the product of a fetcher is sufficient to satisfy a dependency.
+The `fetchgit`, `fetchFromGitHub`, and `fetchNimble` functions yield an
+output that can be discovered during the `configurePhase` of `buildNimPackage`.
+
+Nim library packages are listed in
+[pkgs/top-level/nim-packages.nix](https://github.com/NixOS/nixpkgs/blob/master/pkgs/top-level/nim-packages.nix) and implemented at
+[pkgs/development/nim-packages](https://github.com/NixOS/nixpkgs/tree/master/pkgs/development/nim-packages).
+
+The following example shows a Nim library that propagates a dependency on a
+non-Nim package:
+```nix
+{ lib, buildNimPackage, fetchNimble, SDL2 }:
+
+buildNimPackage rec {
+  pname = "sdl2";
+  version = "2.0.4";
+  src = fetchNimble {
+    inherit pname version;
+    hash = "sha256-Vtcj8goI4zZPQs2TbFoBFlcR5UqDtOldaXSH/+/xULk=";
+  };
+  propagatedBuildInputs = [ SDL2 ];
+}
+```
+
+## `buildNimPackage` parameters {#buildnimpackage-parameters}
+
+All parameters from `stdenv.mkDerivation` function are still supported. The
+following are specific to `buildNimPackage`:
+
+* `nimBinOnly ? false`: If `true` then build only the programs listed in
+  the Nimble file in the packages sources.
+* `nimbleFile`: Specify the Nimble file location of the package being built
+  rather than discover the file at build-time.
+* `nimRelease ? true`: Build the package in *release* mode.
+* `nimDefines ? []`: A list of Nim defines. Key-value tuples are not supported.
+* `nimFlags ? []`: A list of command line arguments to pass to the Nim compiler.
+  Use this to specify defines with arguments in the form of `-d:${name}=${value}`.
+* `nimDoc` ? false`: Build and install HTML documentation.
+
+* `buildInputs` ? []: The packages listed here will be searched for `*.nimble`
+  files which are used to populate the Nim library path. Otherwise the standard
+  behavior is in effect.
diff --git a/nixpkgs/doc/languages-frameworks/octave.section.md b/nixpkgs/doc/languages-frameworks/octave.section.md
new file mode 100644
index 000000000000..ff872f4a7558
--- /dev/null
+++ b/nixpkgs/doc/languages-frameworks/octave.section.md
@@ -0,0 +1,100 @@
+# Octave {#sec-octave}
+
+## Introduction {#ssec-octave-introduction}
+
+Octave is a modular scientific programming language and environment.
+A majority of the packages supported by Octave from their [website](https://octave.sourceforge.io/packages.php) are packaged in nixpkgs.
+
+## Structure {#ssec-octave-structure}
+
+All Octave add-on packages are available in two ways:
+1. Under the top-level `Octave` attribute, `octave.pkgs`.
+2. As a top-level attribute, `octavePackages`.
+
+## Packaging Octave Packages {#ssec-octave-packaging}
+
+Nixpkgs provides a function `buildOctavePackage`, a generic package builder function for any Octave package that complies with the Octave's current packaging format.
+
+All Octave packages are defined in [pkgs/top-level/octave-packages.nix](https://github.com/NixOS/nixpkgs/blob/master/pkgs/top-level/octave-packages.nix) rather than `pkgs/all-packages.nix`.
+Each package is defined in their own file in the [pkgs/development/octave-modules](https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/octave-modules) directory.
+Octave packages are made available through `all-packages.nix` through both the attribute `octavePackages` and `octave.pkgs`.
+You can test building an Octave package as follows:
+
+```ShellSession
+$ nix-build -A octavePackages.symbolic
+```
+
+When building Octave packages with `nix-build`, the `buildOctavePackage` function adds `octave-octaveVersion` to; the start of the package's name attribute.
+
+This can be required when installing the package using `nix-env`:
+
+```ShellSession
+$ nix-env -i octave-6.2.0-symbolic
+```
+
+Although, you can also install it using the attribute name:
+
+```ShellSession
+$ nix-env -i -A octavePackages.symbolic
+```
+
+You can build Octave with packages by using the `withPackages` passed-through function.
+
+```ShellSession
+$ nix-shell -p 'octave.withPackages (ps: with ps; [ symbolic ])'
+```
+
+This will also work in a `shell.nix` file.
+
+```nix
+{ pkgs ? import <nixpkgs> { }}:
+
+pkgs.mkShell {
+  nativeBuildInputs = with pkgs; [
+    (octave.withPackages (opkgs: with opkgs; [ symbolic ]))
+  ];
+}
+```
+
+### `buildOctavePackage` Steps {#sssec-buildOctavePackage-steps}
+
+The `buildOctavePackage` does several things to make sure things work properly.
+
+1. Sets the environment variable `OCTAVE_HISTFILE` to `/dev/null` during package compilation so that the commands run through the Octave interpreter directly are not logged.
+2. Skips the configuration step, because the packages are stored as gzipped tarballs, which Octave itself handles directly.
+3. Change the hierarchy of the tarball so that only a single directory is at the top-most level of the tarball.
+4. Use Octave itself to run the `pkg build` command, which unzips the tarball, extracts the necessary files written in Octave, and compiles any code written in C++ or Fortran, and places the fully compiled artifact in `$out`.
+
+`buildOctavePackage` is built on top of `stdenv` in a standard way, allowing most things to be customized.
+
+### Handling Dependencies {#sssec-octave-handling-dependencies}
+
+In Octave packages, there are four sets of dependencies that can be specified:
+
+`nativeBuildInputs`
+: Just like other packages, `nativeBuildInputs` is intended for architecture-dependent build-time-only dependencies.
+
+`buildInputs`
+: Like other packages, `buildInputs` is intended for architecture-independent build-time-only dependencies.
+
+`propagatedBuildInputs`
+: Similar to other packages, `propagatedBuildInputs` is intended for packages that are required for both building and running of the package.
+See [Symbolic](https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/octave-modules/symbolic/default.nix) for how this works and why it is needed.
+
+`requiredOctavePackages`
+: This is a special dependency that ensures the specified Octave packages are dependent on others, and are made available simultaneously when loading them in Octave.
+
+### Installing Octave Packages {#sssec-installing-octave-packages}
+
+By default, the `buildOctavePackage` function does _not_ install the requested package into Octave for use.
+The function will only build the requested package.
+This is due to Octave maintaining an text-based database about which packages are installed where.
+To this end, when all the requested packages have been built, the Octave package and all its add-on packages are put together into an environment, similar to Python.
+
+1. First, all the Octave binaries are wrapped with the environment variable `OCTAVE_SITE_INITFILE` set to a file in `$out`, which is required for Octave to be able to find the non-standard package database location.
+2. Because of the way `buildEnv` works, all tarballs that are present (which should be all Octave packages to install) should be removed.
+3. The path down to the default install location of Octave packages is recreated so that Nix-operated Octave can install the packages.
+4. Install the packages into the `$out` environment while writing package entries to the database file.
+This database file is unique for each different (according to Nix) environment invocation.
+5. Rewrite the Octave-wide startup file to read from the list of packages installed in that particular environment.
+6. Wrap any programs that are required by the Octave packages so that they work with all the paths defined within the environment.
diff --git a/nixpkgs/doc/languages-frameworks/python.section.md b/nixpkgs/doc/languages-frameworks/python.section.md
index 987ea1af9daa..cc1a7083dc25 100644
--- a/nixpkgs/doc/languages-frameworks/python.section.md
+++ b/nixpkgs/doc/languages-frameworks/python.section.md
@@ -1513,7 +1513,7 @@ If you need to change a package's attribute(s) from `configuration.nix` you coul
     python = super.python.override {
       packageOverrides = python-self: python-super: {
         twisted = python-super.twisted.overrideAttrs (oldAttrs: {
-          src = super.fetchPipy {
+          src = super.fetchPypi {
             pname = "twisted";
             version = "19.10.0";
             sha256 = "7394ba7f272ae722a74f3d969dcf599bc4ef093bc392038748a490f1724a515d";
diff --git a/nixpkgs/doc/languages-frameworks/rust.section.md b/nixpkgs/doc/languages-frameworks/rust.section.md
index 9de9a06465f8..b2f045b11b32 100644
--- a/nixpkgs/doc/languages-frameworks/rust.section.md
+++ b/nixpkgs/doc/languages-frameworks/rust.section.md
@@ -20,7 +20,7 @@ or use Mozilla's [Rust nightlies overlay](#using-the-rust-nightlies-overlay).
 Rust applications are packaged by using the `buildRustPackage` helper from `rustPlatform`:
 
 ```nix
-{ lib, rustPlatform }:
+{ lib, fetchFromGitHub, rustPlatform }:
 
 rustPlatform.buildRustPackage rec {
   pname = "ripgrep";
@@ -116,22 +116,44 @@ is updated after every change to `Cargo.lock`. Therefore,
 a `Cargo.lock` file using the `cargoLock` argument. For example:
 
 ```nix
-rustPlatform.buildRustPackage rec {
+rustPlatform.buildRustPackage {
   pname = "myproject";
   version = "1.0.0";
 
   cargoLock = {
     lockFile = ./Cargo.lock;
-  }
+  };
 
   # ...
 }
 ```
 
 This will retrieve the dependencies using fixed-output derivations from
-the specified lockfile. Note that setting `cargoLock.lockFile` doesn't
-add a `Cargo.lock` to your `src`, and a `Cargo.lock` is still required
-to build a rust package. A simple fix is to use:
+the specified lockfile.
+
+One caveat is that `Cargo.lock` cannot be patched in the `patchPhase`
+because it runs after the dependencies have already been fetched. If
+you need to patch or generate the lockfile you can alternatively set
+`cargoLock.lockFileContents` to a string of its contents:
+
+```nix
+rustPlatform.buildRustPackage {
+  pname = "myproject";
+  version = "1.0.0";
+
+  cargoLock = let
+    fixupLockFile = path: f (builtins.readFile path);
+  in {
+    lockFileContents = fixupLockFile ./Cargo.lock;
+  };
+
+  # ...
+}
+```
+
+Note that setting `cargoLock.lockFile` or `cargoLock.lockFileContents`
+doesn't add a `Cargo.lock` to your `src`, and a `Cargo.lock` is still
+required to build a rust package. A simple fix is to use:
 
 ```nix
 postPatch = ''