Skip to content

Commit

Permalink
refine style
Browse files Browse the repository at this point in the history
  • Loading branch information
@Aurelius84
Aurelius84 committed Feb 24, 2021
1 parent afc8542 commit 07a80f0
Show file tree
Hide file tree
Showing 2 changed files with 81 additions and 64 deletions.
140 changes: 78 additions & 62 deletions python/paddle/utils/cpp_extension/cpp_extension.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -43,21 +43,36 @@ def setup(**attr):
"""
The interface is used to config the process of compiling customized operators,
mainly includes how to complile shared library, automatically generate python API
and install it into site-package. It supports using custom op directly using `import`
statement.
and install it into site-package. It supports using customized operators directly with
``import`` statement.
It encapsulates the python built-in `setuptools.setup` function and keeps arguments
It encapsulates the python built-in ``setuptools.setup`` function and keeps arguments
and usage same as the native interface. Meanwhile, it hiddens Paddle inner framework
concecepts, such as necessary compiling flags, included paths of head files, and linking
flags. It also will automatically search and valid local enviromment and versions of `cc` and
`nvcc` , then compiles customized operators supporting CPU or GPU device according to
specified Extension type.
flags. It also will automatically search and valid local enviromment and versions of ``cc`` and
``nvcc`` , then compiles customized operators supporting CPU or GPU device according to
the specified Extension type.
Moreover, ABI compatibility will be checked to ensure that compiler version from ``cc``
on local machine is compatible with pre-installed Paddle whl in python site-packages.
For example if Paddle with CUDA 10.1 is built with GCC 8.2, then the version of user's
local machine should satisfy GCC >= 8.2. Otherwise, a fatal error will occur because of
ABI compatibility.
.. note::
1. Compiler ABI compatibility is forward compatible. On Linux platform,
we recommend to use GCC 8.2 as soft linking condidate of ``/usr/bin/cc`` .
2. Using ``which cc`` to ensure location of ``cc`` and using ``cc --version``
to ensure linking GCC version on Linux.
3. Currenly we support Linux and Windows platfrom. MacOS is supporting...
Compared with Just-In-Time ``load`` interface, it only compiles once by executing
``python setup.py install`` . Then customized operators API will be available everywhere
after importing it.
A simple example of `setup.py` as followed:
A simple example of ``setup.py`` as followed:
.. code-block:: text
Expand All @@ -67,7 +82,7 @@ def setup(**attr):
from paddle.utils.cpp_extension import CUDAExtension, setup
setup(
name='custom_op', # name of package used by `import`
name='custom_op', # name of package used by "import"
ext_modules=CUDAExtension(
sources=['relu_op.cc', 'relu_op.cu', 'tanh_op.cc', 'tanh_op.cu'] # Support for compilation of multiple OPs
)
Expand All @@ -77,14 +92,14 @@ def setup(**attr):
from paddle.utils.cpp_extension import CppExtension, setup
setup(
name='custom_op', # name of package used by `import`
name='custom_op', # name of package used by "import"
ext_modules=CppExtension(
sources=['relu_op.cc', 'tanh_op.cc'] # Support for compilation of multiple OPs
)
)
Applying compilation and installation by execting `python setup.py install` under source files directory.
Applying compilation and installation by execting ``python setup.py install`` under source files directory.
Then we can use the layer api as followed:
.. code-block:: text
Expand All @@ -98,17 +113,17 @@ def setup(**attr):
Args:
name(str): Specify the name of shared library file and installing python package.
name(str): Specify the name of shared library file and installed python package.
ext_modules(Extension): Specify the Extension instance including customized operator source files, compiling flags et.al.
If only compile operator supporting CPU device, please use `CppExtension` ; If compile operator
supporting CPU and GPU devices, please use `CUDAExtension` .
include_dirs(list[str], optional): Specify the extra include directoies to search head files. The interface will automatically expand
`site-package/paddle/include`. Please add the corresponding directory path if including third-party
If only compile operator supporting CPU device, please use ``CppExtension`` ; If compile operator
supporting CPU and GPU devices, please use ``CUDAExtension`` .
include_dirs(list[str], optional): Specify the extra include directoies to search head files. The interface will automatically add
``site-package/paddle/include`` . Please add the corresponding directory path if including third-party
head files.
extra_compile_args(list[str] | dict, optional): Specify the extra compiling flags such as `-O3` . If set `list[str]` , all these flags
will be applied for `cc` and `nvcc` compiler. It support specify flags only applied `cc` or `nvcc`
compiler using dict type with `{'cxx': [...], 'nvcc': [...]}` .
**attr(dict, optional): Specify other arguments same as `setuptools.setup` .
extra_compile_args(list[str] | dict, optional): Specify the extra compiling flags such as ``-O3`` . If set ``list[str]`` , all these flags
will be applied for ``cc`` and ``nvcc`` compiler. It support specify flags only applied ``cc`` or ``nvcc``
compiler using dict type with ``{'cxx': [...], 'nvcc': [...]}`` .
**attr(dict, optional): Specify other arguments same as ``setuptools.setup`` .
Returns: None
Expand Down Expand Up @@ -177,13 +192,13 @@ def setup(**attr):

def CppExtension(sources, *args, **kwargs):
"""
The interface is used to config source files of customized operators and complie
Op Kernel only supporting CPU device. Please use `CUDAExtension` if you want to
The interface is used to config source files of customized operators and complies
Op Kernel only supporting CPU device. Please use ``CUDAExtension`` if you want to
compile Op Kernel that supports both CPU and GPU devices.
It furtherly encapsulates python built-in `setuptools.Extension`.The argument and
It furtherly encapsulates python built-in ``setuptools.Extension`` .The arguments and
usage are same as the native interface, except for no need to explicitly specify
`name` .
``name`` .
**A simple example:**
Expand All @@ -202,16 +217,16 @@ def CppExtension(sources, *args, **kwargs):
.. note::
It is mainly used in ``setup`` and the nama of built shared library keeps same
as `name` argument specified in ``setup`` interface.
as ``name`` argument specified in ``setup`` interface.
Args:
sources(list[str]): Specify the C++/CUDA source files of customized operators.
*args(list[options], optional): Specify other arguments same as `setuptools.Extension` .
**kwargs(dict[option], optional): Specify other arguments same as `setuptools.Extension` .
*args(list[options], optional): Specify other arguments same as ``setuptools.Extension`` .
**kwargs(dict[option], optional): Specify other arguments same as ``setuptools.Extension`` .
Returns:
Extension: An instance of setuptools.Extension
setuptools.Extension: An instance of ``setuptools.Extension``
"""
kwargs = normalize_extension_kwargs(kwargs, use_cuda=False)
# Note(Aurelius84): While using `setup` and `jit`, the Extension `name` will
Expand All @@ -227,13 +242,13 @@ def CppExtension(sources, *args, **kwargs):

def CUDAExtension(sources, *args, **kwargs):
"""
The interface is used to config source files of customized operators and complie
Op Kernel supporting both CPU and GPU devices. Please use `CppExtension` if you want to
The interface is used to config source files of customized operators and complies
Op Kernel supporting both CPU and GPU devices. Please use ``CppExtension`` if you want to
compile Op Kernel that supports only CPU device.
It furtherly encapsulates python built-in `setuptools.Extension`.The argument and
It furtherly encapsulates python built-in ``setuptools.Extension`` .The arguments and
usage are same as the native interface, except for no need to explicitly specify
`name` .
``name`` .
**A simple example:**
Expand All @@ -247,23 +262,23 @@ def CUDAExtension(sources, *args, **kwargs):
setup(
name='custom_op',
ext_modules=CUDAExtension(
sources=['relu_op.cc', 'relu_op.cu',
sources=['relu_op.cc', 'relu_op.cu']
)
)
.. note::
It is mainly used in ``setup`` and the nama of built shared library keeps same
as `name` argument specified in ``setup`` interface.
as ``name`` argument specified in ``setup`` interface.
Args:
sources(list[str]): Specify the C++/CUDA source files of customized operators.
*args(list[options], optional): Specify other arguments same as `setuptools.Extension` .
**kwargs(dict[option], optional): Specify other arguments same as `setuptools.Extension` .
*args(list[options], optional): Specify other arguments same as ``setuptools.Extension`` .
**kwargs(dict[option], optional): Specify other arguments same as ``setuptools.Extension`` .
Returns:
Extension: An instance of setuptools.Extension
setuptools.Extension: An instance of setuptools.Extension
"""
kwargs = normalize_extension_kwargs(kwargs, use_cuda=True)
# Note(Aurelius84): While using `setup` and `jit`, the Extension `name` will
Expand Down Expand Up @@ -644,32 +659,33 @@ def load(name,
"""
An Interface to automatically compile C++/CUDA source files Just-In-Time
and return callable python function as other Paddle layers API. It will
append user defined custom op in background.
append user defined custom operators in background while building models.
It will perform compiling, linking, api generation and module loading
processes under subprocess. It does not require CMake or Ninja environment
and only g++/nvcc on Linux and clang++ on MacOS. For example it requires
GCC compiler with version is greater than 5.4 and linked into `/usr/bin/cc` .
If compiling Operators supporting GPU device, please make sure `nvcc` compiler
It will perform compiling, linking, Python API generation and module loading
processes under a individual subprocess. It does not require CMake or Ninja environment
and only ``g++/nvcc`` on Linux and clang++ on MacOS. For example it requires
GCC compiler with version is greater than 5.4 and linked into ``/usr/bin/cc`` .
If compiling Operators supporting GPU device, please make sure ``nvcc`` compiler
is installed in local environment.
Moreover, ABI compatibility will be checked to ensure that compiler version from `cc`
Moreover, ABI compatibility will be checked to ensure that compiler version from ``cc``
on local machine is compatible with pre-installed Paddle whl in python site-packages.
For example if Paddle with CUDA 10.1 is built with GCC 8.2, then the version of user's
local machine should satisfy GCC >= 8.2. Otherwise, a fatal error will occur because of
ABI compatibility.
Compared with `setup` interface, it doesn't need extra `setup.py` and excute
`python setup.py install` command. The interface contains all compiling and installing
Compared with ``setup`` interface, it doesn't need extra ``setup.py`` and excute
``python setup.py install`` command. The interface contains all compiling and installing
process underground.
.. note::
1. Compiler ABI compatibility is forward compatible. On Linux platform,
we recommend to use GCC 8.2 as soft linking condidate of `/usr/bin/cc` .
2. Using `which cc` to ensure location of ``cc`` and using ``cc --version``
we recommend to use GCC 8.2 as soft linking condidate of ``/usr/bin/cc`` .
2. Using ``which cc`` to ensure location of ``cc`` and using ``cc --version``
to ensure linking GCC version on Linux.
3. Currenly we support Linux and Windows platfrom. MacOS is supporting...
**A simple example:**
Expand All @@ -693,35 +709,35 @@ def load(name,
Args:
name(str): Specify the name of generated shared library file name, not including .so and .dll suffix.
sources(list[str]): Specify source files name of customize operators. Supporting .cc, .cpp for CPP file and .cu for CUDA file.
extra_cxx_cflags(list[str], optional): additional flags used to compile CPP files. By default
name(str): Specify the name of generated shared library file name, not including ``.so`` and ``.dll`` suffix.
sources(list[str]): Specify source files name of customized operators. Supporting ``.cc`` , ``.cpp`` for CPP file
and ``.cu`` for CUDA file.
extra_cxx_cflags(list[str], optional): Specify additional flags used to compile CPP files. By default
all basic and framework related flags have been included.
If your pre-insall Paddle supported MKLDNN, please add
'-DPADDLE_WITH_MKLDNN'. Default None.
extra_cuda_cflags(list[str], optional): Specify additional flags used to compile CUDA files. By default
all basic and framework related flags have been included.
If your pre-insall Paddle supported MKLDNN, please add
'-DPADDLE_WITH_MKLDNN'. Default None. See
https://docs.nvidia.com/cuda/cuda-compiler-driver-nvcc/index.html
``-DPADDLE_WITH_MKLDNN`` . Default None. See `Cuda Compiler Driver NVCC <https://docs.nvidia.com/cuda/cuda-compiler-driver-nvcc/index.html>`_
for details. Default None.
extra_ldflags(list[str], optional): Specify additional flags used to link shared library. See
https://gcc.gnu.org/onlinedocs/gcc/Link-Options.html for details.
`GCC Link Options <https://gcc.gnu.org/onlinedocs/gcc/Link-Options.html>`_ for details.
Default None.
extra_include_paths(list[str], optional): Specify additional include path used to search header files. By default
all basic headers are included implicitly from `site-package/paddle/include` .
all basic headers are included implicitly from ``site-package/paddle/include`` .
Default None.
build_directory(str, optional): Specify directory path to put shared library file. If set None,
it will use `PADDLE_EXTENSION_DIR` from os.environ. Use
`paddle.utils.cpp_extension.get_build_directory()` to see the location.
interpreter(str, optional): alias or full interpreter path to specific which one to use if have installed multiple.
If set None, will use `python` as default interpreter. If local environment contains
build_directory(str, optional): Specify root directory path to put shared library file. If set None,
it will use ``PADDLE_EXTENSION_DIR`` from os.environ. Use
``paddle.utils.cpp_extension.get_build_directory()`` to see the location.
interpreter(str, optional): Specify nterpreter path, supporting alias and full path.
If set None, it will use `python` as default interpreter. If local environment contains
more than one python interpreters and want to use new interpreter to apply compilation,
please specify this parameter, such as `python3.7` .
verbose(bool, optional): whether to verbose compiled log information
please specify this parameter, such as ``python3.7`` .
verbose(bool, optional): whether to verbose compiled log information.
Returns:
custom api: A callable python function with same signature as CustomOp Kernel definition.
Moudle: A callable python module contains all CustomOp Layer APIs.
"""

Expand Down
5 changes: 3 additions & 2 deletions python/paddle/utils/cpp_extension/extension_utils.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -433,14 +433,15 @@ def is_cuda_file(path):
def get_build_directory(verbose=False):
"""
Return paddle extension root directory to put shared library. It could be specified by
`export PADDLE_EXTENSION_DIR=XXX` . If not set, `~/.cache/paddle_extension` will be used
``export PADDLE_EXTENSION_DIR=XXX`` . If not set, ``~/.cache/paddle_extension`` will be used
by default.
Returns:
The root directory of compiling customized operators.
Examples:
.. code-block:: python
.. code-block:: python
from paddle.utils.cpp_extension import get_build_directory
Expand Down

0 comments on commit 07a80f0

Please sign in to comment.