diff options
Diffstat (limited to 'meson/docs/markdown/Adding-new-projects-to-wrapdb.md')
| -rw-r--r-- | meson/docs/markdown/Adding-new-projects-to-wrapdb.md | 267 |
1 files changed, 267 insertions, 0 deletions
diff --git a/meson/docs/markdown/Adding-new-projects-to-wrapdb.md b/meson/docs/markdown/Adding-new-projects-to-wrapdb.md new file mode 100644 index 000000000..51a0d7171 --- /dev/null +++ b/meson/docs/markdown/Adding-new-projects-to-wrapdb.md @@ -0,0 +1,267 @@ +# Adding new projects to WrapDB + + +## How it works + +Each wrap repository has a master branch with only one initial commit +and *no* wrap files. And that is the only commit ever made on that +branch. + +For every release of a project a new branch is created. The new branch +is named after the the upstream release number (e.g. `1.0.0`). This +branch holds a wrap file for this particular release. + +There are two types of wraps on WrapDB - regular wraps and wraps with +Meson build definition patches. A wrap file in a repository on WrapDB +must have a name `upstream.wrap`. + +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 Git +repositories on GitHub. They only contain build definition files. You +may also think of them as an overlay to upstream source. + +Whenever a new commit is pushed into GitHub's project branch, a new +wrap is generated with an incremented version number. 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 repository name + +Wrapped subprojects are used much like external dependencies. Thus +they should have the same name as the upstream projects. + +NOTE: Repo names must fully match this regexp: `[a-z0-9._]+`. + +If the project provides a pkg-config file, then the repository 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 repository is +named plain `ogg`. + +If there is no a 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 +- `upstream.wrap` should be provided. In other case a Meson build +definition patch - a set of `meson.build` files - should be also +provided. + +### Request a new repository + +*Note:* you should only do this if you have written the build files +and want to contribute them for inclusion to WrapDB. The maintainers +have only limited reesources and unfortunately can not take requests +to write Meson build definitions for arbitrary projects. + +The submission starts by creating an issue on the [wrapdb bug +tracker](https://github.com/mesonbuild/wrapdb/issues) using *Title* +and *Description* below as a template. + +*Title:* `new wrap: <project_name>` + +*Description:* +``` +upstream url: <link_to_updastream> +version: <version_you_have_a_wrap_for> +``` + +Wait until the new repository or branch is created. A link to the new +repository or branch will be posted in a comment to this issue. After +this you can createa a merge request in that repository for your build +files. + +NOTE: Requesting a branch is not necessary. WrapDB maintainer can +create the branch and modify the PR accordingly if the project +repository exists. + +### Creating the wrap contents + +Setting up the contents might seem a bit counterintuitive at first. +Just remember that the outcome needs to have one (and only one) commit +that has all the build definition files (i.e. `meson.build` and +`meson_options.txt` files) and _nothing else_. It is good practice to +have this commit in a branch whose name matches the release as +described above. + +First you need to fork the repository to your own page using GitHub's +fork button. Then you can clone the repo to your local machine. + + +``` +git clone git@github.com:yourusername/libfoo.git foo-wrap +``` + +Create a new branch for your work: + +``` +git checkout -b 1.0.0 +``` + +If you are adding new changes to an existing branch, leave out the +`-b` argument. + +Now you need to copy the source code for the original project to this +directory. If you already have it extracted somewhere, you'd do +something like this: + +``` +cd /path/to/source/extract/dir +cp -r * /path/to/foo-wrap +``` + +Now all the files should be in the wrap directory. Do _not_ add them +to Git, though. Neither now or at any time during this process. The +repo must contain only the newly created build files. + +New release branches require an `upstream.wrap` file, so create one if +needed. + +``` +${EDITOR} upstream.wrap +``` + +The file format is simple, see any existing wrapdb repo 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: + +```ini +[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](Wrap-dependency-system-manual.md). + +Now you can create the build files and work on them until the project +builds correctly. + +``` +${EDITOR} meson.build meson_options.txt +``` + +When you are satisfied with the results, add the build files to Git +and push the result to GitHub. + +``` +<verify that your project builds and runs> +git add upstream.wrap meson.build +git commit -a -m 'Add wrap files for libfoo-1.0.0' +git push -u origin 1.0.0 +``` + +Now you should create a pull request on GitHub. Try to create it +against the correct branch rather than master (`1.0.0` branch in this +example). GitHub should do this automatically. + +If the branch doesn't exist file a pull request against master. +WrapDB maintainers can fix it before merging. + +If packaging review requires you to do changes, use the `--amend` +argument to `commit` so that your branch will continue to have only +one commit. + +``` +${EDITOR} meson.build +git commit -a --amend +git push --force +``` + +### Request a new release version to an existing repository + +Adding new releases to an existing repo is straightforward. All you +need to do is to follow the rules discussed above but when you create +the merge request, file it against the master branch. The repository +reviewer will create the necessary branch and retarget your merge +request accordingly. + +## What is done by WrapDB maintainers + +[mesonwrap tools](Wrap-maintainer-tools.md) must be used for the tasks +below. + +### Adding new project to the Wrap provider service + +Each project gets its own repo. It is initialized like this: + +``` +mesonwrap new_repo --homepage=$HOMEPAGE --directory=$NEW_LOCAL_PROJECT_DIR $PROJECT_NAME +``` + +The command creates a new repository and uploads it to GitHub. + +`--version` flag may be used to create a branch immediately. + +### Adding a new branch to an existing project + +Create a new branch whose name matches the upstream release number. + +``` +git checkout master +git checkout -b 1.0.0 +git push origin 1.0.0 +(or from GitHub web page, remember to branch from master) +``` + +Branch names must fully match this regexp: `[a-z0-9._]+`. + +## 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. + +Instructions on how to install and run the review tool can be found on +the [Wrap review guidelines page](Wrap-review-guidelines.md). If your +submission is merge request number 5 for a repository called `mylib`, +then you'd run the following command: + + mesonwrap review --pull-request 5 mylib |