Add installation / build instruction to doc (#3038)

Summary:
Add a section about installation/build

https://output.circle-artifacts.com/output/job/f121cd38-68f3-47a3-ac29-c7b0cfe94c77/artifacts/0/docs/installation.html
<img width="1102" alt="Screenshot 2023-02-06 at 6 13 50 PM" src="https://user-images.githubusercontent.com/855818/217108551-622b117b-209e-4776-b5d6-d6934c8126a4.png">

https://output.circle-artifacts.com/output/job/f121cd38-68f3-47a3-ac29-c7b0cfe94c77/artifacts/0/docs/build.html
<img width="1072" alt="Screenshot 2023-02-06 at 6 13 57 PM" src="https://user-images.githubusercontent.com/855818/217108568-c125cdc2-9d6a-4c1d-a155-2cee40c9dac6.png">

Pull Request resolved: https://github.com/pytorch/audio/pull/3038

Reviewed By: hwangjeff, nateanl

Differential Revision: D43083469

Pulled By: mthrok

fbshipit-source-id: e0b5b76dbf706552dd60ae26ea40ebc98627e3b0

docs/source/build.jetson.rst

+Building on Jetson
+==================
+
+1. Install JetPack
+------------------
+
+JetPack includes the collection of CUDA-related libraries that is required to run PyTorch with CUDA.
+
+Please refer to https://developer.nvidia.com/embedded/learn/get-started-jetson-agx-orin-devkit for the up-to-date instruction.
+
+.. code-block::
+
+   sudo bash -c 'echo "deb https://repo.download.nvidia.com/jetson/common r34.1 main" >> /etc/apt/sources.list.d/nvidia-l4t-apt-source.list'
+   sudo bash -c 'echo "deb https://repo.download.nvidia.com/jetson/t234 r34.1 main" >> /etc/apt/sources.list.d/nvidia-l4t-apt-source.list'
+
+   sudo apt update
+   sudo apt dist-upgrade
+
+   # REBOOT
+
+   sudo apt install nvidia-jetpack
+
+Checking the versions
+~~~~~~~~~~~~~~~~~~~~~
+
+To check the version installed you can use the following commands;
+
+.. code-block::
+
+   # JetPack
+   $ apt list --installed | grep nvidia-jetpack
+
+   nvidia-jetpack-dev/stable,now 5.0.1-b118 arm64 [installed,automatic]
+   nvidia-jetpack-runtime/stable,now 5.0.1-b118 arm64 [installed,automatic]
+   nvidia-jetpack/stable,now 5.0.1-b118 arm64 [installed]
+
+   # CUDA
+   $ apt list --installed | grep cuda-toolkit
+
+   cuda-toolkit-11-4-config-common/stable,now 11.4.243-1 all [installed,automatic]
+   cuda-toolkit-11-4/stable,now 11.4.14-1 arm64 [installed,automatic]
+   cuda-toolkit-11-config-common/stable,now 11.4.243-1 all [installed,automatic]
+   cuda-toolkit-config-common/stable,now 11.4.243-1 all [installed,automatic]
+
+   # cuDNN
+   $ apt list --installed | grep cudnn
+
+   libcudnn8-dev/stable,now 8.3.2.49-1+cuda11.4 arm64 [installed,automatic]
+   libcudnn8-samples/stable,now 8.3.2.49-1+cuda11.4 arm64 [installed,automatic]
+   libcudnn8/stable,now 8.3.2.49-1+cuda11.4 arm64 [installed,automatic]
+   nvidia-cudnn8-dev/stable,now 5.0.1-b118 arm64 [installed,automatic]
+   nvidia-cudnn8-runtime/stable,now 5.0.1-b118 arm64 [installed,automatic]
+
+.. image:: https://download.pytorch.org/torchaudio/doc-assets/jetson-package-versions.png
+   :width: 360px
+
+2. [Optional] Install jtop
+--------------------------
+
+Since Tegra GPUs are not supported by ``nvidia-smi`` command, it is recommended to isntall ``jtop``.
+
+Only super-use can install ``jtop``. So make sure to add ``-U``, so that running ``jtop`` won't require super-user priviledge.
+
+3. Install ``pip`` in user env
+------------------------------
+
+By default, ``pip`` / ``pip3`` commands use the ones from system directory ``/usr/bin/``, and its ``site-packages`` directory is protected and cannot be modified without ``sudo``.
+
+One way to workaround this is to install ``pip`` in user directory.
+
+https://forums.developer.nvidia.com/t/python-3-module-install-folder/181321
+
+.. code-block::
+
+   wget https://bootstrap.pypa.io/get-pip.py
+   python get-pip.py --user
+
+After this verify that ``pip`` command is pointing the one in user directory.
+
+.. code-block::
+
+   $ which pip
+   /home/USER/.local/bin/pip
+
+4. Install PyTorch
+------------------
+
+As of PyTorch 1.13 and torchaudio 0.13, there is no official pre-built binaries for Linux ARM64. Nidia provides custom pre-built binaries for PyTorch, which works with specific JetPack.
+
+Please refer to https://docs.nvidia.com/deeplearning/frameworks/install-pytorch-jetson-platform/index.html for up-to-date instruction on how to install PyTorch.
+
+.. code-block::
+
+   $ package=torch-1.13.0a0+340c4120.nv22.06-cp38-cp38-linux_aarch64.whl
+   $ wget "https://developer.download.nvidia.com/compute/redist/jp/v50/pytorch/${package}"
+   $ pip install --no-cache "${package}"
+
+Verify the installation by checking the version and CUDA device accessibility.
+
+.. code-block::
+
+   $ python -c '
+
+   import torch
+   print(torch.__version__)
+   print(torch.cuda.is_available())
+   print(torch.empty((1, 2), device=torch.device("cuda")))
+   '
+   1.13.0a0+410ce96a.nv22.12
+   True
+   tensor([[0., 0.]], device='cuda:0')
+
+.. image:: https://download.pytorch.org/torchaudio/doc-assets/jetson-torch.png
+   :width: 360px
+
+5. Build TorchAudio
+-------------------
+
+1. Install build tools
+~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block::
+
+   pip install cmake ninja pkg-config
+
+2. Install dependencies
+~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block::
+
+   sudo apt install ffmpeg libavformat-dev libavcodec-dev libavutil-dev libavdevice-dev libavfilter-dev
+
+3. Build TorchAudio
+~~~~~~~~~~~~~~~~~~~
+
+.. code-block::
+
+   git clone https://github.com/pytorch/audio
+   cd audio
+   USE_CUDA=1 USE_FFMPEG=1 pip install -v -e . --no-use-pep517
+
+4. Check the installation
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block::
+
+   import torchaudio
+
+   print(torchaudio.__version__)
+
+   torchaudio.utils.ffmpeg_utils.get_build_config()
+
+.. code-block::
+
+   2.0.0a0+2ead941
+   --prefix=/usr --extra-version=0ubuntu0.1 --toolchain=hardened --libdir=/usr/lib/aarch64-linux-gnu --incdir=/usr/include/aarch64-linux-gnu --arch=arm64 --enable-gpl --disable-stripping --enable-avresample --disable-filter=resample --enable-avisynth --enable-gnutls --enable-ladspa --enable-libaom --enable-libass --enable-libbluray --enable-libbs2b --enable-libcaca --enable-libcdio --enable-libcodec2 --enable-libflite --enable-libfontconfig --enable-libfreetype --enable-libfribidi --enable-libgme --enable-libgsm --enable-libjack --enable-libmp3lame --enable-libmysofa --enable-libopenjpeg --enable-libopenmpt --enable-libopus --enable-libpulse --enable-librsvg --enable-librubberband --enable-libshine --enable-libsnappy --enable-libsoxr --enable-libspeex --enable-libssh --enable-libtheora --enable-libtwolame --enable-libvidstab --enable-libvorbis --enable-libvpx --enable-libwavpack --enable-libwebp --enable-libx265 --enable-libxml2 --enable-libxvid --enable-libzmq --enable-libzvbi --enable-lv2 --enable-omx --enable-openal --enable-opencl --enable-opengl --enable-sdl2 --enable-libdc1394 --enable-libdrm --enable-libiec61883 --enable-chromaprint --enable-frei0r --enable-libx264 --enable-shared
+
+.. image:: https://download.pytorch.org/torchaudio/doc-assets/jetson-verify-build.png
+   :width: 360px

docs/source/build.linux.rst

+Building on Linux and macOS
+===========================
+
+1. Install Conda and activate conda environment
+-----------------------------------------------
+
+Please folllow the instruction at https://docs.conda.io/en/latest/miniconda.html
+
+2. Install PyTorch
+------------------
+
+Please select the version of PyTorch you want to install from https://pytorch.org/get-started/locally/
+
+Here, we install nightly build.
+
+.. code-block::
+
+   conda install pytorch -c pytorch-nightly
+
+3. Install build tools
+----------------------
+
+.. code-block::
+
+   conda install cmake ninja pkg-config
+
+4. Install external dependencies
+--------------------------------
+
+.. code-block::
+
+   conda install -c conda-forge ffmpeg
+
+5. Clone the torchaudio repository
+----------------------------------
+
+.. code-block::
+
+   git clone https://github.com/pytorch/audio
+   cd audio
+
+6. Build
+--------
+
+.. code-block::
+
+   USE_FFMPEG=1 python setup.py develop
+
+.. note::
+   Due to the complexity of build process, TorchAudio only supports in-place build.
+   To use ``pip``, please use ``--no-use-pep517`` option.
+
+   ``USE_FFMPEG=1 pip install -v -e . --no-use-pep517``

docs/source/build.rst

+Building from source
+====================
+
+TorchAudio integrates PyTorch for numerical computation and third party libraries for multimedia I/O. It requires the following tools to build from source.
+
+- `PyTorch <https://pytorch.org>`_
+- `CMake <https://cmake.org/>`_
+- `Ninja <https://ninja-build.org/>`_
+- C++ complier with C++ 17 support
+   - `GCC <https://gcc.gnu.org/>`_ (Linux)
+   - `Clang <https://clang.llvm.org/>`_ (macOS)
+   - `MSVC <https://visualstudio.microsoft.com>`_  2019 or newer (Windows)
+- `pkg-config <https://www.freedesktop.org/wiki/Software/pkg-config/>`_ (Linux/macOS, if building sox extension)
+- `CUDA toolkit <https://developer.nvidia.com/cudnn>`_ and `cuDNN <https://developer.nvidia.com/cudnn>`_ (if building CUDA extension)
+
+Most of the tools are available in `Conda <https://conda.io/>`_, so we recommend using conda.
+
+.. toctree::
+   :maxdepth: 1
+
+   build.linux
+   build.windows
+   build.jetson
+
+Customizing the build
+---------------------
+
+TorchAudio's integration with third party libraries can be enabled/disabled via
+environment variables.
+
+They can be enabled by passing ``1`` and disabled by ``0``.
+
+- ``BUILD_SOX``: Enable/disable I/O features based on libsox.
+- ``BUILD_KALDI``: Enable/disable feature extraction based on Kaldi.
+- ``BUILD_RNNT``: Enable/disable custom RNN-T loss function.
+- ``BUILD_CTC_DECODER``: Enable/disable CTC decoder based on `Flashlight Text <https://github.com/flashlight/text>`_.
+- ``USE_FFMPEG``: Enable/disable I/O features based on FFmpeg libraries.
+- ``USE_ROCM``: Enable/disable AMD ROCm support.
+- ``USE_CUDA``: Enable/disable CUDA support.
+
+For the latest configurations and their default values, please check the source code.
+https://github.com/pytorch/audio/blob/main/tools/setup_helpers/extension.py

docs/source/build.windows.rst

+Building on Windows
+===================
+
+To build TorchAudio on Windows, we need to enable C++ compiler and install build tools and runtime dependencies.
+
+We use Microsoft Visual C++ for compiling C++ and Conda for managing the other build tools and runtime dependencies.
+
+1. Install build tools
+----------------------
+
+MSVC
+~~~~
+
+Please follow the instruction at https://visualstudio.microsoft.com/downloads/, and make sure to install C++ development tools.
+
+.. note::
+
+   The official binary distribution are compiled with MSVC 2019.
+   The following section uses path from MSVC 2019 Community Edition.
+
+Conda
+~~~~~
+
+Please follow the instruction at https://docs.conda.io/en/latest/miniconda.html.
+
+2. Start the dev environment
+----------------------------
+
+In the following, we need to use C++ compiler (``cl``), and Conda package manager (``conda``).
+We also use Bash for the sake of similar experience to Linux/macOS.
+
+To do so, the following three steps are required.
+
+1. Open command prompt
+2. Enable developer environment
+3. [Optional] Launch bash
+
+|
+
+The following combination is known to work.
+
+1. Launch Anaconda3 Command Prompt.
+
+   |
+
+   .. image:: https://download.pytorch.org/torchaudio/doc-assets/windows-conda.png
+      :width: 360px
+
+   |
+
+   Please make sure that ``conda`` command is recognized.
+
+   |
+
+   .. image:: https://download.pytorch.org/torchaudio/doc-assets/windows-conda2.png
+      :width: 360px
+
+   |
+
+2. Activate dev tools by running the following command.
+
+   .. code-block::
+
+      call "C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Auxiliary\Build\vcvarsall.bat" x64
+
+   Please makes sure that ``cl`` command is recognized.
+
+   .. image:: https://download.pytorch.org/torchaudio/doc-assets/windows-msvc.png
+      :width: 360px
+
+3. [Optional] Launch bash with the following command.
+
+   If you want a similar UX as Linux/macOS, you can launch Bash. However, please note that in Bash environment, the file paths are different from native Windows style, and ``torchaudio.datasets`` module does not work.
+
+   .. code-block::
+
+      Miniconda3\Library\bin\bash.exe
+
+   .. image:: https://download.pytorch.org/torchaudio/doc-assets/windows-bash.png
+      :width: 360px
+
+3. Install PyTorch
+------------------
+
+Please refer to https://pytorch.org/get-started/locally/ for the up-to-date way to install PyTorch.
+
+The following command installs the nightly build version of PyTorch.
+
+.. code-block::
+
+   # CPU-only
+   conda install pytorch cpuonly -c pytorch-nightly
+
+   # With CUDA support
+   conda install pytorch pytorch-cuda=11.7 -c pytorch-nightly -c nvidia
+
+When installing CUDA-enabled version, it also install CUDA toolkit.
+
+4. [Optional] cuDNN
+-------------------
+
+If you intend to build CUDA-related features, please install cuDNN.
+
+Download CuDNN from https://developer.nvidia.com/cudnn, and extract files in
+the same directories as CUDA toolkit.
+
+When using conda, the directories are ``${CONDA_PREFIX}/bin``, ``${CONDA_PREFIX}/include``, ``${CONDA_PREFIX}/Lib/x64``.
+
+5. Install external dependencies
+--------------------------------
+
+.. code-block::
+
+   conda install cmake ninja
+
+.. code-block::
+
+   conda install -c conda-forge ffmpeg
+
+6. Build TorchAudio
+-------------------
+
+Now that we have everything ready, we can build TorchAudio.
+
+.. code-block::
+
+   git clone https://github.com/pytorch/audio
+   cd audio
+
+
+.. code-block::
+
+   # In Command Prompt
+   set USE_FFMPEG=1
+   python setup.py develop
+
+.. code-block::
+
+   # In Bash
+   USE_FFMPEG=1 python setup.py develop
+
+.. note::
+   Due to the complexity of build process, TorchAudio only supports in-place build.
+   To use ``pip``, please use ``--no-use-pep517`` option.
+
+   ``USE_FFMPEG=1 pip install -v -e . --no-use-pep517``
+
+[Optional] Building FFmpeg from source
+--------------------------------------
+
+The following section illustrates a way to build FFmpeg libraries from source.
+
+Conda-forge's FFmpeg package comes with support for major codecs and GPU decoders, so regular users and developers do not need to build FFmpeg from source.
+
+If you are not using Conda, then you can either find a pre-built binary distribution or build FFmpeg by yourself.
+
+Also, in case torchaudio developer needs to update and customize the CI for FFmpeg build, this section might be helpful.
+
+1. Install MSYS2
+~~~~~~~~~~~~~~~~
+
+To build FFmpeg in a way it is usable from the TorchAudio development environment, we need to build binaries native to ``MINGW64``. To do so, we need tools required by FFmpeg's build process, such as ``gcc`` and ``make``,  that work in ``MINGW64`` environment. For this purpose, we use MSYS2.
+
+FFmpeg's official documentation touches this https://trac.ffmpeg.org/wiki/CompilationGuide/MinGW
+
+Please follow the instruction at https://www.msys2.org/ to install MSYS2.
+
+2. Launch MSYS2
+~~~~~~~~~~~~~~~
+
+Use the shortcut to launch MSYS2 (MINGW64).
+
+.. image:: https://download.pytorch.org/torchaudio/doc-assets/windows-msys2.png
+   :width: 360px
+
+.. note::
+
+   The Bash environment in MSYS2 does not play well with Conda env, so do not add Conda initialization script in ``~/.bashrc`` of MSYS2 environment. (i.e. ``C:\msys2\home\USER\.bashrc``) Instead, add it in ``C:\Users\USER\.bashrc``)
+
+3. Install build tools
+~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block::
+
+   $ pacman -S mingw-w64-x86_64-gcc
+   $ pacman -S mingw-w64-x86_64-make
+   $ pacman -S mingw-w64-x86_64-yasm
+
+After the installation, you should have packages similar to the following;
+
+.. code-block::
+
+   $ pacman -Qe
+   base 2020.12-1
+   base-devel 2022.01-2
+   filesystem 2023.01-2
+   git 2.36.0-1
+   mingw-w64-x86_64-gcc-ada 11.3.0-1
+   mingw-w64-x86_64-gcc-fortran 11.3.0-1
+   mingw-w64-x86_64-gcc-libgfortran 11.3.0-1
+   mingw-w64-x86_64-gcc-objc 11.3.0-1
+   mingw-w64-x86_64-gdb 11.2-2
+   mingw-w64-x86_64-gdb-multiarch 11.2-2
+   mingw-w64-x86_64-libmangle-git 10.0.0.r14.ga08c638f8-1
+   mingw-w64-x86_64-make 4.3-1
+   mingw-w64-x86_64-pkgconf 1.8.0-2
+   mingw-w64-x86_64-tools-git 10.0.0.r14.ga08c638f8-1
+   mingw-w64-x86_64-winstorecompat-git 10.0.0.r14.ga08c638f8-1
+   mingw-w64-x86_64-yasm 1.3.0-4
+   msys2-runtime 3.4.3-5
+
+4. Build FFmpeg
+~~~~~~~~~~~~~~~
+
+Check out FFmpeg source code.
+
+.. code-block::
+
+   git clone https://github.com/ffmpeg/ffmpeg
+   cd ffmpeg
+   git checkout <VERSION>
+
+Build
+
+.. code-block::
+
+   ./configure
+   make -j
+
+If the build succeeds, ``ffmpeg.exe`` should be found in the same directory. Make sure that you can run it.
+
+5. Verify the build
+~~~~~~~~~~~~~~~~~~~
+
+Check that the resulting FFmpeg binary is accessible from Conda env
+
+Now launch a new command prompt and enable the TorchAudio development environment. Make sure that you can run the ``ffmpeg.exe`` command generated in the previous step.
+
+6. Build TorchAudio with the custom FFmpeg
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To use this FFmpeg libraries for building torchaudio, do the following;
+1. Uninstall ``ffmpeg`` package installed by conda. ``conda uninstall ffmpeg``.
+2. When building set ``FFMPEG_ROOT`` environment variable to the directory where the libraries like ``libavcodec`` are found.
+
+.. code-block::
+
+   # In Command Prompt
+   set USE_FFMPEG=1
+   set FFMPEG_ROOT=<FFMPEG_BUILD_DIR>
+   python setup.py clean develop
+
+.. code-block::
+
+   # In Bash
+   USE_FFMPEG=1 FFMPEG_ROOT=<FFMPEG_BUILD_DIR> python setup.py clean develop

