From fdc83146b1ac07b65c59abc39b65b1af3898fdd1 Mon Sep 17 00:00:00 2001 From: Benson Ma Date: Tue, 30 Jan 2024 14:44:43 -0800 Subject: [PATCH] Add build instructions doc page (#2294) Summary: Pull Request resolved: https://github.com/pytorch/FBGEMM/pull/2294 Reviewed By: spcyppt Differential Revision: D53206603 Pulled By: q10 fbshipit-source-id: cab030fe29c67a70b753ed8fe9127364dc16fdda --- README.md | 120 +---------- .../fbgemm-development/BuildInstructions.rst | 192 ++++++++++++++++++ .../BuildInstructions.rst | 2 +- .../InstallationInstructions.rst | 2 +- fbgemm_gpu/docs/src/index.rst | 8 + 5 files changed, 208 insertions(+), 116 deletions(-) create mode 100644 fbgemm_gpu/docs/src/fbgemm-development/BuildInstructions.rst diff --git a/README.md b/README.md index 86c8c7efa1..77daebdcda 100644 --- a/README.md +++ b/README.md @@ -17,119 +17,19 @@ FBGEMM is used as a backend of Caffe2 and PyTorch quantized operators for x86 ma * Caffe2: https://github.com/pytorch/pytorch/tree/master/caffe2/quantization/server * PyTorch: https://github.com/pytorch/pytorch/tree/master/aten/src/ATen/native/quantized/cpu - - -## Build Instructions - -### Build with CMake - -The general instructions for building with Cmake are as follows: - -```sh -# Clone the repo -git clone --recursive https://github.com/pytorch/FBGEMM.git -cd FBGEMM - -# Pull down the submodules -git submodule sync -git submodule update --init --recursive - -# Create a build directory -mkdir build -cd build - -# Set up the build -cmake -DUSE_SANITIZER=address -DFBGEMM_LIBRARY_TYPE=shared -DPYTHON_EXECUTABLE=/usr/bin/python3 .. - -# Run the build -make -j VERBOSE=1 - -# Run all tests -make test - -# Install the package -make install -``` - -##### Build Issues with GCC 12 - -As of time of writing, compilation of FBGEMM on GCC 12 will fail due to a -[known compiler regression](https://gcc.gnu.org/bugzilla/show_bug.cgi?id=105593). -To work around the issue, simply add the following exports prior to running CMake: - -```sh -export CFLAGS+=" -Wno-error=maybe-uninitialized -Wno-error=uninitialized -Wno-error=restrict" -export CXXFLAGS+=" -Wno-error=maybe-uninitialized -Wno-error=uninitialized -Wno-error=restrict" -``` - -Please see GitHub issues [77939](https://github.com/pytorch/pytorch/issues/77939), -[1094](https://github.com/pytorch/FBGEMM/issues/1094), and -[1666](https://github.com/pytorch/FBGEMM/issues/1666) for more details. - -### Run Examples - -The tests in the `test/` directory and benchmarks in the `bench/` directory are -some great examples of using FBGEMM. For instance, the `SpMDMTest` test in -`test/PackedRequantizeAcc16Test.cc` shows how to combine row offset calculations -with packing of A (`PackAWithRowOffset`), how to pack B matrix (`PackBMatrix`) -and construct output pipeline `(sparse_matrix*dense_matrix --> requantization --> -nop)` fused with inner GEMM macro kernel. - -### Dependencies - -FBGEMM requires gcc 8+ and a CPU with support for AVX2 instruction set or -higher. It has been tested on Mac OS X and Linux. - -#### asmjit - -With inner kernels, FBGEMM takes a “one size doesn't fit all” approach, so the -implementation dynamically generates efficient matrix-shape specific vectorized -code using a third-party library called [asmjit][1]. **asmjit is required** to -build FBGEMM. - -#### cpuinfo - -FBGEMM detects CPU instruction set support at runtime using cpuinfo library and -dispatches optimized kernels for the detected instruction set. Therefore, -**cpuinfo is required** to detect CPU type. - -#### googletest - -googletest is required to build and run FBGEMM's tests. **googletest is not -required** if you don't want to run FBGEMM tests. By default, building of tests -is **on**. Turn it off by setting FBGEMM\_BUILD\_TESTS to off. - -You can download [asmjit][1], [cpuinfo][2], [googletest][3] and set -ASMJIT\_SRC\_DIR, CPUINFO\_SRC\_DIR, GOOGLETEST\_SOURCE\_DIR respectively for -cmake to find these libraries. If any of these variables is not set, cmake will -build the git submodules found in the third\_party directory. - -FBGEMM, in general, does not have any dependency on Intel MKL. However, for -performance comparison, some benchmarks use MKL functions. If MKL is found or -MKL path is provided with INTEL\_MKL\_DIR benchmarks are built with MKL and -performance numbers are reported for MKL functions as well. However, if MKL is -not found, the benchmarks are not built. - - -## Documentation - -For a high-level overview, design philosophy and brief descriptions of various -parts of FBGEMM please see [our blog post][4]. +See the full [Documentation](https://pytorch.org/FBGEMM) for more information +on building, installing, and developing with FBGEMM, as well as the most +up-to-date support matrix and API documentation for this library. ### What's New? * [New Features and Recent Improvements](https://github.com/pytorch/FBGEMM/wiki/Recent-feature-additions-and-improvements-in-FBGEMM) (January, 2020) -### API Docs - -We have extensively used comments in our source files. The best and up-do-date -documentation is available in the source files. - -You can also turn on the option to generate the documentation (using [Doxygen][5] -and [Sphinx][6] by setting the `-DFBGEMM_BUILD_DOCS=ON` flag when invoking CMake. - ### Citation +For a high-level overview, design philosophy and brief descriptions of various +parts of FBGEMM please see [our blog post](https://code.fb.com/ml-applications/fbgemm). + For those looking for the appropriate article to cite regarding FBGEMM, we recommend citing our [paper](https://arxiv.org/pdf/2101.05615.pdf): @@ -158,11 +58,3 @@ ways to help out. ## License FBGEMM is BSD licensed, as found in the [`LICENSE`](LICENSE) file. - - -[1]:https://github.com/asmjit/asmjit -[2]:https://github.com/pytorch/cpuinfo -[3]:https://github.com/google/googletest -[4]:https://code.fb.com/ml-applications/fbgemm -[5]:https://www.doxygen.nl/index.html -[6]:https://www.sphinx-doc.org/en/master/ diff --git a/fbgemm_gpu/docs/src/fbgemm-development/BuildInstructions.rst b/fbgemm_gpu/docs/src/fbgemm-development/BuildInstructions.rst new file mode 100644 index 0000000000..a0a396fed2 --- /dev/null +++ b/fbgemm_gpu/docs/src/fbgemm-development/BuildInstructions.rst @@ -0,0 +1,192 @@ +Build Instructions +================== + +**Note:** The most up-to-date build instructions are embedded in a set of +scripts bundled in the FBGEMM repo under +`setup_env.bash `_. + +The general steps for building FBGEMM_GPU are as follows: + +#. Set up an isolated build environment. +#. Set up the toolchain. +#. Run the build script. + + +FBGEMM Requirements +-------------------- + +Hardware Requirements +~~~~~~~~~~~~~~~~~~~~~ + +Building and running FBGEMM requires a CPU with support for AVX2 instruction set +or higher. + +In general, FBGEMM does not have any dependency on Intel MKL. However, for +performance comparisons, some benchmarks use MKL functions. If MKL is found or +the MKL path is provided through the ``INTEL_MKL_DIR`` environment variable, the +benchmarks will be built with MKL and performance numbers will be reported for +MKL functions. Otherwise, this subset of benchmarks will not built. + +Software Dependencies +~~~~~~~~~~~~~~~~~~~~~ + +All three dependencies are provided through the FBGEMM repo's git submodules. +However, if a custom version is desired, they can be set in the build using the +environment variables ``ASMJIT_SRC_DIR``, ``CPUINFO_SRC_DIR``, and +``GOOGLETEST_SOURCE_DIR``. + +asmjit +^^^^^^ + +With inner kernels, FBGEMM takes a "one size doesn't fit all" approach, so the +implementation dynamically generates efficient matrix-shape specific vectorized +code using a third-party library called `asmjit `_. + +cpuinfo +^^^^^^^ + +FBGEMM detects CPU instruction set support at runtime using the +`cpuinfo `_ library provided by the PyTorch +project, and dispatches optimized kernels for the detected instruction set. + +GoogleTest +^^^^^^^^^^ + +`GoogleTest `_ is required to build and +run FBGEMM's tests. However, GoogleTest is not required if you don't want to run +FBGEMM tests. Tests are built together with the library by default; to turn this +off, simply set ``FBGEMM_BUILD_TESTS=0``. + + +.. _fbgemm.build.setup.env: + +Set Up an Isolated Build Environment +------------------------------------ + +Follow the instructions for setting up the Conda environment at +:ref:`fbgemm-gpu.build.setup.env`. + + +Install the Build Tools +----------------------- + +C/C++ Compiler +~~~~~~~~~~~~~~ + +For Linux and macOS platforms, Install a version of the GCC toolchain +**that supports C++17**. The ``sysroot`` package will also need to be installed +to avoid issues with missing versioned symbols with ``GLIBCXX`` when compiling FBGEMM: + +.. code:: sh + + conda install -n "${env_name}" -y gxx_linux-64=10.4.0 sysroot_linux-64=2.17 -c conda-forge + +While newer versions of GCC can be used, binaries compiled under newer versions +of GCC will not be compatible with older systems such as Ubuntu 20.04 or CentOS +Stream 8, because the compiled library will reference symbols from versions of +``GLIBCXX`` that the system’s ``libstdc++.so.6`` will not support. To see what +versions of GLIBC and GLIBCXX the available ``libstdc++.so.6`` supports: + +.. code:: sh + + libcxx_path=/path/to/libstdc++.so.6 + + # Print supported for GLIBC versions + objdump -TC "${libcxx_path}" | grep GLIBC_ | sed 's/.*GLIBC_\([.0-9]*\).*/GLIBC_\1/g' | sort -Vu | cat + + # Print supported for GLIBCXX versions + objdump -TC "${libcxx_path}" | grep GLIBCXX_ | sed 's/.*GLIBCXX_\([.0-9]*\).*/GLIBCXX_\1/g' | sort -Vu | cat + +For builds on Windows machines, Microsoft Visual Studio 2019 or newer is +recommended. Follow the installation instructions provided by Microsoft. + +Other Build Tools +~~~~~~~~~~~~~~~~~ + +Install the other necessary build tools such as ``ninja``, ``cmake``, etc: + +.. code:: sh + + conda install -n "${env_name}" -y \ + bazel \ + cmake \ + make \ + ninja \ + openblas-dev + +Note that the `bazel` package is only necessary for Bazel builds, and the +`ninja` package is only necessary for Windows builds. + + +Build the FBGEMM Library +------------------------ + +Preparing the Build +~~~~~~~~~~~~~~~~~~~ + +Clone the repo along with its submodules: + +.. code:: sh + + # !! Run inside the Conda environment !! + + # Clone the repo and its submodules + git clone --recurse-submodules https://github.com/pytorch/FBGEMM.git + cd FBGEMM + +Building on Linux and macOS (CMake) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Assuming a Conda environment with all the tools installed, the CMake build +process is straightforward: + +.. code:: sh + + # !! Run inside the Conda environment !! + + # Create a build directory + mkdir build + cd build + + # Set up the build + # To generate Doxygen documentation, add `-DFBGEMM_BUILD_DOCS=ON` + cmake -DUSE_SANITIZER=address -DFBGEMM_LIBRARY_TYPE=shared -DPYTHON_EXECUTABLE=`which python3` .. + + # Build the library + make -j VERBOSE=1 + + # Run all tests + make test + + # Install the library + make install + +Building on Linux (Bazel) +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Likewise, a Bazel build is also very straightforward: + +.. code:: sh + + # !! Run inside the Conda environment !! + + # Build the library + bazel build -s :* + + # Run all tests + bazel test -s :* + +Building on Windows +~~~~~~~~~~~~~~~~~~~ + +.. code:: powershell + + # Specify the target architecture to bc x64 + call "C:\Program Files (x86)\Microsoft Visual Studio\2019\Enterprise\VC\Auxiliary\Build\vcvarsall.bat" x64 + + # Create a build directory + mkdir %BUILD_DIR% + cd %BUILD_DIR% + + cmake -G Ninja -DFBGEMM_BUILD_BENCHMARKS=OFF -DFBGEMM_LIBRARY_TYPE=${{ matrix.library-type }} -DCMAKE_BUILD_TYPE=Release -DCMAKE_C_COMPILER="cl.exe" -DCMAKE_CXX_COMPILER="cl.exe" .. + ninja -v all diff --git a/fbgemm_gpu/docs/src/fbgemm_gpu-development/BuildInstructions.rst b/fbgemm_gpu/docs/src/fbgemm_gpu-development/BuildInstructions.rst index c7f7e6744c..a7c8ba152c 100644 --- a/fbgemm_gpu/docs/src/fbgemm_gpu-development/BuildInstructions.rst +++ b/fbgemm_gpu/docs/src/fbgemm_gpu-development/BuildInstructions.rst @@ -2,7 +2,7 @@ Build Instructions ================== **Note:** The most up-to-date build instructions are embedded in a set of -scripts bundled in the FBGEMM_GPU repo under +scripts bundled in the FBGEMM repo under `setup_env.bash `_. The general steps for building FBGEMM_GPU are as follows: diff --git a/fbgemm_gpu/docs/src/fbgemm_gpu-development/InstallationInstructions.rst b/fbgemm_gpu/docs/src/fbgemm_gpu-development/InstallationInstructions.rst index 64bdbb50c5..0b6ea4112c 100644 --- a/fbgemm_gpu/docs/src/fbgemm_gpu-development/InstallationInstructions.rst +++ b/fbgemm_gpu/docs/src/fbgemm_gpu-development/InstallationInstructions.rst @@ -2,7 +2,7 @@ Installation Instructions ========================= **Note:** The most up-to-date installation instructions are embedded in a set -of scripts bundled in the FBGEMM_GPU repo under +of scripts bundled in the FBGEMM repo under `setup_env.bash `_. The general steps for installing FBGEMM_GPU are as follows: diff --git a/fbgemm_gpu/docs/src/index.rst b/fbgemm_gpu/docs/src/index.rst index 83e1bc58c7..36e3e3c8f0 100644 --- a/fbgemm_gpu/docs/src/index.rst +++ b/fbgemm_gpu/docs/src/index.rst @@ -31,6 +31,14 @@ Table of Contents general/ContactUs.rst general/License.rst +.. _fbgemm.toc.development: + +.. toctree:: + :maxdepth: 1 + :caption: FBGEMM Development + + fbgemm-development/BuildInstructions.rst + .. _fbgemm-gpu.toc.development: .. toctree::