================================================================================
PyAudio Installation and Compilation Hints
================================================================================

Install PyAudio using pip on most platforms.

--------------------------------------------------------------------------------
Microsoft Windows
--------------------------------------------------------------------------------
Pip will fetch and install PyAudio pre-compiled wheels. These wheels statically
link PortAudio v19 built with the native toolchain.  They support Windows MME,
DirectSound, WASAPI, and WDM-KS, but not ASIO.

  > python -m pip install pyaudio


--------------------------------------------------------------------------------
Apple macOS
--------------------------------------------------------------------------------
Use a package manager (e.g. Homebrew) to install the PortAudio library, then
install PyAudio using pip:

  % brew install portaudio
  % pip install pyaudio


--------------------------------------------------------------------------------
Most GNU/Linux distributions
--------------------------------------------------------------------------------
Use a package manager to install PyAudio. For example, on Debian/Ubuntu:

  % sudo apt install python3-pyaudio

If the latest version of PyAudio is not available, install it using pip. pip
will download the PyAudio source and build it for your system. Be sure to
install the python and PortAudio development library first.


--------------------------------------------------------------------------------
Compiling from source (GNU/Linux, macOS, and POSIX-like platforms)
--------------------------------------------------------------------------------
For most platforms, compiling from source is similar to the
instructions above for GNU/Linux: obtain or compile PortAudio, and
then build PyAudio. To manually build PyAudio from source (rather than
relying on pip):

  % python setup.py build

You can then use pip to install PyAudio (pip install .) or create wheels.


--------------------------------------------------------------------------------
Compiling from source (Microsoft Windows & VCPKG)
--------------------------------------------------------------------------------
Microsoft provides a C/C++ package manager called vcpkg, which can install
PortAudio on Windows along with any necessary headers. You'll need a copy of
both Visual Studio with the C compilers installed, as well as vcpkg.

To install PortAudio with static linking, run:

  For 32-bit builds:
  > vcpkg install portaudio:x86-windows-static

  For 64-bit builds:
  > vcpkg install portaudio:x64-windows-static

This will place PortAudio headers and libraries into your vcpkg install folder
(assuming vcpkg.exe is in C:\vcpkg, this would be C:\vcpkg\installed).

PortAudio headers will be in
C:\vcpkg\installed\{x86,x64}-windows-static\include, and the library will be in
C:\vcpkg\installed\{x86,x64}-windows-static\lib, assuming that vcpkg has the
install root at C:\vcpkg\installed).

To build this python package with those libraries, run:
  > set VCPKG_PATH=C:\vcpkg\installed\x86-windows-static (or x64-windows-static)
  > python setup.py build

To distribute it to users as a binary wheel, run:
  > python setup.py bdist_wheel

The generated wheel will be placed in the dist folder, and can be copied to any
target machine and installed with 'pip install PYAUDIO_WHEEL.whl'.


Without VCPKG
--------------------------------------------------------------------------------
If you prefer not to use VCPKG, you can build PortAudio directly using the
standard Windows compiler chain. You will need Visual Studio with the C compiler
installed, and a copy of CMake.

Once you have the PortAudio sources, run the following from the sources
directory:

  > mkdir mybuild
  > cd mybuild
  > cmake ..                          # Generates build with default options.
                                      # You can also run cmake-gui ..
  > cmake --build . --config Release  # Build the library in release mode.

This will generate ./Release/portaudio_static_x86.lib (or
portaudio_static_x64.lib for 64-bit builds).

We can now build pyaudio. For this example, we'll assume your PortAudio sources
are in the same folder as pyaudio.

  > python setup.py build_ext `
    -I .\portaudio\include `
    -L .\portaudio\mybuild\Release `
    -l portaudio_static_x86  (or portaudio_static_x64)

To distribute it to users as a binary wheel, run:
  > python setup.py bdist_wheel

The generated wheel will be placed in the dist folder, and can be copied to any
target machine and installed with 'pip install PYAUDIO_WHEEL.whl'.