docs/source/index.rst

@@ -22,6 +22,17 @@ model implementations and application components.
    logo
    references
 
+.. toctree::
+   :maxdepth: 2
+   :caption: Installation
+   :hidden:
+
+   installation
+   build
+   build.linux
+   build.windows
+   build.jetson
+
 .. toctree::
    :maxdepth: 1
    :caption: API Tutorials

docs/source/installation.rst

+Installing pre-built binaries
+=============================
+
+``torchaudio`` has binary distributions for PyPI (``pip``) and Anaconda (``conda``).
+
+Please refer to https://pytorch.org/get-started/locally/ for the details.
+
+.. note::
+
+   Each ``torchaudio`` package is compiled against specific version of ``torch``.
+   Please refer to the following table and install the correct pair of ``torch`` and ``torchaudio``.
+
+.. note::
+
+   Starting ``0.10``, torchaudio has CPU-only and CUDA-enabled binary distributions,
+   each of which requires a corresponding PyTorch distribution.
+
+.. note::
+   This software was compiled against an unmodified copy of FFmpeg (licensed under `the LGPLv2.1 <https://github.com/FFmpeg/FFmpeg/blob/a5d2008e2a2360d351798e9abe883d603e231442/COPYING.LGPLv2.1>`_), with the specific rpath removed so as to enable the use of system libraries. The LGPL source can be downloaded `here <https://github.com/FFmpeg/FFmpeg/releases/tag/n4.1.8>`_.
+
+Compatibility Matrix
+--------------------
+
+.. list-table::
+   :header-rows: 1
+
+   * - ``torch``
+     - ``torchaudio``
+     - ``python``
+   * - ``1.13.0``
+     - ``0.13.0``
+     - ``>=3.7``, ``<=3.10``
+   * - ``1.12.1``
+     - ``0.12.1``
+     - ``>=3.7``, ``<=3.10``
+   * - ``1.12.0``
+     - ``0.12.0``
+     - ``>=3.7``, ``<=3.10``
+   * - ``1.11.0``
+     - ``0.11.0``
+     - ``>=3.7``, ``<=3.9``
+   * - ``1.10.0``
+     - ``0.10.0``
+     - ``>=3.6``, ``<=3.9``
+   * - ``1.9.1``
+     - ``0.9.1``
+     - ``>=3.6``, ``<=3.9``
+   * - ``1.8.1``
+     - ``0.8.1``
+     - ``>=3.6``, ``<=3.9``
+   * - ``1.7.1``
+     - ``0.7.2``
+     - ``>=3.6``, ``<=3.9``
+   * - ``1.7.0``
+     - ``0.7.0``
+     - ``>=3.6``, ``<=3.8``
+   * - ``1.6.0``
+     - ``0.6.0``
+     - ``>=3.6``, ``<=3.8``
+   * - ``1.5.0``
+     - ``0.5.0``
+     - ``>=3.5``, ``<=3.8``
+   * - ``1.4.0``
+     - ``0.4.0``
+     - ``==2.7``, ``>=3.5``, ``<=3.8``