| 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. |