# 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://gnu-octave.github.io/packages/) 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
```

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

```ShellSession
$ nix-env -f. -iA 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`.