distutils による C および C++ 拡張モジュールのビルド
****************************************************

Starting in Python 1.4, Python provides, on Unix, a special make file
for building make files for building dynamically-linked extensions and
custom interpreters.  Starting with Python 2.0, this mechanism (known
as related to Makefile.pre.in, and Setup files) is no longer
supported. Building custom interpreters was rarely used, and extension
modules can be built using distutils.

Building an extension module using distutils requires that distutils
is installed on the build machine, which is included in Python 2.x and
available separately for Python 1.5. Since distutils also supports
creation of binary packages, users don’t necessarily need a compiler
and distutils to install the extension.

distutils ベースのパッケージには、駆動スクリプト (driver script) とな
る "setup.py" が入っています。 "setup.py" は普通の Python プログラムフ
ァイルで、ほとんどの場合以下のような内容になっています:

   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])

この "setup.py" とファイル "demo.c" があるとき、以下のコマンド

   python setup.py build

を実行すると、 "demo.c" をコンパイルして、 "demo" という名前の拡張モジ
ュールを "build" ディレクトリ内に生成します。システムによってはモジュ
ールファイルは "build/lib.system" サブディレクトリに生成され、
"demo.so" や "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 of addition
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".

多くの場合、拡張モジュールのビルドはもっと複雑になります。 というのは
、プリプロセッサ定義やライブラリの追加指定が必要になることがあるからで
す。 例えば以下のファイルがその実例です。

   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

これらのコマンドラインは実演目的で書かれたものです; distutils のユーザ
は distutils が正しくコマンドを実行すると信用してください。


拡張モジュールの配布
====================

拡張モジュールをうまくビルドできたら、三通りの使い方があります。

エンドユーザは普通モジュールをインストールしようと考えます; これには、
次を実行します

   python setup.py install

モジュールメンテナはソースパッケージを作成します; これには、次を実行し
ます

   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 the
distutils documentation for details.

ソースコード配布物をうまく構築できたら、メンテナはバイナリ配布物も作成
できます。プラットフォームに応じて、以下のコマンドのいずれかを使います
。

   python setup.py bdist_wininst
   python setup.py bdist_rpm
   python setup.py bdist_dumb
