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.
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.
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
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 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.
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.
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 ...
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, .
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.
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.
Besides general documentation, include a usage summary and typical examples. Link to JAL download and SVN as described for InterWiki at EditingGuidelines.
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'
References to JAL can be marked with a JAL icon featuring a soaring jet with letters "JAL" inclined by its force.