Merge pull request #137243 from KarlJoad/octave-docs

octavePackages: add documentation

doc/languages-frameworks/index.xml

@@ -24,6 +24,7 @@
  <xi:include href="lua.section.xml" />
  <xi:include href="maven.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" />

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.