Debian Codegraph @

subprojects/meson-docs/docs/markdown/Shipping-prebuilt-binaries-as-wraps.md

raw
1 # Shipping prebuilt binaries as wraps
2
3 A common dependency case, especially on Windows, is the need to
4 provide dependencies as prebuilt binaries rather than Meson projects
5 that you build from scratch. Common reasons include not having access
6 to source code, not having the time and effort to rewrite a legacy
7 system's build definitions to Meson or just the fact that compiling
8 the dependency projects takes too long.
9
10 Packaging a project is straightforward. As an example let's look at a
11 case where the project consists of one static library called `bob` and
12 some headers. To create a binary dependency project we put the static
13 library at the top level and headers in a subdirectory called
14 `include`. The Meson build definition would look like the following.
15
16 ```meson
17 project('bob', 'c')
18
19 # Do some sanity checking so that meson can fail early instead of at final link time
20 if not (host_machine.system() == 'windows' and host_machine.cpu_family() == 'x86_64')
21 error('This wrap of libbob is a binary wrap for x64_64 Windows, and will not work on your system')
22 endif
23
24 cc = meson.get_compiler('c')
25 bob_dep = declare_dependency(
26 dependencies : cc.find_library('bob', dirs : meson.current_source_dir()),
27 include_directories : include_directories('include'))
28
29 meson.override_dependency('bob', bob_dep)
30 ```
31
32 Now you can use this subproject as if it was a Meson project:
33
34 ```meson
35 project('using dep', 'c')
36 bob_dep = dependency('bob')
37 executable('prog', 'prog.c', dependencies : bob_dep)
38 ```
39
40 Note that often libraries compiled with different compilers (or even
41 compiler flags) might not be compatible. If you do this, then you are
42 responsible for verifying that your libraries are compatible, Meson
43 will not check things for you.
44
45 ## Using a wrap file
46
47 To make this all work automatically, a project will need a
48 [wrap file](Wrap-dependency-system-manual.md#wrap-format), as well as the
49 meson.build definition from above. For this example our dependency is called
50 `bob`.
51
52 The wrap ini (subprojects/bob.wrap):
53 ```ini
54 [wrap-file]
55 directory = libbob-1.0
56 source_url = https://libbob.example.com/libbob-1.0.zip
57 source_filename = libbob-1.0.zip
58 source_hash = 5ebeea0dfb75d090ea0e7ff84799b2a7a1550db3fe61eb5f6f61c2e971e57663
59 patch_directory = libbob
60
61 [provide]
62 dependency_names = bob
63 ```
64
65 Then create `subprojects/packagefiles/libbob/`, and place the `meson.build` from
66 above in that directory. With these in place a call to `dependency('bob')` will
67 first try standard discovery methods for your system (such as pkg-config, cmake,
68 and any built-in meson find methods), and then fall back to using the binary
69 wrap if it cannot find the dependency on the system. Meson provides the
70 `--force-fallback-for=bob` command line option to force the use of the fallback.
71
72 ## Note for Linux libraries
73
74 A precompiled linux shared library (.so) requires a soname field to be properly installed. If the soname field is missing, binaries referencing the library will require a hard link to the location of the library at install time (`/path/to/your/project/subprojects/precompiledlibrary/lib.so` instead of `$INSTALL_PREFIX/lib/lib.so`) after installation.
75
76 You should change the compilation options for the precompiled library to avoid this issue. If recompiling is not an option, you can use the [patchelf](https://github.com/NixOS/patchelf) tool with the command `patchelf --set-soname libfoo.so libfoo.so` to edit the precompiled library after the fact.
77
78 Meson generally guarantees any library it compiles has a soname. One notable exception is libraries built with the [[shared_module]] function.