Addons/Developers Guide

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

Addons are created and tested in J under the ~addons subfolder of a J installation.

When ready, an addon is committed to the addons SVN. The manifest version is checked, and if this is a new addon or a new version of the addon, then a distributable archive is built and made available on the J server, for download by the Package Manager.

Addon Folders

Addons are in two-level folders under ~addons, e.g. ~addons/web/gethttp.

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 a category, with attributes such as version and platforms described in a manifest file.

Single file addons can be placed into the category misc folder, 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 or unchanged from before, 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.

CAPTION one-line brief description
VERSION version number in the form major.minor.build, e.g. 1.0.2
FILES list of files to be included, with any local paths, e.g. doc/readme.txt
FILESxxx additional lists specific to platform xxx, e.g. FILESLINUX64
DEPENDS other addons, with optional version
DESCRIPTION description
PLATFORMS list of target platforms, default win (windows) and linux, e.g. 'win darwin'
RELEASE list of target J releases for automatic tagging, e.g. 'j504 j601'
LABCATEGORY category used for any labs. The default is based on category, e.g. 'Web' for web/cgi

Example

CAPTION=: 'FFTW'

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.

FFTW is available under Windows, Mac and Linux.
)

VERSION=: '1.1.16'

RELEASE=: 'j802 j803 j804 j805 j806 j807'

LABCATEGORY=: 'Math'

PLATFORMS=: ''

FILES=: 0 : 0
fftw.ijs
fftw.ijt
gpl.htm
philosophical-gnu-sm.jpg
)

FILESWIN=: 0 : 0
libfftw3-3.dll
)

FILESWIN64=: 0 : 0
libfftw3-3_64.dll
)

FILESDARWIN=: 0 : 0
libfftw3.3.dylib
)

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

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

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/Build Log page.

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

math_fftw_1.1.16_android.tar.gz
math_fftw_1.1.16_darwin.tar.gz
math_fftw_1.1.16_linux.tar.gz
math_fftw_1.1.16_win64.zip

Archives are placed under the distribution folder for respective J version. For example, [1].

Test Scripts

Including one or more test scripts with your addon:

  • helps prevent the introduction of bugs during development
  • makes it easier for new developers to contribute changes without fear of screwing up
  • provide valuable example data and usage to users

It is recommended that a test script be included with every addon published in the J Application Library. The test script should be run and complete successfully before any update is committed to the JAL SVN repository.

See Addons/Test scripts and Addons/general/unittest for suggested approaches.

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.

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/gethttp'
   load '~addons/web/gethttp/gethttp.ijs'

Also, the following are equivalent:

   load 'general/misc/numeric'
   load '~addons/general/misc/numeric.ijs'

Branding

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

Jal12.png Jal14.png Jal24.png Jal36.png
48×12 48×14 100×24 140×36