Skip to content

Packaging Documentation

Jump to bottom Edit New page
Christian Fillion edited this page Nov 1, 2024 · 116 revisions

This indexer uses metadata found at the start of the files to generate a package database for ReaPack.

File Structure

All packages are plain-text files with a metadata header at the top. For scripts, JS effects and language packs, the metadata header must be located above the code and commented in an appropriate way for the programming language used.

Package files must be in at least one subdirectory (the path is translated into the package's category). Package files at the root of the repository are not indexed.

Package type by extension:

  • .lua, .eel, .py: ReaScripts
  • .jsfx: JS effects
  • .ext: Native extensions (all included files must be explicitely defined)
  • .data: Miscellaneous data (installed in REAPER's "Data" directory)
  • .theme: Color themes
  • .ReaperLangPack: Language Packs
  • .www: Web Interfaces
  • .ReaperAutoItem: Automation Items
  • .RPP: Project Templates
  • .RTrackTemplate: Track Templates
  • .txt: MIDI Notes Names

See Examples for examples of typical packages for all types.

Metadata

Two equivalent syntaxes are supported: @tag_name value and tag name: value. The tag names are case insensitive. There cannot be empty lines between tags. The value of some tags can span over multiple lines if the subsequent lines are consistently indented with at least one space or tab character and, if needed, decorated with the same language-specific comment syntax.

@version is the only mandatory tag.

  1. Package Tags
  2. Version Tags

Package Tags

These tags affects an entire package. Changes to any of those tags are applied immediately and may affect released versions.

@about

Sets the documentation for this package in markdown format (using the commonmark spec). Added in v1.1.

Online tool to preview how the contents is rendered: http://try.commonmark.org/.

@about
  # Header Line

  Hello *World*
  [This is a link](https://google.com)

About:
  - Bullet list item 1
  - Bullet list item 2

@description

Changes the display name of this package. Should be similar to the file name for easy access. Please keep the name tidy without author name prefix or the file extension. Use @author for this purpose instead. This tag was added in v1.1.

Aliases: desc, Name, ReaScript Name, JSFX Name, Theme Name and Extension Name

@description Name of the package

ReaScript Name: Name of the package

@donation

Sets donation links for your package. See @link for usage examples. Added in v1.1.

Aliases: donate See also: @link and @screenshot

@link

Sets one or more website links. They are displayed in the about window for your package in ReaPack. Added in v1.1.

Aliases: links and website See also: @donation and @screenshot

@links
  Forum Thread http://forum.cockos.com/showthread.php?t=169127
  GitHub repository https://github.com/cfillion/reapack-index

Link: http://unlabelled/link

@noindex

Disable indexing for this file. Use this in files that have a file type that is normally considered as a package (see here) but should not be distributed alone (such as a library ReaScript file).

@noindex

NoIndex: true

@screenshot

Sets one or more screenshot links. See @link for usage examples. Added in v1.1.

Alias: screenshots See also: @donation and @link

@version

The current version of the package. This tag is mandatory. The value must contain at least one digit. Add letters to create a pre-release. The separator can be any non-alphanumerical character.

@version 1.0
@version 1.2pre3

Version: 0.2015-12-25

Note: ReaPack versions are not decimal numbers. See this post for more details.

Version Tags

These tags are specific to the current version of the package (see @version). If you are running your own repository, note that by default reapack-index ignores changes made to these tags post-release unless the --amend option is used.

@author

@author cfillion

Author: Christian Fillion

@changelog

Sets the changelog for the current version. The changelogs of previous versions are preserved.

@changelog
  Documented the metadata syntax
  Added support for deleted scripts

Changelog:
  Added an alternate syntax for metadata tags

Note: there is a deprecated type you may see in some scripts. Please do not use as it may be removed at any time.

--[[
 * Changelog:
 * v0.40 (2020-05-18)
   + Potential fix for OSX tap thingy
--]]

@metapackage

Removes the current file from the package's default file list. This is enabled by default for data packages, themes and extensions.

@metapackage

MetaPackage: true

Note: @metapackage false (the default value for scripts/jsfx) implicitly adds the current file to the file list with the main option even if omitted from the @provides tag.

@provides

Manage the files included in the package and their options. Wildcards (globbing) are supported. Each line can optionally have a download url pattern, a target file name and a space-separated list of options between brackets.

ReaPack packages have exclusive ownership over the files they install. reapack-index enforces this exclusivity rule to ensure all packages in the repository may be successfully installed at the same time. Each package must provide a unique set of target file names (actual files on the source repository may overlap).

@provides
  Images/background.png
  Images/fader_*.png

Provides: [data] unicode.dat

@provides
  [windows] reaper_extension.dll http://mysite.com/download/$version/$path
  [darwin jsfx] Ultimate Limiter.jsfx
  Original File.lua > New Directory/Target File.lua
  File Name.conf > New Directory/

Platform options:

  • darwin: All versions of macOS
  • darwin32: macOS x86 32-bit
  • darwin64: macOS x86 64-bit
  • darwin-arm64: macOS ARM 64-bit (added in v1.2.3/ReaPack v1.2.3.1)
  • linux: All versions of Linux
  • linux32: Linux x86 32-bit
  • linux64: Linux x86 64-bit
  • linux-armv7l: Linux ARM 32-bit (added in v1.2.3)
  • linux-aarch64: Linux ARM 64-bit (added in v1.2.3)
  • windows: All versions of Windows
  • win32: Windows x86 32-bit
  • win64: Windows x86 64-bit
  • windows-arm64ec: Windows ARM 64-bit Emulation Compatible (added in v1.2.5)

Type options (overrides the package type):

  • script, lua, eel, py
  • effect, jsfx
  • extension, ext
  • data
  • theme
  • langpack, reaperlangpack
  • webinterface, www
  • projecttpl, rpp
  • tracktpl, rtracktemplate
  • midinotesnames, txt
  • autoitem, reaperautoitem

Action List options (script files only):

  • main: Add this file to the Action List and auto-detect the section from the package's top-level directory name (currently only MIDI Editor is detected). This is the default for the package file itself.
  • main=comma-separated,list: Set in which section(s) the script should be registered in. Possible values are main, midi_editor, midi_inlineeditor, midi_eventlisteditor and mediaexplorer.
  • nomain: Do not add to the Action List. This is the default for additional files.

The following variables are interpolated if found in the URL pattern:

  • $path: The path of the file relative to the repository
  • $commit: The hash of the commit being indexed or "master" if unavailable
  • $version: The version of the package being indexed
  • $package: The package being indexed (path relative to the repository)

Settings for the current file can be set either by using its file name or a dot:

-- this is in a package file named `hello.lua`
-- @provides [nomain] hello.lua

-- @provides [nomain] .
Add a custom footer
Add a custom sidebar
Clone this wiki locally