[CustomOp] Add cpp_extension zh doc

ci_scripts/api_white_list.txt

@@ -31,4 +31,8 @@ paddle/fluid/dygraph/parallel/ParallelEnv_cn.rst
 paddle/fluid/framework/is_compiled_with_xpu_cn.rst
 paddle/fluid/framework/xpu_places_cn.rst
 paddle/fluid/core/XPUPlace_cn.rst
+paddle/utils/cpp_extension/load_cn.rst
+paddle/utils/cpp_extension/setup_cn.rst
+paddle/utils/cpp_extension/CppExtension_cn.rst
+paddle/utils/cpp_extension/CUDAExtension_cn.rst
 upgrade_guide_cn.md

doc/paddle/api/paddle/utils/Overview_cn.rst

@@ -5,10 +5,27 @@ paddle.utils
 
 paddle.utils 目录下包含飞桨框架工具类的API。具体如下：
 
+-  :ref:`自定义OP相关API <about_cpp_extension>`
 -  :ref:`工具类相关API <about_utils>`
 
 
 
+.. _about_cpp_extension:
+
+自定义OP相关API
+::::::::::::::::::::
+
+.. csv-table::
+    :header: "API名称", "API功能"
+    :widths: 10, 30
+
+    " :ref:`load <cn_api_paddle_utils_cpp_extension_load>` ", "飞桨框架一键编译自定义OP、自动生成和返回Python API的接口"
+    " :ref:`setup <cn_api_paddle_utils_cpp_extension_setup>` ", "飞桨框架编译自定义OP、并安装到site-package目录的接口"
+    " :ref:`CppExtension <cn_api_paddle_utils_cpp_extension_CppExtension>` ", "飞桨框架编译仅支持CPU的自定义OP扩展类"
+    " :ref:`CUDAExtension <cn_api_paddle_utils_cpp_extension_CUDAExtension>` ", "飞桨框架编译支持GPU的自定义OP扩展类"
+    " :ref:`get_build_directory <cn_api_paddle_utils_cpp_extension_get_build_directory>` ", "返回一键编译自定义OP的build目录"
+
+
 .. _about_utils:
 
 工具类相关API

doc/paddle/api/paddle/utils/cpp_extension/CUDAExtension_cn.rst

@@ -0,0 +1,40 @@
+.. _cn_api_paddle_utils_cpp_extension_CUDAExtension:
+
+CUDAExtension
+-------------------------------
+
+.. py:function:: paddle.utils.cpp_extension.CUDAExtension(sources, *args, **kwargs)
+
+此接口用于配置自定义 OP 的源文件信息，编译生成同时支持 CPU 和 GPU 设备上执行的算子。若要编译仅支持 CPU 设备的算子，请使用 :ref:`cn_api_paddle_utils_cpp_extension_CppExtension` 。
+
+此接口是对 Python 内建库 ``setuptools.Extension`` 的进一步封装。除了不需要显式地指定 ``name`` 参数，其他参数以及使用方式上，与原生内建库接口保持一致。
+
+**使用样例如下：**
+
+.. code-block:: text
+
+    # setup.py 
+
+    # 编译支持 CPU/GPU 的算子
+    from paddle.utils.cpp_extension import CUDAExtension, setup
+
+    setup(
+        name='custom_op',
+        ext_modules=CUDAExtension(
+            sources=['relu_op.cc', 'relu_op.cu']
+        )
+    )
+
+
+
+.. note::
+
+    搭配 ``setup`` 接口使用，编译生成的动态库名称与 :ref:`cn_api_paddle_utils_cpp_extension_setup` 接口中的 ``name`` 一致。
+
+
+
+参数：
+  - **sources** (list[str]): 用于指定自定义 OP 对应的源码文件。cpp 源文件支持 .cc、.cpp等后缀；cuda 源文件以 .cu 为后缀。
+  - **\*args, \*\*kwargs** (可选): 用于指定 Extension 的其他参数，支持的参数与 ``setuptools.Extension`` 一致。
+
+返回： ``setuptools.Extension`` 对象

doc/paddle/api/paddle/utils/cpp_extension/CppExtension_cn.rst

