diff options
| -rw-r--r-- | docs/markdown/Wrap-dependency-system-manual.md | 156 |
1 files changed, 65 insertions, 91 deletions
diff --git a/docs/markdown/Wrap-dependency-system-manual.md b/docs/markdown/Wrap-dependency-system-manual.md index 22ba589..f2262b8 100644 --- a/docs/markdown/Wrap-dependency-system-manual.md +++ b/docs/markdown/Wrap-dependency-system-manual.md @@ -2,12 +2,13 @@ One of the major problems of multiplatform development is wrangling all your dependencies. This is easy on Linux where you can use system -packages but awkward on other platforms. Most of those do not have a -package manager at all. This has been worked around by having third -party package managers. They are not really a solution for end user -deployment, because you can't tell them to install a package manager -just to use your app. On these platforms you must produce -self-contained applications. +packages (and happen to know that your target distribution provides a +recent enough version of the dependency) but awkward on other +platforms. Most of those do not have a package manager at all. This +has been worked around by having third party package managers. They +are not really a solution for end user deployment, because you can't +tell them to install a package manager just to use your app. On these +platforms you must produce self-contained applications. The traditional approach to this has been to bundle dependencies inside your own project. Either as prebuilt libraries and headers or @@ -36,15 +37,18 @@ subproject embedding extremely easy. All wrap files must have a name of `<project_name>.wrap` form and be in `subprojects` dir. -Currently Meson has three kinds of wraps: +Currently Meson has four kinds of wraps: - wrap-file -- wrap-file with Meson build patch - wrap-git +- wrap-hg +- wrap-svn -## wrap-file +## wrap format -An example wrap file for `libfoobar` would have a name `libfoobar.wrap` -and would look like this: +Wrap files are written in ini format, with a single header containing the type +of wrap, followed by properties describing how to obtain the sources, validate +them, and modify them if needed. An example wrap-file for the wrap named +`libfoobar` would have a filename `libfoobar.wrap` and would look like this: ```ini [wrap-file] @@ -55,38 +59,60 @@ source_filename = foobar-1.0.tar.gz source_hash = 5ebeea0dfb75d090ea0e7ff84799b2a7a1550db3fe61eb5f6f61c2e971e57663 ``` -`source_hash` is *sha256sum* of `source_filename`. +An example wrap-git will look like this: -Since *0.49.0* if `source_filename` is found in project's -`subprojects/packagecache` directory, it will be used instead of downloading the -source, even if `--wrap-mode` option is set to `nodownload`. The file's hash will -be checked. +```ini +[wrap-git] +url = https://github.com/libfoobar/libfoobar.git +revision = head +``` + +## Accepted configuration properties for wraps +- `directory` - name of the subproject root directory, defaults to the name of the wrap. + +### Specific to wrap-file +- `source_url` - download url to retrieve the wrap-file source archive +- `source_filename` - filename of the downloaded source archive +- `source_hash` - sha256 checksum of the downloaded source archive +- `patch_url` - download url to retrieve an optional overlay archive +- `patch_filename` - filename of the downloaded overlay archive +- `patch_hash` - sha256 checksum of the downloaded overlay archive +- `lead_directory_missing` - for `wrap-file` create the leading + directory name. Needed when the source file does not have a leading + directory. + +Since *0.49.0* if `source_filename` or `patch_filename` is found in the +project's `subprojects/packagecache` directory, it will be used instead +of downloading the file, even if `--wrap-mode` option is set to +`nodownload`. The file's hash will be checked. + +### Specific to VCS-based wraps +- `url` - name of the wrap-git repository to clone. Required. +- `revision` - name of the revision to checkout. Must be either: a + valid value (such as a git tag) for the VCS's `checkout` command, or + (for git) `head` to track upstream's default branch. Required. + +## Specific to wrap-git +- `depth` - shallowly clone the repository to X number of commits. Note + that git always allow shallowly cloning branches, but in order to + clone commit ids shallowly, the server must support + `uploadpack.allowReachableSHA1InWant=true`. *(since 0.52.0)* +- `push-url` - alternative url to configure as a git push-url. Useful if + the subproject will be developed and changes pushed upstream. + *(since 0.37.0)* +- `clone-recursive` - also clone submodules of the repository + *(since 0.48.0)* ## wrap-file with Meson build patch Unfortunately most software projects in the world do not build with -Meson. Because of this Meson allows you to specify a patch URL. This -works in much the same way as Debian's distro patches. That is, they -are downloaded and automatically applied to the subproject. These -files contain a Meson build definition for the given subproject. +Meson. Because of this Meson allows you to specify a patch URL. -A wrap file with an additional patch URL would look like this: - -```ini -[wrap-file] -directory = libfoobar-1.0 - -source_url = https://upstream.example.com/foobar-1.0.tar.gz -source_filename = foobar-1.0.tar.gz -source_hash = 5ebeea0dfb75d090ea0e7ff84799b2a7a1550db3fe61eb5f6f61c2e971e57663 - -patch_url = https://myserver.example.com/libfoobar-meson.tar.gz -patch_filename = libfoobar-meson.tar.gz -patch_hash = 8c9d00702d5fe4a6bf25a36b821a332f6b2dfd117c66fe818b88b23d604635e9 -``` - -In this example the Wrap manager would download the patch and unzip it -in libfoobar's directory. +For historic reasons this is called a "patch", however, it serves as an +overlay to add or replace files rather than modifying them. The file +must be an archive; it is downloaded and automatically extracted into +the subproject. The extracted files will include a meson build +definition for the given subproject. This approach makes it extremely simple to embed dependencies that require build system changes. You can write the Meson build definition @@ -96,60 +122,8 @@ thousands of lines of code. Once you have a working build definition, just zip up the Meson build files (and others you have changed) and put them somewhere where you can download them. -Since *0.49.0* if `patch_filename` is found in project's -`subprojects/packagecache` directory, it will be used instead of downloading the -patch, even if `--wrap-mode` option is set to `nodownload`. The file's hash will -be checked. - -## wrap-git - -This type of wrap allows branching subprojects directly from git. - -The above mentioned scheme assumes that your subproject is working off -packaged files. Sometimes you want to check code out directly from -Git. Meson supports this natively. All you need to do is to write a -slightly different wrap file. - -```ini -[wrap-git] -directory = samplesubproject -url = https://github.com/jpakkane/samplesubproject.git -revision = head -``` - -The format is straightforward. The only thing to note is the revision -element that can have one of two values. The first is `head` which -will cause Meson to track the master head (doing a repull whenever the -build definition is altered). The second type is a commit hash or a -tag. In this case Meson will use the commit specified (with `git -checkout [hash/tag id]`). - -Note that in this case you cannot specify an extra patch file to -use. The git repo must contain all necessary Meson build definitions. - -Usually you would use subprojects as read only. However in some cases -you want to do commits to subprojects and push them upstream. For -these cases you can specify the upload URL by adding the following at -the end of your wrap file: - -```ini -push-url = git@git.example.com:projects/someproject.git # Supported since version 0.37.0 -``` - -If the git repo contains submodules, you can tell Meson to clone them -automatically by adding the following *(since 0.48.0)*: - -```ini -clone-recursive = true -``` - -Setting the clone depth is supported using the `depth` directive *(since 0.52.0)*. -Note that git always allow shallowly cloning branches, but in order to clone commit ids -shallowly, the server must support `uploadpack.allowReachableSHA1InWant=true`. - -```ini -depth = 1 -``` +Meson build patches are only supported for wrap-file mode. When using +wrap-git, the repository must contain all Meson build definitions. ## Using wrapped projects |