Skip to content

Commit

Permalink
Add build instructions doc page (#2294)
Browse files Browse the repository at this point in the history 
Summary: Pull Request resolved: #2294

Reviewed By: spcyppt

Differential Revision: D53206603

Pulled By: q10

fbshipit-source-id: cab030fe29c67a70b753ed8fe9127364dc16fdda
  • Loading branch information
@q10 @facebook-github-bot
q10 authored and facebook-github-bot committed Jan 30, 2024
1 parent 0c7fa1a commit fdc8314
Show file tree
Hide file tree
Showing 5 changed files with 208 additions and 116 deletions.
120 changes: 6 additions & 114 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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):

Expand Down Expand Up @@ -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/
192 changes: 192 additions & 0 deletions fbgemm_gpu/docs/src/fbgemm-development/BuildInstructions.rst
View file
Original file line number Diff line number Diff line change
@@ -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 <https://github.com/pytorch/FBGEMM/blob/main/.github/scripts/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 <https://github.com/asmjit/asmjit>`_.

cpuinfo
^^^^^^^

FBGEMM detects CPU instruction set support at runtime using the
`cpuinfo <https://github.com/pytorch/cpuinfo>`_ library provided by the PyTorch
project, and dispatches optimized kernels for the detected instruction set.

GoogleTest
^^^^^^^^^^

`GoogleTest <https://github.com/google/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
2 changes: 1 addition & 1 deletion fbgemm_gpu/docs/src/fbgemm_gpu-development/BuildInstructions.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 <https://github.com/pytorch/FBGEMM/blob/main/.github/scripts/setup_env.bash>`_.

The general steps for building FBGEMM_GPU are as follows:
Expand Down
2 changes: 1 addition & 1 deletion fbgemm_gpu/docs/src/fbgemm_gpu-development/InstallationInstructions.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 <https://github.com/pytorch/FBGEMM/blob/main/.github/scripts/setup_env.bash>`_.

The general steps for installing FBGEMM_GPU are as follows:
Expand Down
8 changes: 8 additions & 0 deletions fbgemm_gpu/docs/src/index.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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::
Expand Down

0 comments on commit fdc8314

Please sign in to comment.