4. C および C++ 拡張のビルド
****************************

CPython の C 拡張は *初期化関数* をエクスポートした共有ライブラリ (例
、 Linux の ".so" ファイルや Windows の ".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>" はハイフンをアンダースコア
で置き換えて Python の *punycode* エンコーディングでエンコードしたもの
になります。 Python で書くと次のような処理になります:

   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

1つの共有ライブラリに複数の初期化関数を定義することで、複数のモジュー
ルをエクスポートすることは可能です。 しかし、デフォルトではファイル名
に対応した関数しか見付けようとしないので、複数のモジュールをインポート
させるにはシンボリックリンクか独自のインポーターを使う必要があります。
詳しいことは **PEP 489** の *"Multiple modules in one library"* 節を参
照してください。


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 Python モジュールの配布
(レガシーバージョン) 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 配布する
ファイルを指定する 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
