4. C와 C++ 확장 빌드하기
************************

CPython의 C 확장은 *초기화 함수*를 내보내는 공유 라이브러리입니다 (예
를 들어, 리눅스는 ".so", 윈도우는 ".pyd").

To be importable, the shared library must be available on
"PYTHONPATH", and must be named after the module name, with an
appropriate extension. When using distutils, the correct filename is
generated automatically.

초기화 함수는 다음과 같은 서명을 갖습니다:

PyObject *PyInit_modulename(void)

완전히 초기화된 모듈이나 "PyModuleDef" 인스턴스를 반환합니다. 자세한
내용은 C 모듈 초기화을 참조하십시오.

ASCII로만 이루어진 이름을 가진 모듈의 경우, 함수의 이름을
"PyInit_<modulename>"이어야 합니다. 여기서 "<modulename>"을 모듈의 이
름으로 치환합니다. 다단계 초기화를 사용할 때 ASCII가 아닌 모듈 이름이
허용됩니다. 이 경우, 초기화 함수 이름은 "PyInitU_<modulename>"이며
"<modulename>"은 파이썬의 *punycode* 인코딩으로 인코딩되고 하이픈을 밑
줄로 대체합니다. 파이썬에서:

   def initfunc_name(name):
       try:
           suffix = b'_' + name.encode('ascii')
       except UnicodeEncodeError:
           suffix = b'U_' + name.encode('punycode').replace(b'-', b'_')
       return b'PyInit' + suffix

여러 초기화 함수를 정의하여 단일 공유 라이브러리에서 여러 모듈을 내보
낼 수 있습니다. 그러나, 이들을 임포트 하려면 심볼릭 링크나 사용자 정의
임포터를 사용해야 합니다. 기본적으로 파일 이름에 해당하는 함수만 발견
되기 때문입니다. 자세한 내용은 **PEP 489**의 *"한 라이브러리에 여러 모
듈"* 절을 참조하십시오.


4.1. Building C and C++ Extensions with distutils
=================================================

Extension modules can be built using distutils,  which is included in
Python. Since distutils also supports creation of binary packages,
users don't necessarily need a compiler and distutils to install the
extension.

A distutils package contains a driver script, "setup.py". This is a
plain Python file, which, in the most simple case, could look like
this:

   from distutils.core import setup, Extension

   module1 = Extension('demo',
                       sources = ['demo.c'])

   setup (name = 'PackageName',
          version = '1.0',
          description = 'This is a demo package',
          ext_modules = [module1])

With this "setup.py", and a file "demo.c", running

   python setup.py build

will compile "demo.c", and produce an extension module named "demo" in
the "build" directory. Depending on the system, the module file will
end up in a subdirectory "build/lib.system", and may have a name like
"demo.so" or "demo.pyd".

In the "setup.py", all execution is performed by calling the "setup"
function. This takes a variable number of keyword arguments, of which
the example above uses only a subset. Specifically, the example
specifies meta-information to build packages, and it specifies the
contents of the package.  Normally, a package will contain additional
modules, like Python source modules, documentation, subpackages, etc.
Please refer to the distutils documentation in Distributing Python
Modules (Legacy version) to learn more about the features of
distutils; this section explains building extension modules only.

It is common to pre-compute arguments to "setup()", to better
structure the driver script. In the example above, the "ext_modules"
argument to "setup()" is a list of extension modules, each of which is
an instance of the "Extension". In the example, the instance defines
an extension named "demo" which is build by compiling a single source
file, "demo.c".

In many cases, building an extension is more complex, since additional
preprocessor defines and libraries may be needed. This is demonstrated
in the example below.

   from distutils.core import setup, Extension

   module1 = Extension('demo',
                       define_macros = [('MAJOR_VERSION', '1'),
                                        ('MINOR_VERSION', '0')],
                       include_dirs = ['/usr/local/include'],
                       libraries = ['tcl83'],
                       library_dirs = ['/usr/local/lib'],
                       sources = ['demo.c'])

   setup (name = 'PackageName',
          version = '1.0',
          description = 'This is a demo package',
          author = 'Martin v. Loewis',
          author_email = 'martin@v.loewis.de',
          url = 'https://docs.python.org/extending/building',
          long_description = '''
   This is really just a demo package.
   ''',
          ext_modules = [module1])

In this example, "setup()" is called with additional meta-information,
which is recommended when distribution packages have to be built. For
the extension itself, it specifies preprocessor defines, include
directories, library directories, and libraries. Depending on the
compiler, distutils passes this information in different ways to the
compiler. For example, on Unix, this may result in the compilation
commands

   gcc -DNDEBUG -g -O3 -Wall -Wstrict-prototypes -fPIC -DMAJOR_VERSION=1 -DMINOR_VERSION=0 -I/usr/local/include -I/usr/local/include/python2.2 -c demo.c -o build/temp.linux-i686-2.2/demo.o

   gcc -shared build/temp.linux-i686-2.2/demo.o -L/usr/local/lib -ltcl83 -o build/lib.linux-i686-2.2/demo.so

These lines are for demonstration purposes only; distutils users
should trust that distutils gets the invocations right.


4.2. Distributing your extension modules
========================================

When an extension has been successfully built, there are three ways to
use it.

End-users will typically want to install the module, they do so by
running

   python setup.py install

Module maintainers should produce source packages; to do so, they run

   python setup.py sdist

In some cases, additional files need to be included in a source
distribution; this is done through a "MANIFEST.in" file; see
Specifying the files to distribute for details.

If the source distribution has been built successfully, maintainers
can also create binary distributions. Depending on the platform, one
of the following commands can be used to do so.

   python setup.py bdist_rpm
   python setup.py bdist_dumb
