This is the MSXHub packages repository containing the package definitions for all the software available in MSXHub.

A package in MSXHub is just a YAML file with metadata and instructions on how to generate it. Once approved it will be automatically uploaded to MSXHub.

To build and test a package in your own PC some software is required:

• GNU make
• Docker

A MSXHub package is just a YAML file in the packages/ directory. This file contains the package information and the script required to build it.

The file has to be the same as the package name (in uppercase) plus the yaml extension in lowercase.

A package file contains several mandatory fields defining the package itself.

The name of the package to be created.

Restrictions:

• Capital letters
• No longer than 8 characters

The version of the software being packaged.

Restrictions:

• No longer than 16 characters
• Cannot contain the following characters -, :

Release number of the package. It starts with 1 and it's increased every time a new package with the same version number is created. Every time a new version is package, the release number should be back to 1.

Restrictions:

• Must be an integer number

Short description of the package.

Restrictions:

• No longer than 80 characters

Name of the author or authors of the packaged software. Can be a personal name or a company name.

Restrictions:

• No longer than 128 characters

Name of the author of the package itself. That's you! :)

Restrictions:

• No longer than 128 characters

License of the packaged software.

Restrictions:

• Should be in the list defined in msxhub.com/list_licenses

Please, open an issue if the required license is not in the list.

Category of the packaged software.

Restrictions:

• Should be in the list defined in msxhub.com/categories

Please, open an issue if the required category is not in the list.

Minimum system required to run the software.

Restrictions:

• Should be in the list defined in msxhub.com/list_systems

Please, open an issue if the required system is not in the list.

List of required extensions to run the software.

Restrictions:

• Should be in the list defined in msxhub.com/list_requirements

Please, open an issue if the required extension is not in the list.

Web URL where to find more information of the packaged software. In some cases, the packaged software doesn't have an official website. Just use a relevant URL in such cases.

Restrictions:

• No longer than 256 characters

Long description of the packaged software. Markdown format can be used to add style to the text.

Default directory where to install the packaged software in MSX-DOS format. Do not specify the drive letter as it will be automatically added by MSXHub.

Restrictions:

• Should start with \

Examples:

• \VI will be installed in A:\VI
• \MSXDOS2T will be installed in A:\MSXDOS2T

Before building the package, the required files need to be downloaded. This list field define all the files required to build the package and the URLs where to get it them.

Use the following format:

files:
  - vi.zip: 'https://github.com/fr3nd/msx-vi/releases/download/v%VERSION%/vi.zip'

First define the name of the file and then the URL where to fetch it.

The string %VERSION% will be automatically replaced by the content defined in the field version.

GNU Bash script to generate the package.

The script needs to have all the commands to uncompress the downloaded file and place all the required files in the package/ directory.

In some cases, BAT or BAS files need to be created. In such cases, here documents may be used. Do not forget to convert the resulting file to DOS format after it's been created:

cat > package/RUNME.BAT << EOF
basic LOADER.BAS
EOF
unix2dos package/RUNME.BAT

Requirements:

• The first line should be mkdir -p package to create the directory where all the files will be stored.

Example:

build: |
  mkdir -p package/
  unzip alien8.zip
  mv Alien8msx2.rom package/alien8.rom
  cat > package/alien8.bat << EOF
  srom alien8.rom
  EOF
  unix2dos package/alien8.bat

Simple changelog of the package in Markdown format.

Example:

changelog: |
  - 1.0.0-1 2018-09-02
    - First release

Once the PACKAGE.yaml file has been created, run make PACKAGE to build it in your own computer. GNU Make and Docker are required.

• make PACKAGE (replace PACKAGE by your package name in capital letters): Test and build the specified package.
• make clean: Clean all generated files.
• make emulator: Run OpenMSX with the generated packages under the \FILES directory for testing.