commit a75b1fa5a9df17fe30ad986aef53010400a1888c · pyrox.dev/nixpkgs

doc/languages-frameworks/index.xml

···

       24
       24
        
        <xi:include href="lua.section.xml" />

     

       25
       25
        
        <xi:include href="maven.section.xml" />

     

       26
       26
        
        <xi:include href="ocaml.section.xml" />

     

       27
       27
       +
        <xi:include href="octave.section.xml" />

     

       27
       28
        
        <xi:include href="perl.section.xml" />

     

       28
       29
        
        <xi:include href="php.section.xml" />

     

       29
       30
        
        <xi:include href="python.section.xml" />

+100

doc/languages-frameworks/octave.section.md

···

       1
       1
       +
       # Octave {#sec-octave}

     

       2
       2
       +
       

     

       3
       3
       +
       ## Introduction {#ssec-octave-introduction}

     

       4
       4
       +
       

     

       5
       5
       +
       Octave is a modular scientific programming language and environment.

     

       6
       6
       +
       A majority of the packages supported by Octave from their [website](https://octave.sourceforge.io/packages.php) are packaged in nixpkgs.

     

       7
       7
       +
       

     

       8
       8
       +
       ## Structure {#ssec-octave-structure}

     

       9
       9
       +
       

     

       10
       10
       +
       All Octave add-on packages are available in two ways:

     

       11
       11
       +
       1. Under the top-level `Octave` attribute, `octave.pkgs`.

     

       12
       12
       +
       2. As a top-level attribute, `octavePackages`.

     

       13
       13
       +
       

     

       14
       14
       +
       ## Packaging Octave Packages {#ssec-octave-packaging}

     

       15
       15
       +
       

     

       16
       16
       +
       Nixpkgs provides a function `buildOctavePackage`, a generic package builder function for any Octave package that complies with the Octave's current packaging format.

     

       17
       17
       +
       

     

       18
       18
       +
       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`.

     

       19
       19
       +
       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.

     

       20
       20
       +
       Octave packages are made available through `all-packages.nix` through both the attribute `octavePackages` and `octave.pkgs`.

     

       21
       21
       +
       You can test building an Octave package as follows:

     

       22
       22
       +
       

     

       23
       23
       +
       ```ShellSession

     

       24
       24
       +
       $ nix-build -A octavePackages.symbolic

     

       25
       25
       +
       ```

     

       26
       26
       +
       

     

       27
       27
       +
       When building Octave packages with `nix-build`, the `buildOctavePackage` function adds `octave-octaveVersion` to; the start of the package's name attribute.

     

       28
       28
       +
       

     

       29
       29
       +
       This can be required when installing the package using `nix-env`:

     

       30
       30
       +
       

     

       31
       31
       +
       ```ShellSession

     

       32
       32
       +
       $ nix-env -i octave-6.2.0-symbolic

     

       33
       33
       +
       ```

     

       34
       34
       +
       

     

       35
       35
       +
       Although, you can also install it using the attribute name:

     

       36
       36
       +
       

     

       37
       37
       +
       ```ShellSession

     

       38
       38
       +
       $ nix-env -i -A octavePackages.symbolic

     

       39
       39
       +
       ```

     

       40
       40
       +
       

     

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

     

       42
       42
       +
       

     

       43
       43
       +
       ```ShellSession

     

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

     

       45
       45
       +
       ```

     

       46
       46
       +
       

     

       47
       47
       +
       This will also work in a `shell.nix` file.

     

       48
       48
       +
       

     

       49
       49
       +
       ```nix

     

       50
       50
       +
       { pkgs ? import <nixpkgs> { }}:

     

       51
       51
       +
       

     

       52
       52
       +
       pkgs.mkShell {

     

       53
       53
       +
         nativeBuildInputs = with pkgs; [

     

       54
       54
       +
           (octave.withPackages (opkgs: with opkgs; [ symbolic ]))

     

       55
       55
       +
         ];

     

       56
       56
       +
       }

     

       57
       57
       +
       ```

     

       58
       58
       +
       

     

       59
       59
       +
       ### `buildOctavePackage` Steps {#sssec-buildOctavePackage-steps}

     

       60
       60
       +
       

     

       61
       61
       +
       The `buildOctavePackage` does several things to make sure things work properly.

     

       62
       62
       +
       

     

       63
       63
       +
       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.

     

       64
       64
       +
       2. Skips the configuration step, because the packages are stored as gzipped tarballs, which Octave itself handles directly.

     

       65
       65
       +
       3. Change the hierarchy of the tarball so that only a single directory is at the top-most level of the tarball.

     

       66
       66
       +
       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`.

     

       67
       67
       +
       

     

       68
       68
       +
       `buildOctavePackage` is built on top of `stdenv` in a standard way, allowing most things to be customized.

     

       69
       69
       +
       

     

       70
       70
       +
       ### Handling Dependencies {#sssec-octave-handling-dependencies}

     

       71
       71
       +
       

     

       72
       72
       +
       In Octave packages, there are four sets of dependencies that can be specified:

     

       73
       73
       +
       

     

       74
       74
       +
       `nativeBuildInputs`

     

       75
       75
       +
       : Just like other packages, `nativeBuildInputs` is intended for architecture-dependent build-time-only dependencies.

     

       76
       76
       +
       

     

       77
       77
       +
       `buildInputs`

     

       78
       78
       +
       : Like other packages, `buildInputs` is intended for architecture-independent build-time-only dependencies.

     

       79
       79
       +
       

     

       80
       80
       +
       `propagatedBuildInputs`

     

       81
       81
       +
       : Similar to other packages, `propagatedBuildInputs` is intended for packages that are required for both building and running of the package.

     

       82
       82
       +
       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.

     

       83
       83
       +
       

     

       84
       84
       +
       `requiredOctavePackages`

     

       85
       85
       +
       : 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.

     

       86
       86
       +
       

     

       87
       87
       +
       ### Installing Octave Packages {#sssec-installing-octave-packages}

     

       88
       88
       +
       

     

       89
       89
       +
       By default, the `buildOctavePackage` function does _not_ install the requested package into Octave for use.

     

       90
       90
       +
       The function will only build the requested package.

     

       91
       91
       +
       This is due to Octave maintaining an text-based database about which packages are installed where.

     

       92
       92
       +
       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.

     

       93
       93
       +
       

     

       94
       94
       +
       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.

     

       95
       95
       +
       2. Because of the way `buildEnv` works, all tarballs that are present (which should be all Octave packages to install) should be removed.

     

       96
       96
       +
       3. The path down to the default install location of Octave packages is recreated so that Nix-operated Octave can install the packages.

     

       97
       97
       +
       4. Install the packages into the `$out` environment while writing package entries to the database file.

     

       98
       98
       +
       This database file is unique for each different (according to Nix) environment invocation.

     

       99
       99
       +
       5. Rewrite the Octave-wide startup file to read from the list of packages installed in that particular environment.

     

       100
       100
       +
       6. Wrap any programs that are required by the Octave packages so that they work with all the paths defined within the environment.