| 1 |
--- |
| 2 |
short-description: Creating releases |
| 3 |
... |
| 4 |
|
| 5 |
# Creating releases |
| 6 |
|
| 7 |
In addition to development, almost all projects provide periodical |
| 8 |
source releases. These are standalone packages (usually either in |
| 9 |
tar or zip format) of the source code. They do not contain any |
| 10 |
revision control metadata, only the source code. Meson provides |
| 11 |
a simple way of generating these, with the `meson dist` command. |
| 12 |
|
| 13 |
Meson provides a simple way of generating these. It consists of a |
| 14 |
single command *(available since 0.52.0)*: |
| 15 |
|
| 16 |
```sh |
| 17 |
meson dist |
| 18 |
``` |
| 19 |
|
| 20 |
or alternatively (on older Meson versions with `ninja` backend): |
| 21 |
|
| 22 |
```sh |
| 23 |
ninja dist |
| 24 |
``` |
| 25 |
|
| 26 |
This creates a file called `projectname-version.tar.xz` in the build |
| 27 |
tree subdirectory `meson-dist`. This archive contains the full |
| 28 |
contents of the latest commit in revision control including all the |
| 29 |
submodules (recursively). All revision control metadata is removed. |
| 30 |
Meson then takes this archive and tests that it works by doing a full |
| 31 |
`compile` + `test` + `install` cycle. If all these pass, Meson will |
| 32 |
then create a `SHA-256` checksum file next to the archive. |
| 33 |
|
| 34 |
|
| 35 |
## Autotools dist VS Meson dist |
| 36 |
|
| 37 |
Meson behaviour is different from Autotools. The Autotools "dist" |
| 38 |
target packages up the current source tree. Meson packages the latest |
| 39 |
revision control commit. The reason for this is that it prevents |
| 40 |
developers from doing accidental releases where the distributed |
| 41 |
archive does not match any commit in revision control (especially the |
| 42 |
one tagged for the release). |
| 43 |
|
| 44 |
|
| 45 |
## Include subprojects in your release |
| 46 |
|
| 47 |
The `meson dist` command has `--include-subprojects` command line |
| 48 |
option. When enabled, the source tree of all subprojects used by the |
| 49 |
current build will also be included in the final tarball. This is |
| 50 |
useful to distribute self contained tarball that can be built offline |
| 51 |
(i.e. `--wrap-mode=nodownload`). |
| 52 |
|
| 53 |
|
| 54 |
## Skip build and test with `--no-tests` |
| 55 |
|
| 56 |
The `meson dist` command has a `--no-tests` option to skip build and |
| 57 |
tests steps of generated packages. It can be used to not waste time |
| 58 |
for example when done in CI that already does its own testing. |
| 59 |
|
| 60 |
So with `--no-tests` you can tell Meson "Do not build and test generated |
| 61 |
packages.". |
| 62 |
|
| 63 |
## Use `--allow-dirty` to override error when git repository contains uncommitted changes |
| 64 |
|
| 65 |
*Since 0.62.0* Instead of emitting a warning when a repository contains |
| 66 |
uncommitted changes, Meson will produce an error message notifying the |
| 67 |
user and immediately exit. If `--allow-dirty` is given as an option to |
| 68 |
`meson dist`, a warning will be emitted instead and Meson will proceed |
| 69 |
as usual. |
| 70 |
|
| 71 |
## Release a subproject separately |
| 72 |
|
| 73 |
*Since 0.57.0* the `meson dist` command can now create a distribution tarball |
| 74 |
for a subproject in the same git repository as the main project. This can be |
| 75 |
useful if parts of the project (e.g. libraries) can be built and distributed |
| 76 |
separately. In that case they can be moved into `subprojects/mysub` and running |
| 77 |
`meson dist` in that directory will now create a tarball containing only the |
| 78 |
source code from that subdir and not the rest of the main project or other |
| 79 |
subprojects. |
| 80 |
|
| 81 |
For example: |
| 82 |
```sh |
| 83 |
git clone https://github.com/myproject |
| 84 |
cd myproject/subprojects/mysubproject |
| 85 |
meson setup builddir |
| 86 |
meson dist -C builddir |
| 87 |
``` |
| 88 |
This produces `builddir/meson-dist/mysubproject-1.0.tar.xz` tarball. |
| 89 |
|
| 90 |
## Cement a version obtained from VCS |
| 91 |
|
| 92 |
*Since 1.4.0* the `meson dist` command enables rewriting the build |
| 93 |
configuration of the distribution tarball. This is needed when the |
| 94 |
configuration depends on metadata from revision control such as in the |
| 95 |
following example. |
| 96 |
|
| 97 |
`meson.build`: |
| 98 |
```meson |
| 99 |
project('tig', 'c', |
| 100 |
version : run_command('version.sh', 'get-vcs').stdout.strip()) |
| 101 |
|
| 102 |
meson.add_dist_script('version.sh', 'set-dist', meson.project_version()) |
| 103 |
``` |
| 104 |
`version.sh`: |
| 105 |
```sh |
| 106 |
#!/bin/sh |
| 107 |
|
| 108 |
if [ "$1" = "get-vcs" ]; then |
| 109 |
git -C "$MESON_SOURCE_ROOT" describe --always --dirty |
| 110 |
elif [ "$1" = "set-dist" ]; then |
| 111 |
$MESONREWRITE --sourcedir="$MESON_PROJECT_DIST_ROOT" kwargs set project / version "$2" |
| 112 |
else |
| 113 |
exit 1 |
| 114 |
fi |
| 115 |
``` |