@@ -0,0 +1,38 @@
+.. _cn_api_paddle_utils_cpp_extension_CppExtension:
+
+CppExtension
+-------------------------------
+
+.. py:function:: paddle.utils.cpp_extension.CppExtension(sources, *args, **kwargs)
+
+此接口用于配置自定义 OP 的源文件信息，编译生成仅支持 CPU 设备上执行的算子。若要编译同时支持 GPU 设备的算子，请使用 :ref:`cn_api_paddle_utils_cpp_extension_CUDAExtension` 。
+
+此接口是对 Python 内建库 ``setuptools.Extension`` 的进一步封装。除了不需要显式地指定 ``name`` 参数，其他参数以及使用方式上，与原生内建库接口保持一致。
+
+**使用样例如下：**
+
+.. code-block:: text
+
+    # setup.py 
+
+    # 编译仅支持 CPU 的算子
+    from paddle.utils.cpp_extension import CppExtension, setup
+
+    setup(
+        name='custom_op',
+        ext_modules=CppExtension(sources=['relu_op.cc'])
+    )
+
+
+
+.. note::
+
+    搭配 ``setup`` 接口使用，编译生成的动态库名称与 :ref:`cn_api_paddle_utils_cpp_extension_setup` 接口中的 ``name`` 一致。
+
+
+
+参数：
+  - **sources** (list[str]): 用于指定自定义 OP 对应的源码文件。cpp 源文件支持 .cc、.cpp等后缀
+  - **\*args, \*\*kwargs** (可选): 用于指定 Extension 的其他参数，支持的参数与 ``setuptools.Extension`` 一致。
+
+返回： ``setuptools.Extension`` 对象

doc/paddle/api/paddle/utils/cpp_extension/get_build_directory_cn.rst

@@ -0,0 +1,20 @@
+.. _cn_api_paddle_utils_cpp_extension_get_build_directory:
+
+get_build_directory
+-------------------------------
+
+.. py:function:: paddle.utils.cpp_extension.get_build_directory()
+
+此接口返回编译自定义 OP 时生成动态链接库所在的 build 目录路径。此目录可以通过 ``export PADDLE_EXTENSION_DIR=XXX`` 来设置。若未设定，则默认使用 ``~/.cache/paddle_extension`` 作为 build 目录。
+
+
+返回：编译自定义 OP 的 build 目录路径。
+
+**代码示例**：
+
+.. code-block:: python
+
+    from paddle.utils.cpp_extension import get_build_directory
+
+    build_dir = get_build_directory()
+    print(build_dir)

doc/paddle/api/paddle/utils/cpp_extension/load_cn.rst

