Debian Codegraph @

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

raw
1 # Adding new projects to WrapDB
2
3
4 ## How it works
5
6 New wraps must be submitted as a working subproject to the [wrapdb
7 repository](https://github.com/mesonbuild/wrapdb).
8
9 There are two types of wraps on WrapDB - regular wraps and wraps with
10 Meson build definition patches.
11
12 Wraps with Meson build definition patches work in much the same way as
13 Debian: we take the unaltered upstream source package and add a new
14 build system to it as a patch. These build systems are stored as a
15 subdirectory of subprojects/packagefiles/. They only contain build
16 definition files. You may also think of them as an overlay to upstream
17 source.
18
19 Wraps without Meson build definition patches only contain the wrap
20 metadata describing how to fetch the project
21
22 Whenever a new release is pushed into the wrapdb, a new tag is
23 generated with an incremented version number, and a new release is
24 added to the wrapdb API listing. All the old releases remain
25 unaltered. New commits are always done via GitHub merge requests and
26 must be reviewed by someone other than the submitter.
27
28 Note that your Git repo with wrap must not contain the subdirectory of
29 the source release. That gets added automatically by the service. You
30 also must not commit any source code from the original tarball into
31 the wrap repository.
32
33 ## Choosing the wrap name
34
35 Wrapped subprojects are used much like external dependencies. Thus
36 they should have the same name as the upstream projects.
37
38 NOTE: Wrap names must fully match this regexp: `[a-z0-9._]+`.
39
40 If the project provides a pkg-config file, then the wrap name
41 should be the same as the pkg-config name. Usually this is the name of
42 the project, such as `libpng`. Sometimes it is slightly different,
43 however. As an example the libogg project's chosen pkg-config name is
44 `ogg` instead of `libogg`, which is the reason why the wrap is
45 named plain `ogg`.
46
47 If there is no pkg-config file, the name the project uses/promotes
48 should be used, lowercase only (Catch2 -> catch2).
49
50 If the project name is too generic or ambiguous (e.g. `benchmark`),
51 consider using `organization-project` naming format (e.g.
52 `google-benchmark`).
53
54 ## How to contribute a new wrap
55
56 If the project already uses Meson build system, then only a wrap file
57 `project.wrap` should be provided. In other case a Meson build
58 definition patch - a set of `meson.build` files - should also be
59 provided.
60
61 ### Creating the wrap contents
62
63 New release branches require a `project.wrap` file, so create one if
64 needed.
65
66 ```
67 ${EDITOR} upstream.wrap
68 ```
69
70 The file format is simple, see any existing wrapdb subproject for the
71 content. The checksum is SHA-256 and can be calculated with the
72 following command on most unix-like operating systems:
73
74 ```
75 sha256sum path/to/libfoo-1.0.0.tar.gz
76 ```
77
78 Under macOS the command is the following:
79
80 ```
81 shasum -a 256 path/to/libfoo-1.0.0.tar.gz
82 ```
83
84 Next you need to add the entries that define what dependencies the
85 current project provides. This is important, as it is what makes
86 Meson's automatic dependency resolver work. It is done by adding a
87 `provide` entry at the end of the `upstream.wrap` file. Using the Ogg
88 library as an example, this is what it would look like:
89
90 ```ini
91 [provide]
92 ogg = ogg_dep
93 ```
94
95 The `ogg` part on the left refers to the dependency name, which should
96 be the same as its Pkg-Config name. `ogg_dep` on the right refers to
97 the variable in the build definitions that provides the dependency.
98 Most commonly it holds the result of a `declare_dependency` call. If a
99 variable of that name is not defined, Meson will exit with a hard
100 error. For further details see [the main Wrap
101 manual](Wrap-dependency-system-manual.md).
102
103 Now you can create the build files, if the upstream project does not
104 contain any, and work on them until the project builds correctly.
105 Remember that all files go in the directory
106 `subprojects/packagefiles/<project-name>`.
107
108 ```
109 ${EDITOR} meson.build meson.options
110 ```
111
112 In order to apply the locally added build files to the upstream
113 release tarball, the `wrap-file` section must contain a
114 `patch_directory` property naming the subdirectory in
115 subprojects/packagefiles/ with the build files inside, as this is
116 central to the way the wrapdb works. It will be used by the wrapdb
117 meson.build, and when a release is created, the files from this
118 directory will be converted into an archive and a patch_url will be
119 added to the wrap file.
120
121 When you are satisfied with the results, add the build files to Git, update
122 releases.json as described in
123 [README.md](https://github.com/mesonbuild/wrapdb#readme), and push the result
124 to GitHub.
125
126 ```
127 <verify that your project builds and runs>
128 git add releases.json subprojects/project.wrap subprojects/packagefiles/project/
129 git commit -a -m 'Add wrap files for libfoo-1.0.0'
130 git push -u origin libfoo
131 ```
132
133 Now you should create a pull request on GitHub.
134
135 If packaging review requires you to do changes, use the `--amend`
136 argument to `commit` so that your branch will have only one commit.
137
138 ```
139 ${EDITOR} meson.build
140 git commit -u --amend
141 git push --force
142 ```
143
144 ## Changes to original source
145
146 The point of a wrap is to provide the upstream project with as few
147 changes as possible. Most projects should not contain anything more
148 than a few Meson definition files. Sometimes it may be necessary to
149 add a template header file or something similar. These should be held
150 at a minimum.
151
152 It should especially be noted that there must **not** be any patches
153 to functionality. All such changes must be submitted to upstream. You
154 may also host your own Git repo with the changes if you wish. The Wrap
155 system has native support for Git subprojects.
156
157 ## Passing automatic validation
158
159 Every submitted wrap goes through an automated correctness review and
160 passing it is a requirement for merging. Therefore it is highly
161 recommended that you run the validation checks yourself so you can fix
162 any issues faster.
163
164 You can test the wrap itself with the following commands:
165
166 meson subprojects purge --confirm
167 meson setup builddir/ -Dwraps=<project-name>
168
169 The first command is to ensure the wrap is correctly fetched from the
170 latest packagefiles. The second command configures meson and selects a
171 set of subprojects to enable.
172
173 The GitHub project contains automatic CI on pushing to run the project
174 and check the metadata for obvious mistakes. This can be checked from
175 your fork before submitting a PR.