Debian Codegraph @

subprojects/meson-docs/docs/markdown/Creating-releases.md

raw
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 ```