@@ -0,0 +1,54 @@
+.. _cn_api_paddle_utils_cpp_extension_load:
+
+load
+-------------------------------
+
+.. py:function:: paddle.utils.cpp_extension.load(name, sources, extra_cxx_cflags=None, extra_cuda_cflags=None, extra_ldflags=None, extra_include_paths=None, build_directory=None, interpreter=None, verbose=False)
+
+此接口将即时编译（Just-In-Time）传入的自定义 OP 对应的 cpp 和 cuda 源码文件，返回一个包含自定义算子 API 的 ``Module`` 对象。
+
+其通过子进程的方式，在后台隐式地执行源码文件编译、符号链接、动态库生成、组网 API 接口生成等一系列过程。不需要本地预装 CMake 或者 Ninja 等工具命令，仅需必要的编译器命令环境，如 Linux 下需安装版本不低于 5.4 的 GCC，并软链到 ``/usr/bin/cc`` ；若编译支持 GPU 设备的算子，则需要预装 ``nvcc`` 编译环境。
+
+同时，编译前会执行 `ABI 兼容性检查 <https://gcc.gnu.org/onlinedocs/libstdc++/manual/abi.html>`_ ，即检查 ``cc`` 命令对应的 GCC 版本是否与编译本地安装的 Paddle 时的 GCC 版本一致。如对于 CUDA 10.1 以上的 Paddle 默认使用 GCC 8.2 编译，则本地 ``cc`` 对应的编译器版本也需为 8.2 ，否则可能由于 ABI 兼容性原因引发自定义 OP 执行期报错。
+
+相对于 :ref:`cn_api_paddle_utils_cpp_extension_setup` 的方式，此接口不需要额外的 ``setup.py`` 文件和  ``python setup.py install`` 命令，``load``  接口包含了一键执行自定义 OP 的编译和加载的全部流程。
+
+.. note::
+
+    1. 编译器的 ABI 兼容性是向前兼容的，Linux 下推荐使用 GCC 8.2 高版本作为 ``/usr/bin/cc`` 命令的软链对象。
+    2. Linux 下可通过 ``which cc`` 查看 ``cc`` 命令的位置；使用 ``cc --version`` 查看对应的 GCC 版本。
+    3. 目前支持 Linux 和 Windows 平台， MacOS 平台正在支持中。
+
+
+**使用样例如下：**
+
+.. code-block:: text
+
+   import paddle
+   from paddle.utils.cpp_extension import load
+
+   custom_op_module = load(
+       name="op_shared_libary_name",                # 生成动态链接库的名称
+       sources=['relu_op.cc', 'relu_op.cu'],        # 自定义 OP 的源码文件列表
+       extra_cxx_cflags=['-DPADDLE_WITH_MKLDNN'],   # 如预装的 Paddle 支持 MKLDNN，需指定此 flag
+       extra_cuda_cflags=['-DPADDLE_WITH_MKLDNN'],  # 如预装的 Paddle 支持 MKLDNN，需指定此 flag
+       interpreter='python3.7',                     # 可指定使用其他 python 解释器路径
+       verbose=True                                 # 打印编译过程中的日志信息
+   )
+
+   x = paddle.randn([4, 10], dtype='float32')
+   out = custom_op_module.relu(x)
+
+
+参数：
+  - **name** (str): 用于指定编译自定义 OP 时，生成的动态链接库的名字，不包括后缀如 .so 或者 .dll
+  - **sources** (list[str]): 用于指定自定义 OP 对应的源码文件。cpp 源文件支持 .cc、.cpp 等后缀；cuda 源文件以 .cu 为后缀。
+  - **extra_cxx_cflags** (list[str], 可选): 用于指定编译 cpp 源文件时额外的编译选项。默认情况下，Paddle 框架相关的必要选项均已被隐式地包含；若预装的 Paddle 是支持 MKLDNN 的，则需要在此参数中额外指定 ``-DPADDLE_WITH_MKLDNN`` 。默认值为 None 。
+  - **extra_cuda_cflags** (list[str], 可选): 用于指定编译 cuda 源文件时额外的编译选项。默认情况下，Paddle 框架相关的必要选项均已被隐式地包含；若预装的 Paddle 是支持 MKLDNN 的，则需要在此参数中额外指定 ``-DPADDLE_WITH_MKLDNN`` 。 ``nvcc`` 相关的编译选项请参考： `CUDA Compiler Driver NVCC <https://docs.nvidia.com/cuda/cuda-compiler-driver-nvcc/index.html>`_ 。 默认值为 None 。
+  - **extra_ldflags** (list[str], 可选): 用于指定编译自定义 OP 时额外的链接选项。GCC 支持的链接选项请参考： `GCC Link Options <https://gcc.gnu.org/onlinedocs/gcc/Link-Options.html>`_ 。 默认值为 None 。
+  - **extra_include_paths** (list[str], 可选): 用于指定编译 cpp 或 cuda 源文件时，额外的头文件搜索目录。默认情况下，Paddle 框架相关头文件所在目录 ``site-packages/paddle/include`` 已被隐式地包含。默认值为 None 。
+  - **build_directory** (str, 可选): 用于指定存放生成动态链接库的目录。若为 None， 则会使用环境变量 ``PADDLE_EXTENSION_DIR`` 的值作为默认的存放目录。可使用 :ref:`cn_api_paddle_utils_cpp_extension_get_build_directory` 接口查看当前的目录设置。默认值为 None 。
+  - **interpreter** (str, 可选): 用于指定执行即时编译所需要的解释器的路径，支持别名和完整路径，默认值为 ``python`` 。若用户本地包含多个版本的 python 环境，需要确保默认的 ``python`` 命令与当前解释器一致，否则需要指定此参数。如当前为 python3.7 环境，可设置此参数为 ``'python3.7'`` 。默认值为 None 。
+  - **verbose** (str, 可选): 用于指定是否需要输出编译过程中的日志信息，默认为 False。
+
+返回： 包含自定义 OP 的可调用 Module 对象。

doc/paddle/api/paddle/utils/cpp_extension/setup_cn.rst

