depot/third_party/nixpkgs/doc/languages-frameworks/octave.section.md

Octave

Introduction

Octave is a modular scientific programming language and environment. A majority of the packages supported by Octave from their website are packaged in nixpkgs.

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

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 rather than pkgs/all-packages.nix. Each package is defined in their own file in the 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:

$ nix-build -A octavePackages.symbolic

To install it into your user profile, run this command from the root of the repository:

$ nix-env -f. -iA octavePackages.symbolic

You can build Octave with packages by using the withPackages passed-through function.

$ nix-shell -p 'octave.withPackages (ps: with ps; [ symbolic ])'

This will also work in a shell.nix file.

{ pkgs ? import <nixpkgs> { }}:

pkgs.mkShell {
  nativeBuildInputs = with pkgs; [
    (octave.withPackages (opkgs: with opkgs; [ symbolic ]))
  ];
}

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

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 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

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.