Addons/Developers Guide

Overview

Addons packages are created in github repositories, and installed in the ~addons subfolder of a J installation.

The folders are in two levels, with the top level folder being the addon category, see Addons/Config/Categories. Any name can be used for the bottom level folders. The repo should be named in the form: top_bottom, e.g. math_lapack.

To avoid problems sharing code between different platforms, all folders and file names should be in lower case and should not contain spaces, punctuation and non-ascii characters.

GitHub

A GitHub account is needed.

The addon can be either on a personal GitHub account or on the jsoftware account.

If you use the jsoftware page, we will create the addon and give you write access to it. Otherwise create the addon on your personal page. Either way is fine, but for addons that are primarily the work of a single developer, the personal page is recommended.

Once your addon is on GitHub, you should test that it has the correct format for the Package Manager to install it. To do this, run the Pacman code to install directly from GitHub .

When you know that your addon has the proper format to satisfy Pacman, contact jal @ jsoftware.com and ask to have it added to the list of addons available for download. Once it has been added, updates to the addon manifest will trigger rebuilding the addon. Remember, it is not enough to update a file - you must always increment the version number in the manifest to trigger a rebuild.

Manifest

An addon is described by its manifest, and a valid manifest is required for installation.

The manifest is a normal j script named manifest.ijs in the addon's root directory.

The manifest script is a collection of attributes defined as relevant global nouns. Only valid noun definitions are permitted in the script - these must be global assignments of a text string, or 0 : 0 expression, for example:

CAPTION=: 'FFTW'

FILES=: 0 : 0
fftw.ijs
fftw.ijt
)

Nouns CAPTION, FOLDER, VERSION and a FILES list are required. Other entries in the script are optional, and are given defaults if omitted. If noun DEPENDS is given, the required dependencies must already exist.

CAPTION	one-line brief description
VERSION	version number in the form major.minor.build, e.g. 1.0.2.
FOLDER	addon folder, e.g. api/expat
FILES	list of files or directories to be included, with any local paths, e.g. doc/readme.txt. Directories should end with a /, e.g. doc/
FILESxxx	additional lists specific to platform xxx, e.g. FILESLINUX64
DEPENDS	other required addons
DESCRIPTION	description
PLATFORMS	list of target platforms, default win (windows) and linux, e.g. 'win darwin'
RELEASE	earliest J release supported, e.g. 'j901', optionally followed by latest release supported, or empty for all releases

Example

CAPTION=: 'Sqlite enhanced API for J'

DESCRIPTION=: 0 : 0
Sqlite allows direct access to sqlite databases.

See wiki page: code.jsoftware.com/wiki/Addons/data/sqlite/Overview
)

VERSION=: '1.0.29'

FILES=: 0 : 0
sqlite.ijs
sqlitez.ijs
sandp.ijs
db/
lib/
)

RELEASE=: 'j901'

FOLDER=: 'data/sqlite'

Platforms

PLATFORMS has the following naming convention:

win	Windows
linux	Linux
android	Android
darwin	Mac

Any tag can be followed by 32 or 64, e.g. win64 is for 64-bit Windows.

Normally archives are built for all platforms, with text files using CRLF or LF separators as appropriate.

Qualifying PLATFORMS will limit the output to exactly the indicated platforms.

Versioning

VERSION is a list of up to 3 numbers: major, minor, build, given as a dotted string, e.g. '1.0.2'.

For the core addons, a fresh build is trigged only if the version number VERSION is incremented from the previous build. So if you want just to save work in progress in the source, you should not update the version number. Conversely, to kick off a new build when you are ready, increment the version number.

Release

If RELEASE is given, it should be the earliest release supported by the addon, e.g. j901, optionally followed by the last release supported, e.g. j901 j903. For the core addons, if this is incremented, the earlier builds will remain available on the server, but will no longer be updated.

For example, in a beta cycle, addons may be given the beta release number so that any changes would only be seen in a beta system.

The RELEASE values are the major, minor release numbers. They can be given in the new form j9.4 or the old form j904. In the old form, the release number is 100 #. major, minor release (e.g. 904 is 100 #. 9 4).

As of j9.4, the earliest release that is built is j901. Addons for versions of J before j901 are no longer updated.

Build System

A server task builds the core addons from the github source. The build also updates the Wiki JAL/Build Log page.

Output distribution archive names include the category and folder name, version number and target platform. For example,

data_sqlite_1.0.18_android.tar.gz
data_sqlite_1.0.18_linux.tar.gz
data_sqlite_1.0.18_darwin.tar.gz
data_sqlite_1.0.18_win.zip

Archives are on the server, for example at [1].

Documentation

Each addon has a wiki documentation page, named with the same folder name. For example, Addons/math/fftw. (Note: lowercase math/fftw). You can create and update this page like any other wiki page.

A list of actual existing pages is on the Vocabulary/Libraries page.

Currently the format is free form, use existing pages as examples (arc/zip, data/sqlite, programming/monthview, etc).

Besides general documentation, include a usage summary and typical examples. Link to JAL download and SVN as described for InterWiki at EditingGuidelines.