Addons/Developers Guide

From J Wiki
Jump to: navigation, search
User Guide | Installation | Development | Categories | Git | Build Log

Overview

The addons packages are saved 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.

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.

Manifest

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

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. 'j805', or empty if all

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

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

RELEASE=: 'j805'

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. j805. 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.

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.