Skip to content

Home

Jump to bottom Edit New page
chmaha edited this page Nov 21, 2024 · 109 revisions

Welcome to the reapack-index wiki! reapack-index is a package indexer for git-based ReaPack repositories. This software is intended to be used by repository owners and maintainers.

This page explains how to install reapack-index and how to use it to create and update your own repository (index file). The documentation for the metadata header format is available in Packaging Documentation.

ReaPack repositories are made of a single XML index file describing its contents. See Index Format on ReaPack's wiki to learn more.

Summary

  1. Installation
  2. Getting started
  3. Updating the index
  4. Testing a package header
  5. Filling the about section
  6. Resources

Installation

  • On macOS:
    1. Install Homebrew (recommended)
    2. Run brew install ruby to install a newer version of Ruby (v2.4+ is required)
    3. Run brew install cmake pkg-config to install required build dependencies
    4. Run gem install reapack-index
  • On Linux or other Unix systems:
    1. Install Ruby v2.4+ with development headers, cmake, pkg-config and openSSL development package
    2. Run gem install reapack-index
  • On Windows:
    1. Install Ruby 2.4+ through RubyInstaller for Windows (install MSYS2 when prompted, option 1,3)
    2. Install CMake (necessary only to build rugged, the Ruby bindings to libgit2)
    3. Run gem install reapack-index from a command prompt

To update reapack-index installed at your machine, run: gem update reapack-index from a command prompt. This may take a while.

Getting started

Start by opening a command prompt:

  • On macOS: Open Terminal.app from the directory /Applications/Utilities/
  • On Windows: Type "cmd.exe" in the start menu and hit the Return key

Then navigate to the location of your local git repository with the following command:

# macOS:
cd /path/to/your/repository

# Windows:
cd C:\Path\To\Your\Repository

Let's start by testing your repository to see if it can be indexed as it is:

reapack-index --check

If everything goes well, you should see something similar to this with each dot representing a valid package:

................................................................................

Finished checks for 80 packages with 0 failures

If you see a different output containg 'F' and errors, fix them and recheck before continuing (see also Packaging Documentation).

Now let's create the index file which will tell ReaPack what is available in the repository. Commit any modified files in git then run this command:

reapack-index --name 'FooBar Scripts'

All done! Your repository should now be ready to be imported into ReaPack using the raw url to the index.xml file (typically https://github.com/USER/REPO/raw/master/index.xml for repositories hosted on GitHub).

See Packaging Documentation for complete instructions on how to creating packages.

Updating the index

To scan new commits and applies the changes to the index, run reapack-index without any argument:

reapack-index

If you wish to alter a released version (eg. to fix a mistake), commit your changes then run:

reapack-index --amend

It is also possible to re-index a commit or a file that was scanned previously:

reapack-index --scan 7a4abf8
reapack-index --scan 7a4abf8 --amend
reapack-index --scan 'MIDI Editor/Some File.lua'

Testing a package header

It is possible to see the output of reapack-index's header parser with this command:

ruby -r metaheader -r pp -e 'pp MetaHeader.parse(ARGF).to_h' /path/to/your/repository/packageFile

Filling the about section

ReaPack can display a formatted description of your repository and additional links.
This uses the RTF format internally, which can be opened and edited in WYSIWYG software like Microsoft Office or Textedit.app. Many other formats (such as Markdown) are supported if Pandoc is installed on your computer.

To put the content of README.md in the about dialog, run this command:

reapack-index --about=README.md

The generated RTF file can be exported and opened it with a specialized editor:

reapack-index --dump-about > about_dumped.rtf
# open about_dumped.rtf in your favorite editor and make edits
# then after saving your changes, import it back:
reapack-index --about=about_dumped.rtf
# about_dumped.rtf can be deleted at this point

Adding or editing links:

reapack-index --link 'http://example.com'
reapack-index --link 'Link Label=http://example.com/page.html'
reapack-index --donation-link 'http://example.com'

Removing links:

reapack-index --link '-http://example.com'
reapack-index --donation-link '-Link Label'

Resources

Add a custom footer
Add a custom sidebar
Clone this wiki locally