Merge pull request #112 from kyamagu/feature/update-readme

Update README.md

README.md

@@ -19,29 +19,35 @@ This repository provides scripts to build wheel packages for the
 There is also a source package to customize the build process.
 
 > **Note**
-> GPU package has been supported until version 1.7.2, but is not available since version 1.7.3 due to [the PyPI limitation](https://github.com/kyamagu/faiss-wheels/issues/57).
+> GPU binary package is discontinued as of 1.7.3 release. Build a source package to support GPU features.
 
 ### Install
 
-Install a binary package by:
+Install the CPU-only binary package by:
 
 ```bash
 pip install faiss-cpu
 ```
 
-## Building source package
+Note that the package name is `faiss-cpu`.
 
-If there is a custom built faiss library in the system, build source package for
-the best performance.
+## Supporting GPU or customized build configuration
 
-### Prerequisite
+The PyPI binary package does not support GPU.
+To support GPU methods or use faiss with different build configuration, build a source package.
+For building the source package, swig 3.0.12 or later needs to be available.
+Also, there should be all the required prerequisites for building faiss itself, such as `nvcc` and CUDA toolkit.
+
+## Building faiss
 
 The source package assumes faiss is already built and installed in the system.
-Build and install the faiss library first.
+If not done so elsewhere, build and install the faiss library first.
+The following example builds and installs faiss with GPU support and avx512 instruction set.
 
 ```bash
+git clone https://github.com/facebookresearch/faiss.git
 cd faiss
-cmake . -B build -DFAISS_ENABLE_GPU=OFF -DFAISS_ENABLE_PYTHON=OFF -DFAISS_OPT_LEVEL=avx512
+cmake . -B build -DFAISS_ENABLE_GPU=ON -DFAISS_ENABLE_PYTHON=OFF -DFAISS_OPT_LEVEL=avx512
 cmake --build build --config Release -j
 cmake --install build install
 cd ..
@@ -51,21 +57,13 @@ See the official
 [faiss installation instruction](https://github.com/facebookresearch/faiss/blob/master/INSTALL.md)
 for more on how to build and install faiss.
 
-For building sdist, swig 3.0.12 or later needs to be available.
-
-### Building a source distribution
+### Building a source package
 
-The following builds and installs the faiss-cpu source package with AVX512.
+Once faiss is built and installed, build the source package.
+The following builds and installs the faiss-cpu source package with GPU and AVX512.
 
 ```bash
-export FAISS_OPT_LEVEL=avx512
-pip install --no-binary :all: faiss-cpu
-```
-
-The following example builds a GPU wheel.
-
-```bash
-export FAISS_ENABLE_GPU=ON
+export FAISS_ENABLE_GPU=ON FAISS_OPT_LEVEL=avx512
 pip install --no-binary :all: faiss-cpu
 ```
 
@@ -74,3 +72,13 @@ There are a few environment variables that specifies build-time options.
 - `FAISS_OPT_LEVEL`: Faiss SIMD optimization, one of `generic`, `avx2`, `avx512`. Note that AVX option is only available in x86_64 arch.
 - `FAISS_ENABLE_GPU`: Setting this variable to `ON` builds GPU wrappers. Set this variable if faiss is built with GPU support.
 - `CUDA_HOME`: Specifies CUDA install location for building GPU wrappers, default to `/usr/local/cuda`.
+
+## Development
+
+This repository is intended to support PyPI distribution for the official [faiss](https://github.com/facebookresearch/faiss) library.
+The repository contains the CI workflow based on [cibuildwheel](https://github.com/pypa/cibuildwheel/).
+Feel free to make a pull request to fix packaging problems.
+
+Other relevant resources:
+
+- [Packaging projects with GPU code](https://pypackaging-native.github.io/key-issues/gpus/)