{ "__type": "IngestedDoc", "__tag": 4010, "_content": {}, "_ordered_sections": [], "item_file": null, "item_line": null, "item_type": null, "aliases": [], "example_section_data": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "see_also": [], "signature": null, "references": null, "qa": "reference:distutils_guide", "arbitrary": [ { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Admonition", "__tag": 4056, "kind": "warning", "base_type": "warning", "children": [ { "__type": "AdmonitionTitle", "__tag": 4055, "children": [ { "__type": "Text", "__tag": 4046, "value": "warning " } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "numpy.distutils" }, { "__type": "Text", "__tag": 4046, "value": " is deprecated, and will be removed for Python >= 3.12. For more details, see " }, { "__type": "CrossRef", "__tag": 4002, "value": "distutils-status-migration", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "docs", "path": "reference:distutils_status_migration" }, "kind": "exists" } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Currently SciPy project consists of two packages:" } ] }, { "__type": "BulletList", "__tag": 4053, "ordered": false, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "NumPy --- it provides packages like:" } ] }, { "__type": "BulletList", "__tag": 4053, "ordered": false, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "numpy.distutils - extension to Python distutils" } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "numpy.f2py - a tool to bind Fortran/C codes to Python" } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "numpy._core - future replacement of Numeric and numarray packages" } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "numpy.lib - extra utility functions" } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "numpy.testing - numpy-style tools for unit testing" } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "etc" } ] } ] } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "SciPy --- a collection of scientific tools for Python." } ] } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The aim of this document is to describe how to add new tools to SciPy." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "SciPy consists of Python packages, called SciPy packages, that are available to Python users via the " }, { "__type": "InlineCode", "__tag": 4051, "value": "scipy" }, { "__type": "Text", "__tag": 4046, "value": " namespace. Each SciPy package may contain other SciPy packages. And so on. Therefore, the SciPy directory tree is a tree of packages with arbitrary depth and width. Any SciPy package may depend on NumPy packages but the dependence on other SciPy packages should be kept minimal or zero." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "A SciPy package contains, in addition to its sources, the following files and directories:" } ] }, { "__type": "BulletList", "__tag": 4053, "ordered": false, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "setup.py" }, { "__type": "Text", "__tag": 4046, "value": " --- building script" } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "__init__.py" }, { "__type": "Text", "__tag": 4046, "value": " --- package initializer" } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "tests/" }, { "__type": "Text", "__tag": 4046, "value": " --- directory of unittests" } ] } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Their contents are described below." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "In order to add a Python package to SciPy, its build script (" }, { "__type": "InlineCode", "__tag": 4051, "value": "setup.py" }, { "__type": "Text", "__tag": 4046, "value": ") must meet certain requirements. The most important requirement is that the package define a " }, { "__type": "InlineCode", "__tag": 4051, "value": "configuration(parent_package='',top_path=None)" }, { "__type": "Text", "__tag": 4046, "value": " function which returns a dictionary suitable for passing to " }, { "__type": "InlineCode", "__tag": 4051, "value": "numpy.distutils.core.setup(..)" }, { "__type": "Text", "__tag": 4046, "value": ". To simplify the construction of this dictionary, " }, { "__type": "InlineCode", "__tag": 4051, "value": "numpy.distutils.misc_util" }, { "__type": "Text", "__tag": 4046, "value": " provides the " }, { "__type": "InlineCode", "__tag": 4051, "value": "Configuration" }, { "__type": "Text", "__tag": 4046, "value": " class, described below." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Below is an example of a minimal " }, { "__type": "InlineCode", "__tag": 4051, "value": "setup.py" }, { "__type": "Text", "__tag": 4046, "value": " file for a pure SciPy package " } ] }, { "__type": "Code", "__tag": 4050, "value": "#!/usr/bin/env python3\ndef configuration(parent_package='',top_path=None):\n from numpy.distutils.misc_util import Configuration\n config = Configuration('mypackage',parent_package,top_path)\n return config\n\nif __name__ == \"__main__\":\n from numpy.distutils.core import setup\n #setup(**configuration(top_path='').todict())\n setup(configuration=configuration)", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The arguments of the " }, { "__type": "InlineCode", "__tag": 4051, "value": "configuration" }, { "__type": "Text", "__tag": 4046, "value": " function specify the name of parent SciPy package (" }, { "__type": "InlineCode", "__tag": 4051, "value": "parent_package" }, { "__type": "Text", "__tag": 4046, "value": ") and the directory location of the main " }, { "__type": "InlineCode", "__tag": 4051, "value": "setup.py" }, { "__type": "Text", "__tag": 4046, "value": " script (" }, { "__type": "InlineCode", "__tag": 4051, "value": "top_path" }, { "__type": "Text", "__tag": 4046, "value": "). These arguments, along with the name of the current package, should be passed to the " }, { "__type": "InlineCode", "__tag": 4051, "value": "Configuration" }, { "__type": "Text", "__tag": 4046, "value": " constructor." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The " }, { "__type": "InlineCode", "__tag": 4051, "value": "Configuration" }, { "__type": "Text", "__tag": 4046, "value": " constructor has a fourth optional argument, " }, { "__type": "InlineCode", "__tag": 4051, "value": "package_path" }, { "__type": "Text", "__tag": 4046, "value": ", that can be used when package files are located in a different location than the directory of the " }, { "__type": "InlineCode", "__tag": 4051, "value": "setup.py" }, { "__type": "Text", "__tag": 4046, "value": " file." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Remaining " }, { "__type": "InlineCode", "__tag": 4051, "value": "Configuration" }, { "__type": "Text", "__tag": 4046, "value": " arguments are all keyword arguments that will be used to initialize attributes of " }, { "__type": "InlineCode", "__tag": 4051, "value": "Configuration" }, { "__type": "Text", "__tag": 4046, "value": " instance. Usually, these keywords are the same as the ones that " }, { "__type": "InlineCode", "__tag": 4051, "value": "setup(..)" }, { "__type": "Text", "__tag": 4046, "value": " function would expect, for example, " }, { "__type": "InlineCode", "__tag": 4051, "value": "packages" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "ext_modules" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "data_files" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "include_dirs" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "libraries" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "headers" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "scripts" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "package_dir" }, { "__type": "Text", "__tag": 4046, "value": ", etc. However, the direct specification of these keywords is not recommended as the content of these keyword arguments will not be processed or checked for the consistency of SciPy building system." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Finally, " }, { "__type": "InlineCode", "__tag": 4051, "value": "Configuration" }, { "__type": "Text", "__tag": 4046, "value": " has " }, { "__type": "InlineCode", "__tag": 4051, "value": ".todict()" }, { "__type": "Text", "__tag": 4046, "value": " method that returns all the configuration data as a dictionary suitable for passing on to the " }, { "__type": "InlineCode", "__tag": 4051, "value": "setup(..)" }, { "__type": "Text", "__tag": 4046, "value": " function." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "In addition to attributes that can be specified via keyword arguments to " }, { "__type": "InlineCode", "__tag": 4051, "value": "Configuration" }, { "__type": "Text", "__tag": 4046, "value": " constructor, " }, { "__type": "InlineCode", "__tag": 4051, "value": "Configuration" }, { "__type": "Text", "__tag": 4046, "value": " instance (let us denote as " }, { "__type": "InlineCode", "__tag": 4051, "value": "config" }, { "__type": "Text", "__tag": 4046, "value": ") has the following attributes that can be useful in writing setup scripts:" } ] }, { "__type": "BulletList", "__tag": 4053, "ordered": false, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "config.name" }, { "__type": "Text", "__tag": 4046, "value": " - full name of the current package. The names of parent packages can be extracted as " }, { "__type": "InlineCode", "__tag": 4051, "value": "config.name.split('.')" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "config.local_path" }, { "__type": "Text", "__tag": 4046, "value": " - path to the location of current " }, { "__type": "InlineCode", "__tag": 4051, "value": "setup.py" }, { "__type": "Text", "__tag": 4046, "value": " file." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "config.top_path" }, { "__type": "Text", "__tag": 4046, "value": " - path to the location of main " }, { "__type": "InlineCode", "__tag": 4051, "value": "setup.py" }, { "__type": "Text", "__tag": 4046, "value": " file." } ] } ] } ] }, { "__type": "BulletList", "__tag": 4053, "ordered": false, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "config.todict()" }, { "__type": "Text", "__tag": 4046, "value": " --- returns configuration dictionary suitable for passing to " }, { "__type": "InlineCode", "__tag": 4051, "value": "numpy.distutils.core.setup(..)" }, { "__type": "Text", "__tag": 4046, "value": " function." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "config.paths(*paths) --- applies ``glob.glob(..)" }, { "__type": "Text", "__tag": 4046, "value": " to items of " }, { "__type": "InlineCode", "__tag": 4051, "value": "paths" }, { "__type": "Text", "__tag": 4046, "value": " if necessary. Fixes " }, { "__type": "InlineCode", "__tag": 4051, "value": "paths" }, { "__type": "Text", "__tag": 4046, "value": " item that is relative to " }, { "__type": "InlineCode", "__tag": 4051, "value": "config.local_path" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "config.get_subpackage(subpackage_name,subpackage_path=None)" }, { "__type": "Text", "__tag": 4046, "value": " --- returns a list of subpackage configurations. Subpackage is looked in the current directory under the name " }, { "__type": "InlineCode", "__tag": 4051, "value": "subpackage_name" }, { "__type": "Text", "__tag": 4046, "value": " but the path can be specified also via optional " }, { "__type": "InlineCode", "__tag": 4051, "value": "subpackage_path" }, { "__type": "Text", "__tag": 4046, "value": " argument. If " }, { "__type": "InlineCode", "__tag": 4051, "value": "subpackage_name" }, { "__type": "Text", "__tag": 4046, "value": " is specified as " }, { "__type": "InlineCode", "__tag": 4051, "value": "None" }, { "__type": "Text", "__tag": 4046, "value": " then the subpackage name will be taken the basename of " }, { "__type": "InlineCode", "__tag": 4051, "value": "subpackage_path" }, { "__type": "Text", "__tag": 4046, "value": ". Any " }, { "__type": "InlineCode", "__tag": 4051, "value": "*" }, { "__type": "Text", "__tag": 4046, "value": " used for subpackage names are expanded as wildcards." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "config.add_subpackage(subpackage_name,subpackage_path=None)" }, { "__type": "Text", "__tag": 4046, "value": " --- add SciPy subpackage configuration to the current one. The meaning and usage of arguments is explained above, see " }, { "__type": "InlineCode", "__tag": 4051, "value": "config.get_subpackage()" }, { "__type": "Text", "__tag": 4046, "value": " method." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "config.add_data_files(*files)" }, { "__type": "Text", "__tag": 4046, "value": " --- prepend " }, { "__type": "InlineCode", "__tag": 4051, "value": "files" }, { "__type": "Text", "__tag": 4046, "value": " to " }, { "__type": "InlineCode", "__tag": 4051, "value": "data_files" }, { "__type": "Text", "__tag": 4046, "value": " list. If " }, { "__type": "InlineCode", "__tag": 4051, "value": "files" }, { "__type": "Text", "__tag": 4046, "value": " item is a tuple then its first element defines the suffix of where data files are copied relative to package installation directory and the second element specifies the path to data files. By default data files are copied under package installation directory. For example," } ] }, { "__type": "Code", "__tag": 4050, "value": " config.add_data_files('foo.dat',\n\t ('fun',['gun.dat','nun/pun.dat','/tmp/sun.dat']),\n 'bar/car.dat'.\n '/full/path/to/can.dat',\n )", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "will install data files to the following locations" } ] }, { "__type": "Code", "__tag": 4050, "value": " /\n foo.dat\n fun/\n gun.dat\n\tpun.dat\n sun.dat\n bar/\n car.dat\n can.dat", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Path to data files can be a function taking no arguments and returning path(s) to data files -- this is a useful when data files are generated while building the package. (XXX: explain the step when this function are called exactly)" } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "config.add_data_dir(data_path)" }, { "__type": "Text", "__tag": 4046, "value": " --- add directory " }, { "__type": "InlineCode", "__tag": 4051, "value": "data_path" }, { "__type": "Text", "__tag": 4046, "value": " recursively to " }, { "__type": "InlineCode", "__tag": 4051, "value": "data_files" }, { "__type": "Text", "__tag": 4046, "value": ". The whole directory tree starting at " }, { "__type": "InlineCode", "__tag": 4051, "value": "data_path" }, { "__type": "Text", "__tag": 4046, "value": " will be copied under package installation directory. If " }, { "__type": "InlineCode", "__tag": 4051, "value": "data_path" }, { "__type": "Text", "__tag": 4046, "value": " is a tuple then its first element defines the suffix of where data files are copied relative to package installation directory and the second element specifies the path to data directory. By default, data directory are copied under package installation directory under the basename of " }, { "__type": "InlineCode", "__tag": 4051, "value": "data_path" }, { "__type": "Text", "__tag": 4046, "value": ". For example," } ] }, { "__type": "Code", "__tag": 4050, "value": "config.add_data_dir('fun') # fun/ contains foo.dat bar/car.dat\nconfig.add_data_dir(('sun','fun'))\nconfig.add_data_dir(('gun','/full/path/to/fun'))", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "will install data files to the following locations" } ] }, { "__type": "Code", "__tag": 4050, "value": "/\n fun/\n foo.dat\n bar/\n car.dat\n sun/\n foo.dat\n bar/\n car.dat\n gun/\n foo.dat\n bar/\n car.dat", "execution_status": null } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "config.add_include_dirs(*paths)" }, { "__type": "Text", "__tag": 4046, "value": " --- prepend " }, { "__type": "InlineCode", "__tag": 4051, "value": "paths" }, { "__type": "Text", "__tag": 4046, "value": " to " }, { "__type": "InlineCode", "__tag": 4051, "value": "include_dirs" }, { "__type": "Text", "__tag": 4046, "value": " list. This list will be visible to all extension modules of the current package." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "config.add_headers(*files)" }, { "__type": "Text", "__tag": 4046, "value": " --- prepend " }, { "__type": "InlineCode", "__tag": 4051, "value": "files" }, { "__type": "Text", "__tag": 4046, "value": " to " }, { "__type": "InlineCode", "__tag": 4051, "value": "headers" }, { "__type": "Text", "__tag": 4046, "value": " list. By default, headers will be installed under " }, { "__type": "InlineCode", "__tag": 4051, "value": "/include/pythonX.X//" }, { "__type": "Text", "__tag": 4046, "value": " directory. If " }, { "__type": "InlineCode", "__tag": 4051, "value": "files" }, { "__type": "Text", "__tag": 4046, "value": " item is a tuple then it's first argument specifies the installation suffix relative to " }, { "__type": "InlineCode", "__tag": 4051, "value": "/include/pythonX.X/" }, { "__type": "Text", "__tag": 4046, "value": " path. This is a Python distutils method; its use is discouraged for NumPy and SciPy in favour of " }, { "__type": "InlineCode", "__tag": 4051, "value": "config.add_data_files(*files)" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "config.add_scripts(*files)" }, { "__type": "Text", "__tag": 4046, "value": " --- prepend " }, { "__type": "InlineCode", "__tag": 4051, "value": "files" }, { "__type": "Text", "__tag": 4046, "value": " to " }, { "__type": "InlineCode", "__tag": 4051, "value": "scripts" }, { "__type": "Text", "__tag": 4046, "value": " list. Scripts will be installed under " }, { "__type": "InlineCode", "__tag": 4051, "value": "/bin/" }, { "__type": "Text", "__tag": 4046, "value": " directory." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "config.add_extension(name,sources,**kw)" }, { "__type": "Text", "__tag": 4046, "value": " --- create and add an " }, { "__type": "InlineCode", "__tag": 4051, "value": "Extension" }, { "__type": "Text", "__tag": 4046, "value": " instance to " }, { "__type": "InlineCode", "__tag": 4051, "value": "ext_modules" }, { "__type": "Text", "__tag": 4046, "value": " list. The first argument " }, { "__type": "InlineCode", "__tag": 4051, "value": "name" }, { "__type": "Text", "__tag": 4046, "value": " defines the name of the extension module that will be installed under " }, { "__type": "InlineCode", "__tag": 4051, "value": "config.name" }, { "__type": "Text", "__tag": 4046, "value": " package. The second argument is a list of sources. " }, { "__type": "InlineCode", "__tag": 4051, "value": "add_extension" }, { "__type": "Text", "__tag": 4046, "value": " method takes also keyword arguments that are passed on to the " }, { "__type": "InlineCode", "__tag": 4051, "value": "Extension" }, { "__type": "Text", "__tag": 4046, "value": " constructor. The list of allowed keywords is the following: " }, { "__type": "InlineCode", "__tag": 4051, "value": "include_dirs" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "define_macros" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "undef_macros" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "library_dirs" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "libraries" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "runtime_library_dirs" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "extra_objects" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "extra_compile_args" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "extra_link_args" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "export_symbols" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "swig_opts" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "depends" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "language" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "f2py_options" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "module_dirs" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "extra_info" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "extra_f77_compile_args" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "extra_f90_compile_args" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Note that " }, { "__type": "InlineCode", "__tag": 4051, "value": "config.paths" }, { "__type": "Text", "__tag": 4046, "value": " method is applied to all lists that may contain paths. " }, { "__type": "InlineCode", "__tag": 4051, "value": "extra_info" }, { "__type": "Text", "__tag": 4046, "value": " is a dictionary or a list of dictionaries that content will be appended to keyword arguments. The list " }, { "__type": "InlineCode", "__tag": 4051, "value": "depends" }, { "__type": "Text", "__tag": 4046, "value": " contains paths to files or directories that the sources of the extension module depend on. If any path in the " }, { "__type": "InlineCode", "__tag": 4051, "value": "depends" }, { "__type": "Text", "__tag": 4046, "value": " list is newer than the extension module, then the module will be rebuilt." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The list of sources may contain functions ('source generators') with a pattern " }, { "__type": "InlineCode", "__tag": 4051, "value": "def (ext, build_dir): return " }, { "__type": "Text", "__tag": 4046, "value": ". If " }, { "__type": "InlineCode", "__tag": 4051, "value": "funcname" }, { "__type": "Text", "__tag": 4046, "value": " returns " }, { "__type": "InlineCode", "__tag": 4051, "value": "None" }, { "__type": "Text", "__tag": 4046, "value": ", no sources are generated. And if the " }, { "__type": "InlineCode", "__tag": 4051, "value": "Extension" }, { "__type": "Text", "__tag": 4046, "value": " instance has no sources after processing all source generators, no extension module will be built. This is the recommended way to conditionally define extension modules. Source generator functions are called by the " }, { "__type": "InlineCode", "__tag": 4051, "value": "build_src" }, { "__type": "Text", "__tag": 4046, "value": " sub-command of " }, { "__type": "InlineCode", "__tag": 4051, "value": "numpy.distutils" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "For example, here is a typical source generator function " } ] }, { "__type": "Code", "__tag": 4050, "value": "def generate_source(ext,build_dir):\n import os\n from distutils.dep_util import newer\n target = os.path.join(build_dir,'somesource.c')\n if newer(target,__file__):\n # create target file\n return target", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The first argument contains the Extension instance that can be useful to access its attributes like " }, { "__type": "InlineCode", "__tag": 4051, "value": "depends" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "sources" }, { "__type": "Text", "__tag": 4046, "value": ", etc. lists and modify them during the building process. The second argument gives a path to a build directory that must be used when creating files to a disk." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "config.add_library(name, sources, **build_info)" }, { "__type": "Text", "__tag": 4046, "value": " --- add a library to " }, { "__type": "InlineCode", "__tag": 4051, "value": "libraries" }, { "__type": "Text", "__tag": 4046, "value": " list. Allowed keywords arguments are " }, { "__type": "InlineCode", "__tag": 4051, "value": "depends" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "macros" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "include_dirs" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "extra_compiler_args" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "f2py_options" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "extra_f77_compile_args" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "extra_f90_compile_args" }, { "__type": "Text", "__tag": 4046, "value": ". See " }, { "__type": "InlineCode", "__tag": 4051, "value": ".add_extension()" }, { "__type": "Text", "__tag": 4046, "value": " method for more information on arguments." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "config.have_f77c()" }, { "__type": "Text", "__tag": 4046, "value": " --- return True if Fortran 77 compiler is available (read: a simple Fortran 77 code compiled successfully)." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "config.have_f90c()" }, { "__type": "Text", "__tag": 4046, "value": " --- return True if Fortran 90 compiler is available (read: a simple Fortran 90 code compiled successfully)." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "config.get_version()" }, { "__type": "Text", "__tag": 4046, "value": " --- return version string of the current package, " }, { "__type": "InlineCode", "__tag": 4051, "value": "None" }, { "__type": "Text", "__tag": 4046, "value": " if version information could not be detected. This methods scans files " }, { "__type": "InlineCode", "__tag": 4051, "value": "__version__.py" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "_version.py" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "version.py" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "__svn_version__.py" }, { "__type": "Text", "__tag": 4046, "value": " for string variables " }, { "__type": "InlineCode", "__tag": 4051, "value": "version" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "__version__" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "_version" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "config.make_svn_version_py()" }, { "__type": "Text", "__tag": 4046, "value": " --- appends a data function to " }, { "__type": "InlineCode", "__tag": 4051, "value": "data_files" }, { "__type": "Text", "__tag": 4046, "value": " list that will generate " }, { "__type": "InlineCode", "__tag": 4051, "value": "__svn_version__.py" }, { "__type": "Text", "__tag": 4046, "value": " file to the current package directory. The file will be removed from the source directory when Python exits." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "config.get_build_temp_dir()" }, { "__type": "Text", "__tag": 4046, "value": " --- return a path to a temporary directory. This is the place where one should build temporary files." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "config.get_distribution()" }, { "__type": "Text", "__tag": 4046, "value": " --- return distutils " }, { "__type": "InlineCode", "__tag": 4051, "value": "Distribution" }, { "__type": "Text", "__tag": 4046, "value": " instance." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "config.get_config_cmd()" }, { "__type": "Text", "__tag": 4046, "value": " --- returns " }, { "__type": "InlineCode", "__tag": 4051, "value": "numpy.distutils" }, { "__type": "Text", "__tag": 4046, "value": " config command instance." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "config.get_info(*names)" }, { "__type": "Text", "__tag": 4046, "value": " ---" } ] } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "NumPy distutils supports automatic conversion of source files named .src. This facility can be used to maintain very similar code blocks requiring only simple changes between blocks. During the build phase of setup, if a template file named .src is encountered, a new file named is constructed from the template and placed in the build directory to be used instead. Two forms of template conversion are supported. The first form occurs for files named .ext.src where ext is a recognized Fortran extension (f, f90, f95, f77, for, ftn, pyf). The second form is used for all other cases." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This template converter will replicate all " }, { "__type": "Strong", "__tag": 4048, "children": [ { "__type": "Text", "__tag": 4046, "value": "function" } ] }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "Strong", "__tag": 4048, "children": [ { "__type": "Text", "__tag": 4046, "value": "subroutine" } ] }, { "__type": "Text", "__tag": 4046, "value": " blocks in the file with names that contain '<...>' according to the rules in '<...>'. The number of comma-separated words in '<...>' determines the number of times the block is repeated. What these words are indicates what that repeat rule, '<...>', should be replaced with in each block. All of the repeat rules in a block must contain the same number of comma-separated words indicating the number of times that block should be repeated. If the word in the repeat rule needs a comma, leftarrow, or rightarrow, then prepend it with a backslash ' '. If a word in the repeat rule matches ' \\' then it will be replaced with the -th word in the same repeat specification. There are two forms for the repeat rule: named and short." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "A named repeat rule is useful when the same set of repeats must be used several times in a block. It is specified using , where N is the number of times the block should be repeated. On each repeat of the block, the entire expression, '<...>' will be replaced first with item1, and then with item2, and so forth until N repeats are accomplished. Once a named repeat specification has been introduced, the same repeat rule may be used " }, { "__type": "Strong", "__tag": 4048, "children": [ { "__type": "Text", "__tag": 4046, "value": "in the current block" } ] }, { "__type": "Text", "__tag": 4046, "value": " by referring only to the name (i.e. )." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "A short repeat rule looks like . The rule specifies that the entire expression, '<...>' should be replaced first with item1, and then with item2, and so forth until N repeats are accomplished." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The following predefined named repeat rules are available:" } ] }, { "__type": "BulletList", "__tag": 4053, "ordered": false, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "" } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "<_c=s,d,c,z>" } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "<_t=real, double precision, complex, double complex>" } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "" } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "" } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "" } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "" } ] } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Non-Fortran files use a separate syntax for defining template blocks that should be repeated using a variable expansion similar to the named repeat rules of the Fortran-specific repeats." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "NumPy Distutils preprocesses C source files (extension: " }, { "__type": "InlineCode", "__tag": 4051, "value": ".c.src" }, { "__type": "Text", "__tag": 4046, "value": ") written in a custom templating language to generate C code. The " }, { "__type": "InlineCode", "__tag": 4051, "value": "@" }, { "__type": "Text", "__tag": 4046, "value": " symbol is used to wrap macro-style variables to empower a string substitution mechanism that might describe (for instance) a set of data types." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The template language blocks are delimited by " }, { "__type": "InlineCode", "__tag": 4051, "value": "/**begin repeat" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "InlineCode", "__tag": 4051, "value": "/**end repeat**/" }, { "__type": "Text", "__tag": 4046, "value": " lines, which may also be nested using consecutively numbered delimiting lines such as " }, { "__type": "InlineCode", "__tag": 4051, "value": "/**begin repeat1" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "InlineCode", "__tag": 4051, "value": "/**end repeat1**/" }, { "__type": "Text", "__tag": 4046, "value": ":" } ] }, { "__type": "BulletList", "__tag": 4053, "ordered": true, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "/**begin repeat" }, { "__type": "Text", "__tag": 4046, "value": " on a line by itself marks the beginning of a segment that should be repeated." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Named variable expansions are defined using " }, { "__type": "InlineCode", "__tag": 4051, "value": "#name=item1, item2, item3, ..., itemN#" }, { "__type": "Text", "__tag": 4046, "value": " and placed on successive lines. These variables are replaced in each repeat block with corresponding word. All named variables in the same repeat block must define the same number of words." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "In specifying the repeat rule for a named variable, " }, { "__type": "InlineCode", "__tag": 4051, "value": "item*N" }, { "__type": "Text", "__tag": 4046, "value": " is short- hand for " }, { "__type": "InlineCode", "__tag": 4051, "value": "item, item, ..., item" }, { "__type": "Text", "__tag": 4046, "value": " repeated N times. In addition, parenthesis in combination with " }, { "__type": "InlineCode", "__tag": 4051, "value": "*N" }, { "__type": "Text", "__tag": 4046, "value": " can be used for grouping several items that should be repeated. Thus, " }, { "__type": "InlineCode", "__tag": 4051, "value": "#name=(item1, item2)*4#" }, { "__type": "Text", "__tag": 4046, "value": " is equivalent to " }, { "__type": "InlineCode", "__tag": 4051, "value": "#name=item1, item2, item1, item2, item1, item2, item1, item2#" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "*/" }, { "__type": "Text", "__tag": 4046, "value": " on a line by itself marks the end of the variable expansion naming. The next line is the first line that will be repeated using the named rules." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Inside the block to be repeated, the variables that should be expanded are specified as " }, { "__type": "InlineCode", "__tag": 4051, "value": "@name@" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "/**end repeat**/" }, { "__type": "Text", "__tag": 4046, "value": " on a line by itself marks the previous line as the last line of the block to be repeated." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "A loop in the NumPy C source code may have a " }, { "__type": "InlineCode", "__tag": 4051, "value": "@TYPE@" }, { "__type": "Text", "__tag": 4046, "value": " variable, targeted for string substitution, which is preprocessed to a number of otherwise identical loops with several strings such as " }, { "__type": "InlineCode", "__tag": 4051, "value": "INT" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "LONG" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "UINT" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "ULONG" }, { "__type": "Text", "__tag": 4046, "value": ". The " }, { "__type": "InlineCode", "__tag": 4051, "value": "@TYPE@" }, { "__type": "Text", "__tag": 4046, "value": " style syntax thus reduces code duplication and maintenance burden by mimicking languages that have generic type support." } ] } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The above rules may be clearer in the following template source example:" } ] }, { "__type": "Code", "__tag": 4050, "value": "", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "will compile the " }, { "__type": "InlineCode", "__tag": 4051, "value": "library" }, { "__type": "Text", "__tag": 4046, "value": " sources without optimization flags." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "It's recommended to specify only those config_fc options in such a way that are compiler independent." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Some old Fortran codes need special compiler options in order to work correctly. In order to specify compiler options per source file, " }, { "__type": "InlineCode", "__tag": 4051, "value": "numpy.distutils" }, { "__type": "Text", "__tag": 4046, "value": " Fortran compiler looks for the following pattern " } ] }, { "__type": "Code", "__tag": 4050, "value": "CF77FLAGS() = ", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "in the first 20 lines of the source and use the " }, { "__type": "InlineCode", "__tag": 4051, "value": "f77flags" }, { "__type": "Text", "__tag": 4046, "value": " for specified type of the fcompiler (the first character " }, { "__type": "InlineCode", "__tag": 4051, "value": "C" }, { "__type": "Text", "__tag": 4046, "value": " is optional)." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "TODO: This feature can be easily extended for Fortran 90 codes as well. Let us know if you would need such a feature." } ] } ], "title": [ { "__type": "InlineCode", "__tag": 4051, "value": "numpy.distutils" }, { "__type": "Text", "__tag": 4046, "value": " user guide" } ], "level": 0, "target": "distutils-user-guide" } ], "local_refs": [] }