@@ -0,0 +1,69 @@
+.. _cn_api_paddle_utils_cpp_extension_setup:
+
+setup
+-------------------------------
+
+.. py:function:: paddle.utils.cpp_extension.setup(**attr)
+
+此接口用于配置如何编译自定义 OP 源文件，包括编译动态库，自动地生成 Python API 并以 Module 的形式安装到 site-packages 目录等过程。编译完成后，支持通过 ``import`` 语句导入使用。
+
+此接口是对 Python 内建库中的 ``setuptools.setup`` 接口的进一步封装，支持的参数类型，以及使用方式均与原生接口保持一致。接口隐藏了 Paddle 框架内部概念，如默认需要指定的编译选项，头文件搜索目录，链接选项等；此接口会自动搜索和检查本地的 ``cc`` 和 ``nvcc`` 编译命令和版本环境，根据用户指定的 ``Extension`` 类型，完成支持 CPU 或 GPU 设备的算子编译。 
+
+同时，编译前会执行 `ABI 兼容性检查 <https://gcc.gnu.org/onlinedocs/libstdc++/manual/abi.html>`_ ，即检查 ``cc`` 命令对应的 GCC 版本是否与编译本地安装的 Paddle 时的 GCC 版本一致。如对于 CUDA 10.1 以上的 Paddle 默认使用 GCC 8.2 编译，则本地 ``cc`` 对应的编译器版本也需为 8.2 ，否则可能由于 ABI 兼容性原因引发自定义 OP 执行期报错。
+
+相对于即时编译的 :ref:`cn_api_paddle_utils_cpp_extension_load` 接口，此接口仅需执行一次 ``python setup.py install`` 命令，即可像其他 python 库一样 import 导入使用。如下是一个 ``setup.py`` 文件的简单样例:
+
+
+.. note::
+
+    1. 编译器的 ABI 兼容性是向前兼容的，Linux 下推荐使用 GCC 8.2 高版本作为 ``/usr/bin/cc`` 命令的软链对象。
+    2. Linux 下可通过 ``which cc`` 查看 ``cc`` 命令的位置；使用 ``cc --version`` 查看对应的 GCC 版本。
+    3. 目前支持 Linux 和 Windows 平台， MacOS 平台正在支持中。
+
+.. code-block:: text
+
+    # setup.py 
+
+    # 方式一：编译支持 CPU 和 GPU 的算子
+    from paddle.utils.cpp_extension import CUDAExtension, setup
+
+    setup(
+        name='custom_op',  # package 的名称，用于 import
+        ext_modules=CUDAExtension(
+            sources=['relu_op.cc', 'relu_op.cu', 'tanh_op.cc', 'tanh_op.cu']  # 支持同时编译多个 OP
+        )
+    )
+
+    # 方式二：编译支持仅 CPU 的算子
+    from paddle.utils.cpp_extension import CppExtension, setup
+
+    setup(
+        name='custom_op',  # package 的名称，用于 import
+        ext_modules=CppExtension(
+            sources=['relu_op.cc', 'tanh_op.cc']  # 支持同时编译多个 OP
+        )
+    )
+
+
+
+在源文件所在目录下执行 ``python setup.py install`` 即可完成自定义 OP 编译和 ``custom_op`` 库的安装。在组网时，可以通过如下方式使用：
+
+.. code-block:: text
+
+    import paddle
+    from custom_op import relu, tanh
+
+    x = paddle.randn([4, 10], dtype='float32')
+    relu_out = relu(x)
+    tanh_out = tanh(x)
+
+
+
+参数：
+  - **name** (string) - 用于指定生成的动态链接库的名称，以及安装到 site-packages 的 ``Module`` 名字
+  - **ext_modules** (Extension): 用于指定包含自定义 OP 必要源文件、编译选项等信息的 ``Extension`` 。若只编译运行在 CPU 设备上的 OP，请使用 :ref:`cn_api_paddle_utils_cpp_extension_CppExtension` ; 若编译同时支持 GPU 设备上的 OP， 请使用 :ref:`cn_api_paddle_utils_cpp_extension_CUDAExtension` 。
+  - **include_dirs** (list[str], 可选): 用于指定编译自定义 OP 时额外的头文件搜索目录。此接口默认会自动添加 ``site-packages/paddle/include`` 目录。若自定义 OP 源码引用了其他三方库文件，可以通过此参数指定三方库的搜索目录。默认值为 None 。
+  - **extra_compile_args** (list[str] | dict, 可选): 用于指定编译自定义 OP 时额外的编译选项，如 ``-O3`` 等。若为 ``list[str]`` 类型，则表示这些编译选项会同时应用到 ``cc`` 和 ``nvcc`` 编译过程；可以通过 ``{'cxx': [...], 'nvcc': [...]}`` 字典的形式单独指定额外的 ``cc`` 或 ``nvcc`` 的编译选项。默认值为 None 。
+  - **\*\*attr** (dict, 可选) - 其他参数与 ``setuptools.setup`` 一致。
+
+返回：None