tsf-sys  

Unsafe rust bindings for TinySoundFont. Don't use this crate directly, instead use tsf which has more user-friendly bindings.

Build requirements

Unfortunately, this library comes with some non-standard build requirements, due to the fact that it uses both cc and bindgen. This means that you will need to do some extra setup, even just if this is a dependency (or a dependency of a dependency...).

cc

We use CC to build the C library which is bundled with this crate. This means you need to have a C compiler installed. In particular, when building against a target triple (with cargo build --target x-y-z) you will need a C compiler from that target's toolchain (i.e. a C compiler which runs on the host, which compiles to the target). You also need an archiver for the target.

Practically, this means:

• When compiling with no target (or a target equal to the host) (e.g. for testing), you just need a C compiler and archiver installed in some sensible way; it should be picked up automatically. If it's not (e.g. the wrong one is picked up), then set the CC and AR environment variables with the paths of the respective executables.
• When compiling with a target triple x-y-z different to the host, you will need to set environment variables CC_x-y-z and AR_x-y-z with paths of the compiler and archiver of the target's toolchain respectively. These are usually the same paths as the ones in your config or config.toml file, which you probably added when installing this target via rustup.

(You may need to set some additional parameters to ensure your compiler chooses he correct target, e.g. the --target clang flag. So far I've only tested Android which doesn't require it if you follow the example below.)

For example, when building to Android you can find this compiler and archiver within the NDK. See this guide. The compiler will be $NDK/toolchains/llvm/prebuilt/$HOST_TAG/bin/$TARGET$NDK_VERSION-clang and the AR will be $NDK/toolchains/llvm/prebuilt/$HOST_TAG/bin/$TARGET-ar

These requirements are the same for any project using cc to compile a C library, so if you already have this configured then your current configuration is probably fine too.

These requirements could be lifted by prebuilding the library for some targets and checking them into git. Pull requests are welcome!

Bindgen

We use Bindgen to generate the rust bindings to the C library's header files. This requires an installation of clang.

These requirements could be liften by prebuilding the bindings for some targets and checking them into git. Pull requests are welcome!

Usage example

Suppose the crate mylib depends on tsf (which depends on tsf-sys), and my host machine is windows and I want to compile mylib against the target armv7-linux-androideabi. Suppose mylib produces a dynamic C lib.

1. Make sure to download the target with rustup target add armv7-linux-androideabi.

2. Then download the toolchain of that target. In this case, it's the NDK that you wish to compile against, which for me is NDK 21.

3. Add the following to a cargo config file (config.toml or config):

[target.armv7-linux-androideabi]
linker = "C:\\path\\to\\ndk\\21.4.7075529\\toolchains\\llvm\\prebuilt\\windows-x86_64\\bin\\armv7a-linux-androideabi21-clang.cmd"
ar = "C:\\path\\to\\ndk\\21.4.7075529\\toolchains\\llvm\\prebuilt\\windows-x86_64\\bin\\arm-linux-androideabi-ar"
# Note that for this target specifically, the `ar` doesn't include the v7a but of the target. Just a quirk of the NDK.

4. Set the following environment variables (you can either paste this into your command prompt, or set them more permanently):

set CC_armv7-linux-androideabi=C:\\path\\to\\ndk\\21.4.7075529\\toolchains\\llvm\\prebuilt\\windows-x86_64\\bin\\armv7a-linux-androideabi21-clang.cmd
set AR_armv7-linux-androideabi=C:\\path\\to\\ndk\\21.4.7075529\\toolchains\\llvm\\prebuilt\\windows-x86_64\\bin\\arm-linux-androideabi-ar 

5. Follow the bindgen requirements above, including setting the LIBCLANG_PATH environment variable.

6. Finally, use cargo to build mylib.

rem Comments in windows command line are given by rem
rem Print out our environment variables to check they were set right. You can obviously omit this
echo %CC_armv7-linux-androideabi%
echo %AR_armv7-linux-androideabi%
echo %LIBCLANG_PATH%
cargo build --target armv7-linux-androideabi --release

For non-Windows host machines all the steps are the same, just slightly different commands. E.g. to set environment variables you can put VAR=VALUE before the cargo build command, which is nice.

Contributing

This crate was written by following this rust-bindgen tutorial. If you can follow that tutorial, then you understand how this crate works.

TinySoundFont is bundled

TinySoundFont is distributed as a header file. This crate includes a static library compiled from that header file, which makes it incredibly convenient to use - you don't need to do anything special.

An un-bundled version of this crate is currently not available. Pull equensts are welcome.