Undefined symbol: _new_tunnel

[mikeshappell]

Good morning everyone.

I am hoping this is a simple issue and someone can help me out. I have spent a lot of time searching for a solution without any luck.

Summary

I have created a static library using the instructions in the repository for the target triple aarch64-apple-ios. The library built without issues. However, when I try to compile the project using the library, I get this error: "Undefined symbol: _new_tunnel". As the library is properly added to my project and the required "bridging header" is correct, I used nm to look at the library and discovered that, in fact, the symbol is not in the library.

What can cause this issue and how can I produce a library which contains the necessary exports to use the library?

Details

Although I have built a version of the library for more than one target triple, let's focus on the aarch64-apple-ios case for the moment. I have installed rustup and have the following versions installed.

rustup 1.27.0 (2024-03-08)
info: This is the version for the rustup toolchain manager, not the rustc compiler.
info: The currently active rustc version is rustc 1.77.1 (7cf61ebde 2024-03-27)

Apple clang version 15.0.0 (clang-1500.3.9.4)
Target: x86_64-apple-darwin23.4.0
Thread model: posix
InstalledDir: /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin

I have also installed the target using rustup.

rustup target add aarch64-apple-ios

Then, I built the library using the command from the README.md, which was:

cargo build --lib --release --no-default-features --target aarch64-apple-ios

This builds and produces the static and dynamic libraries as expected. Using the nm command on the resulting library, I see the following information (excerpt, but includes the only reference to boringtun as the rest are the many dependencies of the project).

cd targets/aarch64-apple-ios/release
nm libboringtun.a > t.txt

First part of t.txt

boringtun.oltf1cth477n37t.rcgu.o:
                 U ___rdl_alloc
                 U ___rdl_alloc_zeroed
                 U ___rdl_dealloc
                 U ___rdl_realloc
                 U ___rg_oom
---------------- T ___rust_alloc
---------------- T ___rust_alloc_error_handler
---------------- D ___rust_alloc_error_handler_should_panic
---------------- T ___rust_alloc_zeroed
---------------- T ___rust_dealloc
---------------- D ___rust_no_alloc_shim_is_unstable
---------------- T ___rust_realloc

hmac-96c14486fb5f355e.hmac.f89c15fd2c601d84-cgu.0.rcgu.o:

pin_project_lite-3d50fbfca7744f31.pin_project_lite.3f539c677dac0c66-cgu.0.rcgu.o:

lock_api-d5f5fcd6e14ec8d4.lock_api.8554128397852c1-cgu.0.rcgu.o:

<snip>

I am unclear why none of the symbols I expected are present. To ensure there was not an issue with my setup, I installed a sample project that generates a simple static library and verified that after building it, the symbols that I expected to be present were in fact in the library.

[mikeshappell]

Investigation

Following up on my own issue, after a lot of digging and testing, I realized that the command line to build the library, which was provided in the README.md, is the issue. The command line specifies --no-default-features, which disables most of the code for the library. In fact, the Cargo.toml includes an empty Default feature definition anyway, so with or without the command line option, the resulting library would be unusable.

I believe the correct command line for building for an iPhone is:

cargo build --lib --release --features "device ffi-bindings" --target aarch64-apple-ios

Obviously, if you were building for a different platform which required the JNI bindings you would need to include that in the feature list as well.

Conclusion

This is a documentation bug and should be resolved to prevent this issue for others.

I admit that my knowledge of Cargo at the start of this was quite limited, so I was relying heavily on the README.md and the information available in the repository. Having dug a little deeper into the package manger, I realized that no features were enabled by default and in fact the resulting library contained virtually no Wireguard code. Why the code was shipped this way is a bit of a mystery to me.

It seems like adding a minimal set of features to the Default feature and removing the --no-default-features flag from the documentation would be a good solution here.

Other useful information

As a side note, it is probably also worth mentioning that the nm included with the XCode command line tools does not appear compatible with the object format produced by the Rust LLVM. That leads to a lot of errors and missing symbols when dumping the library contents. For example:

/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/nm: error: 
libboringtun.a(boringtun.boringtun.d968bf83758f975a-cgu.0.rcgu.o): Unknown attribute kind (86) 
(Producer: 'LLVM17.0.6-rust-1.77.1-stable' Reader: 'LLVM APPLE_1_1500.3.9.4_0')

I found that Objdump was able to dump the library without issues.

objdump -d libboringtun.a

I also found the binutils, available from Homebrew, provided a usable nm. I was able to use gnm to successfully dump the contents of the library. This can be installed and used with the following commands.

brew install binutils
/usr/local/opt/binutils/bin/gnm libboringtun.a