Addons/Developers Guide
User Guide | Installation | Development | Categories | Git | Build Log
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.