fedora-llm-docs/Documents/pages/Octave.txt

= Octave Packaging Guidelines

== What is Octave?

The definition from https://www.octave.org/[website] says:

_"GNU Octave is a high-level language, primarily intended for numerical computations. It provides a convenient command line interface for solving linear and nonlinear problems numerically, and for performing other numerical experiments using a language that is mostly compatible with Matlab. It may also be used as a batch-oriented language."_

If you are interested in packaging Octave packages, you should check here for upstream sources:

* https://octave.sourceforge.io/[The Octave Forge website]

== RPM macros

The following macros are defined in /etc/rpm/macros.octave in the octave 3.4.0 (Fedora 15+) package for help in packaging:

....
# Octave binary API provided
%octave_api %(octave-config -p API_VERSION || echo 0)}

# Octave Package Directories
%octshareprefix %{_datadir}/octave
%octprefix %{octshareprefix}/packages
%octarchprefix %{_libdir}/octave/packages

%octpkgdir %{octshareprefix}/%{octpkg}-%{version}
%octpkglibdir %{octarchprefix}/%{octpkg}-%{version}

# Run an octave command - quietly with no startup files
%octave_cmd()

# Build Source into a package tar file in a temporary location
%octave_pkg_build

# Install a package.  We use the octave pkg install command to install the
# built package into the buildroot.  We also put a note to prevent the root
# user from removing the package with the octave pkg uninstall command
%octave_pkg_install 

# preun script - we need to remove our uninstall protection and perhaps
# run the package's own uninstall script.
%octave_pkg_preun
....

== Octave packaging tips

=== Naming of Octave packages

Packages of Octave packages have their own naming scheme. They should take into account the upstream name of the package. This makes a package name format of `+octave-$NAME+`. When in doubt, use the name of the module that you type to import it in octave.

'''Examples: '''

....
octave-java (Octave package named java)
octave-gsl (Octave package named gsl)
....

Limitations in the pkg function of octave (pkg.m) means that versioning of octave packages requires that the package version must have a MAJOR.MINOR.MICRO format. Failing to use this format results in octave not recognising binary package components in %prefix/libexec.

=== Updating the octave package database

Octave maintains a list of installed packages in /usr/share/octave/octave_packages that needs to be updated on package install and removal. This file is in an octave plain-text format.

The contents of the /usr/share/octave/packages/ directory are scanned for the following files when performing a pkg('rebuild') from within octave.

* /usr/share/octave/packages/_NAMEOFPACKAGE_/packinfo/COPYING
* /usr/share/octave/packages/_NAMEOFPACKAGE_/packinfo/DESCRIPTION

If these files are not present in any given _NAMEOFPACKAGE_ directory, then octave will silently skip the folder and fail to index it correctly.

Octave will use the contents of octave_packages to modify its path at startup, allowing octave to find plugins.

=== Documentation files

All package files are installed into the octave directories.

== Spec Templates for Octave packages

There are two types of Octave packages: arch-specific and noarch.

=== Arch specific Octave spec template

....
%global octpkg image
# Exclude .oct files from provides
%global __provides_exclude_from ^%{octpkglibdir}/.*\\.oct$

Name:           octave-%{octpkg}
Version:        1.0.13
Release:        1%{?dist}
Summary:        Image processing for Octave
Group:          Applications/Engineering
License:        GPLv2+
URL:            https://octave.sourceforge.io/image/
Source:         https://downloads.sourceforge.net/octave/%{octpkg}-%{version}.tar.gz

BuildRequires:  octave-devel

Requires:       octave(api) = %{octave_api}
Requires(post): octave
Requires(postun): octave

%description
The Octave-forge Image package provides functions for processing images. The
package also provides functions for feature extraction, image statistics,
spatial and geometric transformations, morphological operations, linear
filtering, and much more. 


%prep
%setup -q -n %{octpkg}-%{version}


%build
%octave_pkg_build


%install
%octave_pkg_install


%post
%octave_cmd pkg rebuild

%preun
%octave_pkg_preun

%postun
%octave_cmd pkg rebuild

%files
%{octpkglibdir}
%dir %{octpkgdir}
%{octpkgdir}/*.m
%doc %{octpkgdir}/doc-cache
%{octpkgdir}/packinfo


%changelog
* Sat Feb 12 2011 Orion Poplawski <orion@cora.nwra.com> 1.0.13-1
- Initial Fedora package
....

=== Noarch Octave spec template

....
%global octpkg actuarial

Name:           octave-%{octpkg}
Version:        1.1.0
Release:        1%{?dist}
Summary:        Actuarial functions for Octave
Group:          Applications/Engineering
License:        GPLv2+
URL:            https://octave.sourceforge.io
Source:         https://downloads.sourceforge.net/octave/%{octpkg}-%{version}.tar.gz
BuildArch:      noarch

BuildRequires:  octave-devel

Requires:       octave
Requires(post): octave
Requires(postun): octave

%description
Actuarial functions for Casualty and Property lines.


%prep
%setup -q -n %{octpkg}-%{version}


%build
%octave_pkg_build


%install
%octave_pkg_install


%post
%octave_cmd pkg rebuild

%preun
%octave_pkg_preun

%postun
%octave_cmd pkg rebuild

%files
%dir %{octpkgdir}
%{octpkgdir}/*.m
%doc %{octpkgdir}/doc-cache
%{octpkgdir}/packinfo


%changelog
* Sat Feb 12 2011 Orion Poplawski <orion@cora.nwra.com> 1.1.0-1
- Initial Fedora package
....

=== Summary of differences between arch-specific and noarch octave packages

* Noarch packages set `+BuildArch: noarch+`
* Don't require a specific API version
* Noarch packages don't install anything into %\{octpkglibdir}

=== Obsoletes notes

Packages that used to be in the octave-forge package need to have the Obsoletes line above. Packages that were not do not.