meson/docs/markdown/Adding-new-projects-to-wrapdb.md

Adding new projects to WrapDB

How it works

New wraps must be submitted as a working subproject to the wrapdb repository.

There are two types of wraps on WrapDB - regular wraps and wraps with Meson build definition patches.

Wraps with Meson build definition patches work in much the same way as Debian: we take the unaltered upstream source package and add a new build system to it as a patch. These build systems are stored as a subdirectory of subprojects/packagefiles/. They only contain build definition files. You may also think of them as an overlay to upstream source.

Wraps without Meson build definition patches only contain the wrap metadata describing how to fetch the project

Whenever a new release is pushed into the wrapdb, a new tag is generated with an incremented version number, and a new release is added to the wrapdb API listing. All the old releases remain unaltered. New commits are always done via GitHub merge requests and must be reviewed by someone other than the submitter.

Note that your Git repo with wrap must not contain the subdirectory of the source release. That gets added automatically by the service. You also must not commit any source code from the original tarball into the wrap repository.

Choosing the wrap name

Wrapped subprojects are used much like external dependencies. Thus they should have the same name as the upstream projects.

NOTE: Wrap names must fully match this regexp: [a-z0-9._]+.

If the project provides a pkg-config file, then the wrap name should be the same as the pkg-config name. Usually this is the name of the project, such as libpng. Sometimes it is slightly different, however. As an example the libogg project's chosen pkg-config name is ogg instead of libogg, which is the reason why the wrap is named plain ogg.

If there is no pkg-config file, the name the project uses/promotes should be used, lowercase only (Catch2 -> catch2).

If the project name is too generic or ambiguous (e.g. benchmark), consider using organization-project naming format (e.g. google-benchmark).

How to contribute a new wrap

If the project already uses Meson build system, then only a wrap file project.wrap should be provided. In other case a Meson build definition patch - a set of meson.build files - should also be provided.

Creating the wrap contents

New release branches require a project.wrap file, so create one if needed.

${EDITOR} upstream.wrap

The file format is simple, see any existing wrapdb subproject for the content. The checksum is SHA-256 and can be calculated with the following command on most unix-like operating systems:

sha256sum path/to/libfoo-1.0.0.tar.gz

Under macOS the command is the following:

shasum -a 256 path/to/libfoo-1.0.0.tar.gz

Next you need to add the entries that define what dependencies the current project provides. This is important, as it is what makes Meson's automatic dependency resolver work. It is done by adding a provide entry at the end of the upstream.wrap file. Using the Ogg library as an example, this is what it would look like:

[provide]
ogg = ogg_dep

The ogg part on the left refers to the dependency name, which should be the same as its Pkg-Config name. ogg_dep on the right refers to the variable in the build definitions that provides the dependency. Most commonly it holds the result of a declare_dependency call. If a variable of that name is not defined, Meson will exit with a hard error. For further details see the main Wrap manual.

Now you can create the build files, if the upstream project does not contain any, and work on them until the project builds correctly. Remember that all files go in the directory subprojects/packagefiles/<project-name>.

${EDITOR} meson.build meson_options.txt

In order to apply the locally added build files to the upstream release tarball, the wrap-file section must contain a patch_directory property naming the subdirectory in subprojects/packagefiles/ with the build files inside, as this is central to the way the wrapdb works. It will be used by the wrapdb meson.build, and when a release is created, the files from this directory will be converted into an archive and a patch_url will be added to the wrap file.

When you are satisfied with the results, add the build files to Git, update releases.json as described in README.md, and push the result to GitHub.

<verify that your project builds and runs>
git add releases.json subprojects/project.wrap subprojects/packagefiles/project/
git commit -a -m 'Add wrap files for libfoo-1.0.0'
git push -u origin libfoo

Now you should create a pull request on GitHub.

If packaging review requires you to do changes, use the --amend argument to commit so that your branch will have only one commit.

${EDITOR} meson.build
git commit -u --amend
git push --force

Changes to original source

The point of a wrap is to provide the upstream project with as few changes as possible. Most projects should not contain anything more than a few Meson definition files. Sometimes it may be necessary to add a template header file or something similar. These should be held at a minimum.

It should especially be noted that there must not be any patches to functionality. All such changes must be submitted to upstream. You may also host your own Git repo with the changes if you wish. The Wrap system has native support for Git subprojects.

Passing automatic validation

Every submitted wrap goes through an automated correctness review and passing it is a requirement for merging. Therefore it is highly recommended that you run the validation checks yourself so you can fix any issues faster.

You can test the wrap itself with the following commands:

meson subprojects purge --confirm
meson setup builddir/ -Dwraps=<project-name>

The first command is to ensure the wrap is correctly fetched from the latest packagefiles. The second command configures meson and selects a set of subprojects to enable.

The Github project contains automatic CI on pushing to run the project and check the metadata for obvious mistakes. This can be checked from your fork before submitting a PR.