Skip to content

Latest commit

 

History

History
189 lines (151 loc) · 5.71 KB

development.md

File metadata and controls

189 lines (151 loc) · 5.71 KB
Raw

Octave Packages development guide

Quick info

Your package management tool can read the entire package index at once as Octave array of struct into the variable __pkg__ using the command:

function __pkg__ = package_index_resolve ()
  data = urlread ("https://gnu-octave.github.io/packages/packages/")(6:end);
  data = strrep (data, ">",  ">");
  data = strrep (data, "&lt;",  "<");
  data = strrep (data, "&amp;", "&");
  data = strrep (data, "&#39;", "'");
  eval (data);
endfunction

Note, the assignment to the returned variable __pkg__ is done within eval and depending on your internet connection, this is an inexpensive operation, thus a caching strategy is probably not necessary.

>> tic; __pkg__ = package_index_resolve (); toc
Elapsed time is 0.365517 seconds.

Detailed information for writing a package management tool

This package index is build from the perspective of a package management tool written in the GNU Octave language.

Read the package index

Using the routine package_index_resolve() as describe in the quick info above, an Octave array of struct __pkg__ indexed by the package names is returned.

To get the first three packages names, for example, type:

>> fieldnames (__pkg__)(1:3)
ans =
{
  [1,1] = arduino
  [2,1] = audio
  [3,1] = bim
}

Extract package details

After reading the package index to the variable __pkg__ as shown above, one can obtain more detailed information about individual packages. The following code shows all available struct fields for pkg-example:

>> fieldnames (__pkg__.("pkg-example"))
ans =
{
  [1,1] = name
  [2,1] = description
  [3,1] = icon
  [4,1] = links
  [5,1] = maintainers
  [6,1] = versions
}

Similar, one can see all details of the latest pkg-example version:

>> __pkg__.("pkg-example").versions(1)
ans =

  scalar structure containing the fields:

    id = 1.0.0
    date = 2020-09-02
    sha256 = 6b7e4b6bef5a681cb8026af55c401cee139b088480f0da60143e02ec8880cb51
    url = https://github.com/gnu-octave/pkg-example/archive/1.0.0.tar.gz
    depends =

      scalar structure containing the fields:

        name = octave (>= 4.2.0)

Compatibility with Octave's pkg tool

In case you want to stay compatible with Octaves builtin package management tool pkg you should care about the following default settings:

  • pkg prefix: directory new packages are installed to.

    >> pkg prefix -global
Installation prefix:             /usr/share/octave/packages
Architecture dependent prefix:   /usr/lib/octave/packages

>> pkg prefix -local
Installation prefix:             /home/username/octave
Architecture dependent prefix:   /home/username/octave

  • pkg local_list (default: /home/username/.octave_packages):

  • pkg global_list (default: /usr/share/octave/octave_packages): File listing installed local or global packages.

    The file is simply created by saving an array of struct using Octave's default save command:

    >> load /home/username/.octave_packages
>> local_packages
local_packages =
{
  [1,1] =

    scalar structure containing the fields:

      name = pkg-example
      version = 1.0.0
      date = 2020-09-02
      author = Kai T. Ohlhus <k.ohlhus@gmail.com>
      maintainer = Kai T. Ohlhus <k.ohlhus@gmail.com>
      title = Minimal example package to demonstrate the Octave package extensions.
      description = Minimal example package to demonstrate the Octave package  extensions.  It shows how to organize Octave, C/C++, and FORTRAN code within  a package and to properly compile it.
      depends =
      dir = /home/siko1056/octave/pkg-example-1.0.0
      archprefix = /home/siko1056/octave/pkg-example-1.0.0

}

Developing the websites of GNU Octave packages

Two important links first:

  1. Development repository: https://github.com/gnu-octave/packages/
  2. Deployment URL: https://gnu-octave.github.io/packages/

In this section some hints for developing this index from the server site are given.

  • The whole index is a static website generated by bundler and Jekyll and hosted on GitHub pages.

  • There is no limitation to host the generated static pages on any other arbitrary webserver.

  • Build the static websites with bundler/Jekyll

    git clone https://github.com/gnu-octave/packages
cd packages
bundle install
bundle exec jekyll build

    and copy the content of the generated _site directory to the webserver of your choice.

  • Basically, there are two layouts. One for the package index _layouts/package_index.html (used by assets/index.md) and one for the individual packages pages _layouts/package.html (used by all .md files in the package directory).

  • The index read by package_index_resolve() is generated from packages/index.md.

  • The package index page uses following JavaScript/CSS frameworks:

    • FontAwesome for awesome fonts.
    • bootstrap: for simply good-looking design.
    • DataTables for a dynamic search feature. Configuration at https://datatables.net/download/index: 
      Styling framework
  [x] DataTables
Packages
  [x] DataTables
Extensions
  [x] Scroller
Download method: CDN
  [x] Minify
  [x] Concatenate
      If no JavaScript is available, a static HTML table is displayed.
    • jQuery: needed by bootstrap and DataTables.

  • The individual package pages are generated by filling the layout with the metadata given in YAML format, as described in CONTRIBUTING.md.