Step-by-step Guide for setting up ASIO

mitchmindtree commented 5 years ago

It would be nice to add something like this to the README for Windows users who would like to use ASIO:

Setting Up ASIO.

Download the ASIO SDK .zip from this link. The version as of writing this is 2.3.1.
Extract the files and place the ASIOSDK2.3.1 directory somewhere you are happy for it to stay (e.g. ~/.asio).
Assign the full path of the ASIOSDK2.3.1 directory to the CPAL_ASIO_DIR environment variable. How to set persisting Environment Variables on Windows.
Download and install LLVM from here under the "Pre-Built Binaries" section. The version as of writing this is 7.0.0.
Add the LLVM bin directory to a LIBCLANG_PATH environment variable. If you installed LLVM to the default directory, this should work in the command prompt:
```
setx LIBCLANG_PATH "C:\Program Files\LLVM\bin"
```
If you don't have any ASIO devices or drivers availabe, you can download and install ASIO4ALL. Be sure to enable the "offline" feature during installation despite what the installer says about it being useless.
Use the correct command prompt to build cpal and run examples. In my case, I had to run a specific command prompt, otherwise rust-bindgen would fail to find some of the necessary build tools. To do this, I went to the Start Menu > Visual C++ Build Tools > Visual C++ 2015 x64 Native Build Tools Command Prompt and ran this prompt. The exact prompt you need might differ based on your machine's architecture and how you installed your Visual C++ tools. There must be an easier solution to this (especially as not everyone wants to build projects from the command line).
TODO how to choose between ASIO and WDM in CPAL. Related to #9.

mitchmindtree commented 5 years ago

Reminder - Remove the env var assignments from powershell in favour of setting them permanently in "Advanced System Settings > Environment Variables".

mitchmindtree commented 5 years ago

Add something about ASIO4ALL as an ASIO driver for testing.

mitchmindtree commented 5 years ago

Add something about selecting the correct command prompt to use for building. (fixes #7).

freesig commented 5 years ago

Just putting a note here that a gotcha will be this error:

error[E0425]: cannot find function `use_asio_backend` in module `cpal::os::windows`
 --> examples\enumerate.rs:4:24
  |
4 |     cpal::os::windows::use_asio_backend().expect("Failed to use asio");
  |                        ^^^^^^^^^^^^^^^^ did you mean `use_wasapi_backend`?

The user will need to set CPAL_ASIO_DIR and call cargo clean I'm not sure how to make this clearer because its a compile time error, which is what we want but also we can't customize the error. Probably best to mention it in the guide though

freesig commented 5 years ago

VCVARS

This is a little complex. So to get the environment variables we can just run: "C:\Program Files (x86)\Microsoft Visual Studio 14.0\VC\vcvarsall.bat"" amd64 This will give the required env vars for compiling for your own system if its 64bit. The problem is you can't run this from rust because running Command::new("cmd") spawns a new cmd line and runs the script but all the environment changes are lost once it closes. I don't think there is a way to get hold of the process that we are being run from.

Potential solution

What we could do is just put in the docs: For 64 bit run "C:\Program Files (x86)Microsoft Visual Studio 14.0VC\vcvarsall" amd64 For 32 bit run "C:\Program Files (x86)Microsoft Visual Studio 14.0VC\vcvarsall" x86

This should get beginners going. Advanced users will modify the command for what they need ie. cross compilation etc.

mitchmindtree commented 5 years ago

What we could do is just put in the docs: For 64 bit run "C:\Program Files (x86)Microsoft Visual Studio 14.0VC\vcvarsall" amd64 For 32 bit run "C:\Program Files (x86)Microsoft Visual Studio 14.0VC\vcvarsall" x86

Are we sure that's correct for 32-bit machines? Also by "run" do we mean "run it within the command prompt that will be used to run cargo build etc"? Also, the actual env vars that it loads are for the C++ toolchain that bindgen uses right? I think it's useful to mention why they're doing it so they know where to look if it doesn't work.

mitchmindtree commented 5 years ago

@freesig I wonder if we should just run that .bat in the build script using Command before running bindgen and leave out that step altogether? You can check the target architecture using cfg(target_arch) the same way you can use target_os to determine which script to call. Here's an example of checking target_arch in nannou-package.

freesig commented 5 years ago

yeh but you can't run a bat from rust and keep the environment changes because it runs the bat in it's own cmd environment. Yep they are correct check this note the table down the bottom. Yeh you would run it before running cargo build It's required for bindgen and anything that needs to get hold of windows libraries at run time

freesig / cpal