Addons/Developers Guide

Addons are created and tested in J under ~addons folder on local machine. When ready to share, an addon is checked into addons SVN folder, the build process creates a distributable archive placed into download location, which is recognised by the Package Manager and installed on user machines.

1. Addon Folders
2. Manifest
   1. Platforms
   2. Versioning
3. misc Folders
4. Subversion
5. Build System
6. Documentation
7. Shortnames
8. Labs
9. Branding
10. Future Use

Addon Folders

Addons are in two-level folders on the disk installation of J System under ~addons, e.g. ~addons/web/cgi.

Top level folders are referred to as categories defined under Addons/Config/Categories, which also contains rules on category and folder naming and choosing categories for new addons.

For bottom level folders, i.e. addons themselves, any name can be used, except "misc", which is treated specially.

A multi file addon occupies a separate folder under category, which serves as the addon identity, with other attributes, such as version and platforms described in a manifest file. Single file addons are placed into misc folder under respective category, which is simply a collection of scripts treated as a special addon. See section on misc folder below.

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

Manifest

Source folders other than misc should have a script manifest.ijs that describes the addon. The presence of such a script is required for building the addon. If not present, or if present and VERSION is empty, the folder is ignored by the server build task; this might be useful when first creating an addon.

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=: 'value' 
FILES=: 0 : 0
fftw.ijs
fftw.ijt
)

Nouns CAPTION, 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.

Example:

NB. manifest for FFTW
CAPTION=: 'Fastest Fourier Transform in the West'
VERSION=: '1.0.2'
PLATFORMS=: 'win'      NB. only windows zip is built
LABCATEGORY=: 'Math'
FILES=: 0 : 0
fftw.ijs
fftw.ijt
jfftw.dll
doc/readme.txt
)
RELEASE=: 'j601'
DEPENDS=: 0 : 0
image/platimg
web/cgi 0.1.2
xml/sax 0.2
)
DESCRIPTION=: 0 : 0
FFTW (Fastest Fourier Transform in the West) is a collection of fast C routines for computing the Discrete Fourier Transform in one or more dimensions. It includes complex, real, and parallel transforms, and can handle arbitrary array sizes efficiently. The FFTW Add-On consists of a DLL incorporating the FFTW routines, plus supporting J scripts and labs. FFTW and the FFTW package are distributed under the terms of the GNU General Public License. For more information on GNU, see the GNU web page.
)

Platforms

PLATFORMS has the following naming convention:

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

Normally archives are built for Windows and Linux, with text files using CRLF or LF separators respectively. The Windows system is used by default for the Pocket PC, and the Linux system for the Mac.

By default, when PLATFORMS is absent or empty (''), archives are built for Windows and Linux, with text files using CRLF or LF separators respectively. The Windows system is used by default for the Pocket PC, and the Linux system for Darwin.

Default empty PLATFORMS is suitable for platform-neutral addons. 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'.

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.

Builds are always made from the tags branch of the addons repository, and the tags are created if necessary. A change in major or minor version in the trunk will trigger the creation of a new tag subfolder and a new build, while a change in the build number will trigger a replacement build.

Once the tag subfolders are created, the developer can checkout and update those tags independently of the trunk or other such tags, increasing their build numbers thus creating patches for historic versions.

For more information, see Addons/Versioning.

misc Folders

A misc subfolder, i.e. a folder of the form category/misc, treated as a single addon that is just a collection of scripts. No manifest file is required, and it will be ignored if given. On any change in the scripts, or contents of the scripts, the addon will be rebuilt, with an automatic increment to the version number.

Each script should have the short name of the script on the first line, and a caption on the second line. The remaining comment lines are not used by the installer, but would typically contain a version and a description. For example:

NB. convert/misc/base64
NB. convert to and from base64 representation
NB. version: 1.0.0
NB. main functions:
NB.   tobase64          to base64 representation
NB.   frombase64        from base64 representation
...

Subversion

In order to preserve and share an addon, it is placed under SVN.
For SVN usage and repository location, see Subversion.
For details of addons SVN, naming conventions, trunk and tags, see Addons/Versioning.

Build System

A server task builds the addons from the SVN source. The build also updates the Wiki JAL Catalog page for respective J version, e.g. JAL/j601, and the JAL/Build_Log page.

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

math_fftw_1.0.2_win.zip
math_fftw_1.0.2_win64.zip
math_fftw_1.0.2_linux.tar.gz

Archives are placed under the distribution folder for respective J version. For example, http://www.jsoftware.com/jal/j601/addons.

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.

Links to possible addon pages are located on JAL version pages such as JAL/j601, whose list is extended as new J versions become available.

A list of actual existing pages is on the Addons page. (This page also has a number of non-addon child pages for system documentation and configuration, which distinuish themselves from addons by following Wiki naming starting with Capital case.)

Curretly the format is free form, use existing pages as examples (arc/zip, data/sqlite, programming/monthview, etc). Besides general documentation, include summary to load and call, and typical usage examples. Link to JAL download and SVN as described for InterWiki at EditingGuidelines. There may be a template in the future.

Shortnames

Names containing path delimiters, with no trailing .ijs, are treated as addons shortnames by load and require. For example, the following are equivalent:

   load 'web/cgi'
   load '~addons/web/cgi/cgi.ijs'

Also, the following are equivalent:

   load 'web/misc/https'
   load '~addons/web/misc/https.ijs'

Labs

The ADDLABS noun in file addons/config/config.ijs is read for addon labs. This file is normally updated by the Run|Package Manager utility, but can be updated manually. It is a list of labs followed by their categories, for example:

NB. additional labs
ADDLABS=: 0 : 0
excel/tara/tara.ijt Excel
math/fftw/fftw.ijt Math
web/cgi/cgihow.ijt Web
...
)

Branding

References to JAL can be marked with a JAL icon featuring a soaring jet with letters "JAL" inclined by its force.

Future Use

• This section is for future use, which may be recalled without notice. The use of Project Manager to build a project on the server is not yet supported.

Using Project Manager

An addon source directory can contain a normal Project Manager project. If so, it will be built on the server to create the downloadable addon. The source should reference standard scripts and other addons, rather than include them directly.

It is useful, but not essential, to define a J folder name Addons that points to the top level directory of your local copy of the addon source. For example, the project file might be:
   jpath '~Addons/web/cgi/cgi.ijp'

The target directory should be the appropriate addons subdirectory, e.g.
   jpath '~addons/web/cgi'

It should be possible to build the addon on the local machine with a standard J installation.

Note: at some stage, Project Manager should be extended to give additional support for addons, for example, a dialog to update the manifest.