]>
Commit | Line | Data |
---|---|---|
1e59de90 TL |
1 | # Creating Registries |
2 | ||
3 | **The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/maintainers/registries.md).** | |
4 | ||
5 | There are two parts to using registries; this documents the creation side of | |
6 | the relationship. In order to learn more about using registries that others | |
7 | have created, please read [this documentation](../users/registries.md). | |
8 | ## Table of Contents | |
9 | ||
10 | - [Creating Registries](#creating-registries) | |
11 | - [Table of Contents](#table-of-contents) | |
12 | - [Overview](#overview) | |
13 | - [Git Registries](#git-registries) | |
14 | - [Adding a New Version](#adding-a-new-version) | |
15 | - [Filesystem Registries](#filesystem-registries) | |
16 | - [Adding a New Version](#adding-a-new-version-1) | |
17 | ||
18 | ## Overview | |
19 | ||
20 | Registries are collections of ports and their versions. There are two major | |
21 | choices of implementation for registries, if you want to create your own - | |
22 | git registries, and filesystem registries. | |
23 | ||
24 | Git registries are simple git repositories, and can be shared publicly or | |
25 | privately via normal mechanisms for git repositories. The vcpkg repository at | |
26 | <https://github.com/microsoft/vcpkg>, for example, is a git registry. | |
27 | ||
28 | Filesystem registries are designed as more of a testing ground. Given that they | |
29 | literally live on your filesystem, the only way to share them is via shared | |
30 | directories. However, filesystem registries can be useful as a way to represent | |
31 | registries held in non-git version control systems, assuming one has some way | |
32 | to get the registry onto the disk. | |
33 | ||
34 | Note that we expect the set of registry types to grow over time; if you would | |
35 | like support for registries built in your favorite public version control | |
36 | system, don't hesitate to open a PR. | |
37 | ||
38 | The basic structure of a registry is: | |
39 | ||
40 | - The set of versions that are considered "latest" at certain times in history, | |
41 | known as the "baseline". | |
42 | - The set of all the versions of all the ports, and where to find each of | |
43 | these in the registry. | |
44 | ||
45 | ### Git Registries | |
46 | ||
47 | As you're following along with this documentation, it may be helpful to have | |
48 | a working example to refer to. We've written one and put it here: | |
49 | <https://github.com/northwindtraders/vcpkg-registry>. | |
50 | ||
51 | All git registries must have a `versions/baseline.json` file. This file | |
52 | contains the set of "latest versions" at a certain commit. It is laid out as | |
53 | a top-level object containing only the `"default"` field. This field should | |
54 | contain an object mapping port names to the version which is currently the | |
55 | latest. | |
56 | ||
57 | Here's an example of a valid baseline.json: | |
58 | ||
59 | ```json | |
60 | { | |
61 | "default": { | |
62 | "kitten": { | |
63 | "baseline": "2.6.2", | |
64 | "port-version": 0 | |
65 | }, | |
66 | "port-b": { | |
67 | "baseline": "19.00", | |
68 | "port-version": 2 | |
69 | } | |
70 | } | |
71 | } | |
72 | ``` | |
73 | ||
74 | The `versions` directory contains all the information about which versions of | |
75 | which packages are contained in the registry, along with where those versions | |
76 | are stored. The rest of the registry just acts as a backing store, as far as | |
77 | vcpkg is concerned: only things inside the `versions` directory will be used | |
78 | to direct how your registry is seen by vcpkg. | |
79 | ||
80 | Each port in a registry should exist in the versions directory as | |
81 | `<first letter of port>-/<name of port>.json`; in other words, the | |
82 | information about the `kitten` port would be located in | |
83 | `versions/k-/kitten.json`. This should be a top-level object with only a | |
84 | single field: `"versions"`. This field should contain an array of version | |
85 | objects: | |
86 | ||
87 | - The version of the port in question; should be exactly the same as the | |
88 | `vcpkg.json` file, including the version fields and `"port-version"`. | |
89 | - The `"git-tree"` field, which is a git tree; in other words, what you get | |
90 | when you write `git rev-parse COMMIT-ID:path/to/port`. | |
91 | ||
92 | Note that the version fields for ports with `CONTROL` files, is | |
93 | `"version-string"`; we do not recommend using `CONTROL` files in new | |
94 | registries, however. | |
95 | ||
96 | _WARNING_: One very important part of registries is that versions should | |
97 | _never_ be changed. Updating to a later ref should never remove or change an | |
98 | existing version. It must always be safe to update a registry. | |
99 | ||
100 | Here's an example of a valid version database for a `kitten` port with one | |
101 | version: | |
102 | ||
103 | ```json | |
104 | { | |
105 | "versions": [ | |
106 | { | |
107 | "version": "2.6.2", | |
108 | "port-version": 0, | |
109 | "git-tree": "67d60699c271b7716279fdea5a5c6543929eb90e" | |
110 | } | |
111 | ] | |
112 | } | |
113 | ``` | |
114 | ||
115 | In general, it's not important where you place port directories. However, the | |
116 | idiom in vcpkg is to follow what the built in vcpkg registry does: your | |
117 | `kitten` port should be placed in `ports/kitten`. | |
118 | ||
119 | _WARNING_: One other thing to keep in mind is that when you update a registry, | |
120 | all previous versions should also be accessible. Since your user will set their | |
121 | baseline to a commit ID, that commit ID must always exist, and be accessible | |
122 | from your HEAD commit, which is what is actually fetched. This means that your | |
123 | HEAD commit should be a child of all previous HEAD commits. | |
124 | ||
125 | #### Adding a New Version | |
126 | ||
127 | There is some git trickery involved in creating a new version of a port. The | |
128 | first thing to do is make some changes, update the `"port-version"` and regular | |
129 | version field as you need to, and then test with `overlay-ports`: | |
130 | `vcpkg install kitten --overlay-ports=ports/kitten`. | |
131 | ||
132 | Once you've finished your testing, you'll need to make sure that the directory | |
133 | as it is is under git's purview. You'll do this by creating a temporary commit: | |
134 | ||
135 | ```pwsh | |
136 | > git add ports/kitten | |
137 | > git commit -m 'temporary commit' | |
138 | ``` | |
139 | ||
140 | Then, get the git tree ID of the directory: | |
141 | ||
142 | ```pwsh | |
143 | > git rev-parse HEAD:ports/kitten | |
144 | 73ad3c823ef701c37421b450a34271d6beaf7b07 | |
145 | ``` | |
146 | ||
147 | Then, you can add this version to the versions database. At the top of your | |
148 | `versions/k-/kitten.json`, you can add (assuming you're adding version | |
149 | `2.6.3#0`): | |
150 | ||
151 | ```json | |
152 | { | |
153 | "versions": [ | |
154 | { | |
155 | "version": "2.6.3", | |
156 | "port-version": 0, | |
157 | "git-tree": "73ad3c823ef701c37421b450a34271d6beaf7b07" | |
158 | }, | |
159 | { | |
160 | "version": "2.6.2", | |
161 | "port-version": 0, | |
162 | "git-tree": "67d60699c271b7716279fdea5a5c6543929eb90e" | |
163 | } | |
164 | ] | |
165 | } | |
166 | ``` | |
167 | ||
168 | then, you'll want to modify your `versions/baseline.json` with your new version | |
169 | as well: | |
170 | ||
171 | ```json | |
172 | { | |
173 | "default": { | |
174 | "kitten": { | |
175 | "baseline": "2.6.3", | |
176 | "port-version": 0 | |
177 | }, | |
178 | "port-b": { | |
179 | "baseline": "19.00", | |
180 | "port-version": 2 | |
181 | } | |
182 | } | |
183 | } | |
184 | ``` | |
185 | ||
186 | and amend your current commit: | |
187 | ||
188 | ```pwsh | |
189 | > git commit --amend | |
190 | ``` | |
191 | ||
192 | then share away! | |
193 | ||
194 | ### Filesystem Registries | |
195 | ||
196 | As you're following along with this documentation, it may be helpful to have | |
197 | a working example to refer to. We've written one and put it here: | |
198 | <https://github.com/vcpkg/example-filesystem-registry>. | |
199 | ||
200 | All filesystem registries must have a `versions/baseline.json` file. This file | |
201 | contains the set of "latest versions" for a certain version of the registry. | |
202 | It is laid out as a top-level object containing a map from version name to | |
203 | "baseline objects", which map port names to the version which is considered | |
204 | "latest" for that version of the registry. | |
205 | ||
206 | Filesystem registries need to decide on a versioning scheme. Unlike git | |
207 | registries, which have the implicit versioning scheme of refs, filesystem | |
208 | registries can't rely on the version control system here. One possible option | |
209 | is to do a daily release, and have your "versions" be dates. | |
210 | ||
211 | _WARNING_: A baseline must always refer to the same set of versions. If you | |
212 | want to add new versions, you need to create a new version of the registry in | |
213 | the `baseline.json` file. | |
214 | ||
215 | Here's an example of a valid `baseline.json`, for a registry that has decided | |
216 | upon dates for their versions: | |
217 | ||
218 | ```json | |
219 | { | |
220 | "2021-04-16": { | |
221 | "kitten": { | |
222 | "baseline": "2.6.2", | |
223 | "port-version": 0 | |
224 | }, | |
225 | "port-b": { | |
226 | "baseline": "19.00", | |
227 | "port-version": 2 | |
228 | } | |
229 | }, | |
230 | "2021-04-15": { | |
231 | "kitten": { | |
232 | "baseline": "2.6.2", | |
233 | "port-version": 0 | |
234 | }, | |
235 | "port-b": { | |
236 | "baseline": "19.00", | |
237 | "port-version": 1 | |
238 | } | |
239 | } | |
240 | } | |
241 | ``` | |
242 | ||
243 | The `versions` directory contains all the information about which versions of | |
244 | which packages are contained in the registry, along with where those versions | |
245 | are stored. The rest of the registry just acts as a backing store, as far as | |
246 | vcpkg is concerned: only things inside the `versions` directory will be used | |
247 | to direct how your registry is seen by vcpkg. | |
248 | ||
249 | Each port in a registry should exist in the versions directory as | |
250 | `<first letter of port>-/<name of port>.json`; in other words, the | |
251 | information about the `kitten` port would be located in | |
252 | `versions/k-/kitten.json`. This should be a top-level object with only a | |
253 | single field: `"versions"`. This field should contain an array of version | |
254 | objects: | |
255 | ||
256 | - The version of the port in question; should be exactly the same as the | |
257 | `vcpkg.json` file, including the version fields and `"port-version"`. | |
258 | - The `"path"` field: a relative directory, rooted at the base of the registry | |
259 | (in other words, the directory where `versions` is located), to the port | |
260 | directory. It should look something like `"$/path/to/port/dir`" | |
261 | ||
262 | Note that the version fields for ports with `CONTROL` files, is | |
263 | `"version-string"`; we do not recommend using `CONTROL` files in new | |
264 | registries, however. | |
265 | ||
266 | In general, it's not important where you place port directories. However, the | |
267 | idiom in vcpkg is to follow somewhat closely to what the built in vcpkg | |
268 | registry does: your `kitten` port at version `x.y.z` should be placed in | |
269 | `ports/kitten/x.y.z`, with port versions appended as you see fit (although | |
270 | since `#` is not a good character to use for file names, perhaps use `_`). | |
271 | ||
272 | _WARNING_: One very important part of registries is that versions should | |
273 | _never_ be changed. One should never remove or change an existing version. | |
274 | Your changes to your registry shouldn't change behavior to downstream users. | |
275 | ||
276 | Here's an example of a valid version database for a `kitten` port with one | |
277 | version: | |
278 | ||
279 | ```json | |
280 | { | |
281 | "versions": [ | |
282 | { | |
283 | "version": "2.6.2", | |
284 | "port-version": 0, | |
285 | "git-tree": "$/ports/kitten/2.6.2_0" | |
286 | } | |
287 | ] | |
288 | } | |
289 | ``` | |
290 | ||
291 | #### Adding a New Version | |
292 | ||
293 | Unlike git registries, adding a new version to a filesystem registry mostly | |
294 | involves a lot of copying. The first thing to do is to copy the latest | |
295 | version of your port into a new version directory, update the version and | |
296 | `"port-version"` fields as you need to, and then test with `overlay-ports`: | |
297 | `vcpkg install kitten --overlay-ports=ports/kitten/new-version`. | |
298 | ||
299 | Once you've finished your testing, you can add this new version to the top of | |
300 | your `versions/k-/kitten.json`: | |
301 | ||
302 | ```json | |
303 | { | |
304 | "versions": [ | |
305 | { | |
306 | "version": "2.6.3", | |
307 | "port-version": 0, | |
308 | "git-tree": "$/ports/kitten/2.6.3_0" | |
309 | }, | |
310 | { | |
311 | "version": "2.6.2", | |
312 | "port-version": 0, | |
313 | "git-tree": "$/ports/kitten/2.6.2_0" | |
314 | } | |
315 | ] | |
316 | } | |
317 | ``` | |
318 | ||
319 | then, you'll want to modify your `versions/baseline.json` with your new version | |
320 | as well (remember not to modify existing baselines): | |
321 | ||
322 | ```json | |
323 | { | |
324 | "2021-04-17": { | |
325 | "kitten": { | |
326 | "baseline": "2.6.3", | |
327 | "port-version": 0 | |
328 | }, | |
329 | "port-b": { | |
330 | "baseline": "19.00", | |
331 | "port-version": 2 | |
332 | } | |
333 | }, | |
334 | "2021-04-16": { | |
335 | "kitten": { | |
336 | "baseline": "2.6.2", | |
337 | "port-version": 0 | |
338 | }, | |
339 | "port-b": { | |
340 | "baseline": "19.00", | |
341 | "port-version": 2 | |
342 | } | |
343 | }, | |
344 | "2021-04-15": { | |
345 | "kitten": { | |
346 | "baseline": "2.6.2", | |
347 | "port-version": 0 | |
348 | }, | |
349 | "port-b": { | |
350 | "baseline": "19.00", | |
351 | "port-version": 1 | |
352 | } | |
353 | } | |
354 | } | |
355 | ``` | |
356 | ||
357 | and you're done! |