[Doc] Installation guide (dmlc#223)

* docstrings for graph mutation & queries * [Doc] contrib.sampler. (dmlc#200) * subgraph docs * updates * added installation guide * style fix * package name fixes * adding it back... * fix as requested * adding link * mac os build instructions * OS -> macOS
cxncu001 · Dec 3, 2018 · 419ffbd · 419ffbd
1 parent b0c76d4
commit 419ffbd
Showing 1 changed file with 130 additions and 52 deletions.
diff --git a/docs/source/install/index.rst b/docs/source/install/index.rst
@@ -1,94 +1,172 @@
 Install DGL
 ============
 
-At this stage, we recommend installing DGL from source. To quickly try out DGL and its demo/tutorials, checkout `Install from docker`_.
+At this stage, we recommend installing DGL from ``conda`` or ``pip``.
 
-Get source codes
-----------------
-First, download the source files from github. Note you need to use the ``--recursive`` option to
-also clone the submodules.
+System requirements
+-------------------
+Currently DGL is tested on
+
+* Ubuntu 16.04
+* macOS X
+* Windows 7
+
+DGL is expected to work on all Linux distributions later than Ubuntu 16.04, macOS X, and
+Windows 7 or later.
+
+DGL also requires the Python version to be 3.5 or later.  Python 3.4 or less is not
+tested, and Python 2 support is coming.
+
+DGL supports multiple tensor libraries (e.g. PyTorch, MXNet) as backends; refer
+`Working with different backends`_ for requirements on backends and how to select a
+backend.
+
+Install from conda
+----------------------
+One can either grab `miniconda <https://conda.io/miniconda.html>`_ or
+the full `anaconda <https://www.anaconda.com/download/>`_ if ``conda``
+has not been installed.
+
+Once the conda environment is activated, run
 
 .. code:: bash
 
-    git clone --recursive https://github.com/jermainewang/dgl.git
+   conda install -c dglteam dgl
 
-You can also clone the repository first and type following commands:
+Install from pip
+----------------
+One can simply run the following command to install via ``pip``:
 
 .. code:: bash
 
-    git submodule init
-    git submodule update
+   pip install dgl
+
+Working with different backends
+-------------------------------
+
+Currently DGL supports PyTorch and MXNet.
+
+Switching backend
+`````````````````
+
+The backend is controlled by ``DGLBACKEND`` environment variable, which defaults to
+``pytorch``.  Currently it supports the following values:
+
++---------+---------+--------------------------------------------------+
+| Value   | Backend | Memo                                             |
++=========+=========+==================================================+
+| pytorch | PyTorch | Requires 0.4.1 or later; see                     |
+|         |         | `official website <https://pytorch.org>`_        |
++---------+---------+--------------------------------------------------+
+| mxnet   | MXNet   | Requires nightly build; run the following        |
+|         |         | command to install (TODO):                       |
+|         |         |                                                  |
+|         |         | .. code:: bash                                   |
+|         |         |                                                  |
+|         |         |    pip install --pre mxnet                       |
++---------+---------+--------------------------------------------------+
+| numpy   | NumPy   | Does not support gradient computation            |
++---------+---------+--------------------------------------------------+
+
+Install from source
+-------------------
+First, download the source files from GitHub:
+
+.. code:: bash
 
+   git clone --recursive https://github.com/jermainewang/dgl.git
 
-Build shared library
---------------------
-Before building the library, please make sure the following dependencies are installed
-(use ubuntu as an example):
+One can also clone the repository first and run the following:
 
 .. code:: bash
 
-    sudo apt-get update
-    sudo apt-get install -y python
+   git submodule init
+   git submodule update
+
+Linux
+`````
 
-We use cmake (minimal version 2.8) to build the library.
+Install the system packages for building the shared library, for Debian/Ubuntu
+users, run:
 
 .. code:: bash
 
-    mkdir build
-    cd build
-    cmake ..
-    make -j4
+   sudo apt-get update
+   sudo apt-get install -y build-essential build-dep python3-dev make cmake
 
-Build python binding
---------------------
-DGL's python binding depends on following packages (tested version):
+For Fedora/RHEL/CentOS users, run:
 
-* numpy (>= 1.14.0)
-* scipy (>= 1.1.0)
-* networkx (>= 2.1)
+.. code:: bash
+
+   sudo yum install -y gcc-c++ python3-devel make cmake
 
-To install them, use following command:
+Build the shared library and install the Python binding afterwards:
 
 .. code:: bash
 
-    pip install --user numpy scipy networkx
+   mkdir build
+   cd build
+   cmake ..
+   make -j4
+   cd ../python
+   python setup.py install
+
+macOS
+`````
+
+Installation on macOS is similar to Linux. But macOS users need to install
+building tools like clang, GNU Make, cmake first.
 
-There are several ways to setup DGL's python binding. We recommend developers at the current stage
-use environment variables to find python packages.
+Tools like clang and GNU Make are packaged in **Command Line Tools** for macOS. To
+install:
 
 .. code:: bash
 
-    export DGL_HOME=/path/to/dgl
-    export PYTHONPATH=${DGL_HOME}/python:${PYTHONPATH}
-    export DGL_LIBRARY_PATH=${DGL_HOME}/build
+   xcode-select --install
 
-The ``DGL_LIBRARY_PATH`` variable is used for our python package to locate the shared library
-built above. Use following command to test whether the installation is successful or not.
+To install other needed packages like cmake, we recommend first installing
+**Homebrew**, which is a popular package manager for macOS. Detailed
+instructions can be found on its `homepage <https://brew.sh/>`_.
+
+After installation of Homebrew, install cmake by:
 
 .. code:: bash
 
-    python -c 'import dgl'
+   brew install cmake
 
-Install from docker
--------------------
-TBD
+Then go to root directory of DGL repository, build shared library and
+install Python binding for DGL:
+
+.. code:: bash
 
-Install on Windows/MinGW
-------------------------
-Make sure you have the following installed:
+   mkdir build
+   cd build
+   cmake ..
+   make -j4
+   cd ../python
+   python setup.py install
 
-* CMake
-* MinGW/GCC (G++)
-* MinGW/Make
+We tested installation on macOS X with clang 10.0.0, GNU Make 3.81, and cmake
+3.13.1.
 
-You can grab them from Anaconda.
+Windows
+```````
 
-In the command line prompt, run:
+Currently Windows source build is tested with CMake and MinGW/GCC.  We highly recommend
+using CMake and GCC from `conda installations <https://conda.io/miniconda.html>`_.  To
+do so, run
 
 .. code:: bash
 
-    md build
-    cd build
-    cmake -DCMAKE_CXX_FLAGS="-DDMLC_LOG_STACK_TRACE=0 -DTVM_EXPORTS" -DCMAKE_MAKE_PROGRAM=mingw32-make .. -G "MSYS Makefiles"
-    mingw32-make
-    set DGL_LIBRARY_PATH=%CD%
+   conda install cmake m2w64-gcc m2w64-make
+
+Then build the shared library and install the Python binding:
+
+.. code::
+
+   md build
+   cd build
+   cmake -DCMAKE_CXX_FLAGS="-DDMLC_LOG_STACK_TRACE=0 -DTVM_EXPORTS" -DCMAKE_MAKE_PROGRAM=mingw32-make .. -G "MSYS Makefiles"
+   mingw32-make
+   cd ..\python
+   python setup.py install