nixpkgs-suyu/doc/languages-frameworks/octave.section.md

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