From 6c4cc3653e8dd7668295f3e659b7eb4dc571b67c Mon Sep 17 00:00:00 2001 From: Timothy Pearson Date: Tue, 22 Nov 2011 02:59:34 -0600 Subject: Initial import of SIP4 for Qt3 --- doc/html/build_system.html | 1182 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 1182 insertions(+) create mode 100644 doc/html/build_system.html (limited to 'doc/html/build_system.html') diff --git a/doc/html/build_system.html b/doc/html/build_system.html new file mode 100644 index 0000000..11016d4 --- /dev/null +++ b/doc/html/build_system.html @@ -0,0 +1,1182 @@ + + + + + + + The Build System — SIP 4.10.5 Reference Guide + + + + + + + + + + +
+

Navigation

+ +
+ +
+
+
+
+ +
+

The Build System

+

The purpose of the build system is to make it easy for you to write +configuration scripts in Python for your own bindings. The build system takes +care of the details of particular combinations of platform and compiler. It +supports over 50 different platform/compiler combinations.

+

The build system is implemented as a pure Python module called sipconfig +that contains a number of classes and functions. Using this module you can +write bespoke configuration scripts (e.g. PyQt’s configure.py) or use it +with other Python based build systems (e.g. +Distutils and +SCons).

+

An important feature of SIP is the ability to generate bindings that are built +on top of existing bindings. For example, both +PyKDE and +PyQwt are built on top of PyQt but all three +packages are maintained by different developers. To make this easier PyQt +includes its own configuration module, pyqtconfig, that contains additional +classes intended to be used by the configuration scripts of bindings built on +top of PyQt. The SIP build system includes facilities that do a lot of the +work of creating these additional configuration modules.

+
+
+sipconfig.create_config_module(module, template, content[, macros=None])
+

This creates a configuration module (e.g. pyqtconfig) from a template +file and a string.

+ +++ + + + +
Parameters:
    +
  • module – the name of the configuration module file to create.
    • +
  • template – the name of the template file.
    • +
  • content – a string which replaces every occurence of the pattern +@SIP_CONFIGURATION@ in the template file. The content string is +usually created from a Python dictionary using +sipconfig.create_content(). content may also be a +dictionary, in which case sipconfig.create_content() is +automatically called to convert it to a string.
    • +
  • macros – an optional dictionary of platform specific build macros. It is only +used if sipconfig.create_content() is called automatically to +convert a content dictionary to a string.
    • +
+
+
+ +
+
+sipconfig.create_content(dict[, macros=None]) → string
+

This converts a Python dictionary to a string that can be parsed by the +Python interpreter and converted back to an equivalent dictionary. It is +typically used to generate the content string for +sipconfig.create_config_module().

+ +++ + + + + + +
Parameters:
    +
  • dict – the Python dictionary to convert.
    • +
  • macros – the optional dictionary of platform specific build macros.
    • +
+
Returns:

the string representation of the dictionary.

+
+
+ +
+
+sipconfig.create_wrapper(script, wrapper[, gui=0[, use_arch='']]) → string
+

This creates a platform dependent executable wrapper around a Python +script.

+ +++ + + + + + +
Parameters:
    +
  • script – the full pathname of the script.
    • +
  • wrapper – the full pathname of the wrapper to create, excluding any platform +specific extension.
    • +
  • gui – is non-zero if a GUI enabled version of the interpreter should be used +on platforms that require it.
    • +
  • use_arch – is the MacOS/X architecture to invoke python with.
    • +
+
Returns:

the platform specific name of the wrapper.

+
+
+ +
+
+sipconfig.error(msg)
+

This displays an error message on stderr and calls sys.exit(1).

+ +++ + + + +
Parameter:msg – the text of the message and should not include any newline characters.
+
+ +
+
+sipconfig.format(msg[, leftmargin=0[, rightmargin=78]]) → string
+

This formats a message by inserting newline characters at appropriate +places.

+ +++ + + + + + +
Parameters:
    +
  • msg – the text of the message and should not include any newline characters.
    • +
  • leftmargin – the optional position of the left margin.
    • +
  • rightmargin – the optional position of the right margin.
    • +
+
Returns:

the formatted message.

+
+
+ +
+
+sipconfig.inform(msg)
+

This displays an information message on stdout.

+ +++ + + + +
Parameter:msg – the text of the message and should not include any newline characters.
+
+ +
+
+sipconfig.parse_build_macros(filename, names[, overrides=None[, properties=None]]) → dict
+

This parses a qmake compatible file of build system macros and converts +it to a dictionary. A macro is a name/value pair. Individual macros may +be augmented or replaced.

+ +++ + + + + + +
Parameters:
    +
  • filename – the name of the file to parse.
    • +
  • names – the list of the macro names to extract from the file.
    • +
  • overrides – the optional list of macro names and values that modify those found in +the file. They are of the form name=value (in which case the value +replaces the value found in the file) or name+=value (in which case +the value is appended to the value found in the file).
    • +
  • properties – the optional dictionary of property name and values that are used to +resolve any expressions of the form $[name] in the file.
    • +
+
Returns:

the dictionary of parsed macros or None if any of the overrides +were invalid.

+
+
+ +
+
+sipconfig.read_version(filename, description[, numdefine=None[, strdefine=None]]) → integer, string
+

This extracts version information for a package from a file, usually a C or +C++ header file. The version information must each be specified as a +#define of a numeric (hexadecimal or decimal) value and/or a string +value.

+ +++ + + + + + +
Parameters:
    +
  • filename – the name of the file to read.
    • +
  • description – a descriptive name of the package used in error messages.
    • +
  • numdefine – the optional name of the #define of the version as a number. If it +is None then the numeric version is ignored.
    • +
  • strdefine – the optional name of the #define of the version as a string. If it +is None then the string version is ignored.
    • +
+
Returns:

a tuple of the numeric and string versions. sipconfig.error() +is called if either were required but could not be found.

+
+
+ +
+
+sipconfig.version_to_sip_tag(version, tags, description) → string
+

This converts a version number to a SIP version tag. SIP uses the +%Timeline directive to define the chronology of the different +versions of the C/C++ library being wrapped. Typically it is not necessary +to define a version tag for every version of the library, but only for +those versions that affect the library’s API as SIP sees it.

+ +++ + + + + + +
Parameters:
    +
  • version – the numeric version number of the C/C++ library being wrapped. If it +is negative then the latest version is assumed. (This is typically +useful if a snapshot is indicated by a negative version number.)
    • +
  • tags – the dictionary of SIP version tags keyed by the corresponding C/C++ +library version number. The tag used is the one with the smallest key +(i.e. earliest version) that is greater than version.
    • +
  • description – a descriptive name of the C/C++ library used in error messages.
    • +
+
Returns:

the SIP version tag. sipconfig.error() is called if the C/C++ +library version number did not correspond to a SIP version tag.

+
+
+ +
+
+sipconfig.version_to_string(v) → string
+

This converts a 3 part version number encoded as a hexadecimal value to a +string.

+ +++ + + + + + +
Parameter:v – the version number.
Returns:a string.
+
+ +
+
+class sipconfig.Configuration
+

This class encapsulates configuration values that can be accessed as +instance objects. A sub-class may provide a dictionary of additional +configuration values in its constructor the elements of which will have +precedence over the super-class’s values.

+

The following configuration values are provided:

+
+
+default_bin_dir
+
The name of the directory where executables should be installed by +default.
+ +
+
+default_mod_dir
+
The name of the directory where SIP generated modules should be +installed by default.
+ +
+
+default_sip_dir
+
The name of the base directory where the .sip files for SIP +generated modules should be installed by default. A sub-directory with +the same name as the module should be created and its .sip files +should be installed in the sub-directory. The .sip files only need +to be installed if you might want to build other bindings based on +them.
+ +
+
+platform
+
The name of the platform/compiler for which the build system has been +configured for.
+ +
+
+py_conf_inc_dir
+
The name of the directory containing the pyconfig.h header file.
+ +
+
+py_inc_dir
+
The name of the directory containing the Python.h header file.
+ +
+
+py_lib_dir
+
The name of the directory containing the Python interpreter library.
+ +
+
+py_version
+
The Python version as a 3 part hexadecimal number (e.g. v2.3.3 is +represented as 0x020303).
+ +
+
+sip_bin
+
The full pathname of the SIP executable.
+ +
+
+sip_config_args
+
The command line passed to configure.py when SIP was configured.
+ +
+
+sip_inc_dir
+
The name of the directory containing the sip.h header file.
+ +
+
+sip_mod_dir
+
The name of the directory containing the SIP module.
+ +
+
+sip_version
+
The SIP version as a 3 part hexadecimal number (e.g. v4.0.0 is +represented as 0x040000).
+ +
+
+sip_version_str
+
The SIP version as a string. For development snapshots it will start +with snapshot-.
+ +
+
+universal
+
The name of the MacOS/X SDK used when creating universal binaries.
+ +
+
+arch
+
The space separated MacOS/X architectures to build.
+ +
+
+__init__([sub_cfg=None])
+
+++ + + + +
Parameter:sub_cfg – an optional list of sub-class configurations. It should only be +used by the __init__() method of a sub-class to append its own +dictionary of configuration values before passing the list to its +super-class.
+
+ +
+
+build_macros() → dict
+

Get the dictionary of platform specific build macros.

+ +++ + + + +
Returns:the macros dictionary.
+
+ +
+
+set_build_macros(macros)
+

Set the dictionary of platform specific build macros to be used when +generating Makefiles. Normally there is no need to change the default +macros.

+ +++ + + + +
Parameter:macros – the macros dictionary.
+
+ +
+ +
+
+class sipconfig.Makefile
+

This class encapsulates a Makefile. It is intended to be sub-classed to +generate Makefiles for particular purposes. It handles all platform and +compiler specific flags, but allows them to be adjusted to suit the +requirements of a particular module or program. These are defined using a +number of macros which can be accessed as instance attributes.

+

The following instance attributes are provided to help in fine tuning the +generated Makefile:

+
+
+chkdir
+
A string that will check for the existence of a directory.
+ +
+
+config
+
A reference to the configuration argument that was passed to +Makefile.__init__().
+ +
+
+console
+
A reference to the console argument that was passed to the +Makefile.__init__().
+ +
+
+copy
+
A string that will copy a file.
+ +
+
+extra_cflags
+
A list of additional flags passed to the C compiler.
+ +
+
+extra_cxxflags
+
A list of additional flags passed to the C++ compiler.
+ +
+
+extra_defines
+
A list of additional macro names passed to the C/C++ preprocessor.
+ +
+
+extra_include_dirs
+
A list of additional include directories passed to the C/C++ +preprocessor.
+ +
+
+extra_lflags
+
A list of additional flags passed to the linker.
+ +
+
+extra_lib_dirs
+
A list of additional library directories passed to the linker.
+ +
+
+extra_libs
+
A list of additional libraries passed to the linker. The names of the +libraries must be in platform neutral form (i.e. without any platform +specific prefixes, version numbers or extensions).
+ +
+
+generator
+
A string that defines the platform specific style of Makefile. The +only supported values are UNIX, MSVC, MSVC.NET, MINGW +and BMAKE.
+ +
+
+mkdir
+
A string that will create a directory.
+ +
+
+rm
+
A string that will remove a file.
+ +
+
+__init__(configuration[, console=0[, qt=0[, opengl=0[, python=0[, threaded=0[, warnings=None[, debug=0[, dir=None[, makefile="Makefile"[, installs=None[, universal=None[, arch=None]]]]]]]]]]]])
+
+++ + + + +
Parameters:
    +
  • configuration – the current configuration and is an instance of the +Configuration class or a sub-class.
    • +
  • console – is set if the target is a console (rather than GUI) target. This +only affects Windows and is ignored on other platforms.
    • +
  • qt – is set if the target uses Qt. For Qt v4 a list of Qt libraries may +be specified and a simple non-zero value implies QtCore and QtGui.
    • +
  • opengl – is set if the target uses OpenGL.
    • +
  • python – is set if the target uses Python.h.
    • +
  • threaded – is set if the target requires thread support. It is set +automatically if the target uses Qt and Qt has thread support +enabled.
    • +
  • warnings – is set if compiler warning messages should be enabled. The default +of None means that warnings are enabled for SIP v4.x and +disabled for SIP v3.x.
    • +
  • debug – is set if debugging symbols should be generated.
    • +
  • dir – the name of the directory where build files are read from (if they +are not absolute file names) and Makefiles are written to. The +default of None means the current directory is used.
    • +
  • makefile – the name of the generated Makefile.
    • +
  • installs – the list of extra install targets. Each element is a two part +list, the first of which is the source and the second is the +destination. If the source is another list then it is a list of +source files and the destination is a directory.
    • +
  • universal – the name of the SDK if universal binaries are to be created under +MacOS/X. If it is None then the value is taken from the +configuration.
    • +
  • arch – the space separated MacOS/X architectures to build. If it is +None then the value is taken from the configuration.
    • +
+
+
+ +
+
+clean_build_file_objects(mfile, build)
+

This generates the Makefile commands that will remove any files +generated during the build of the default target.

+ +++ + + + +
Parameters:
    +
  • mfile – the Python file object of the Makefile.
    • +
  • build – the dictionary created from parsing the build file.
    • +
+
+
+ +
+
+finalise()
+
This is called just before the Makefile is generated to ensure that it +is fully configured. It must be reimplemented by a sub-class.
+ +
+
+generate()
+
This generates the Makefile.
+ +
+
+generate_macros_and_rules(mfile)
+

This is the default implementation of the Makefile macros and rules +generation.

+ +++ + + + +
Parameter:mfile – the Python file object of the Makefile.
+
+ +
+
+generate_target_clean(mfile)
+

This is the default implementation of the Makefile clean target +generation.

+ +++ + + + +
Parameter:mfile – the Python file object of the Makefile.
+
+ +
+
+generate_target_default(mfile)
+

This is the default implementation of the Makefile default target +generation.

+ +++ + + + +
Parameter:mfile – the Python file object of the Makefile.
+
+ +
+
+generate_target_install(mfile)
+

This is the default implementation of the Makefile install target +generation.

+ +++ + + + +
Parameter:mfile – the Python file object of the Makefile.
+
+ +
+
+install_file(mfile, src, dst[, strip=0])
+

This generates the Makefile commands to install one or more files to a +directory.

+ +++ + + + +
Parameters:
    +
  • mfile – the Python file object of the Makefile.
    • +
  • src – the name of a single file to install or a list of a number of files +to install.
    • +
  • dst – the name of the destination directory.
    • +
  • strip – is set if the files should be stripped of unneeded symbols after +having been installed.
    • +
+
+
+ +
+
+optional_list(name) → list
+

This returns an optional Makefile macro as a list.

+ +++ + + + + + +
Parameter:name – the name of the macro.
Returns:the macro as a list.
+
+ +
+
+optional_string(name[, default=""])
+

This returns an optional Makefile macro as a string.

+ +++ + + + + + +
Parameters:
    +
  • name – the name of the macro.
    • +
  • default – the optional default value of the macro.
    • +
+
Returns:

the macro as a string.

+
+
+ +
+
+parse_build_file(filename) → dict
+

This parses a build file (created with the -b SIP +command line option) and converts it to a dictionary. It can also +validate an existing dictionary created through other means.

+ +++ + + + + + +
Parameter:filename – is the name of the build file, or is a dictionary to +be validated. A valid dictionary will contain the name of the +target to build (excluding any platform specific extension) keyed +by target; the names of all source files keyed by sources; +and, optionally, the names of all header files keyed by +headers.
Returns:a dictionary corresponding to the parsed build file.
+
+ +
+
+platform_lib(clib[, framework=0]) → string
+

This converts a library name to a platform specific form.

+ +++ + + + + + +
Parameters:
    +
  • clib – the name of the library in cannonical form.
    • +
  • framework – is set if the library is implemented as a MacOS framework.
    • +
+
Returns:

the platform specific name.

+
+
+ +
+
+ready()
+
This is called to ensure that the Makefile is fully configured. It is +normally called automatically when needed.
+ +
+
+required_string(name) → string
+

This returns a required Makefile macro as a string.

+ +++ + + + + + +
Parameter:name – the name of the macro.
Returns:the macro as a string. An exception is raised if the macro does +not exist or has an empty value.
+
+ +
+ +
+
+class sipconfig.ModuleMakefile
+

This class is derived from sipconfig.Makefile.

+

This class encapsulates a Makefile to build a generic Python extension +module.

+
+
+__init__(self, configuration, build_file[, install_dir=None[, static=0[, console=0[, opengl=0[, threaded=0[, warnings=None[, debug=0[, dir=None[, makefile="Makefile"[, installs=None[, strip=1[, export_all=0[, universal=None[, arch=None]]]]]]]]]]]]]])
+
+++ + + + +
Parameters: +
+
+ +
+
+finalise()
+
This is a reimplementation of sipconfig.Makefile.finalise().
+ +
+
+generate_macros_and_rules(mfile)
+
This is a reimplementation of +sipconfig.Makefile.generate_macros_and_rules().
+ +
+
+generate_target_clean(mfile)
+
This is a reimplementation of +sipconfig.Makefile.generate_target_clean().
+ +
+
+generate_target_default(mfile)
+
This is a reimplementation of +sipconfig.Makefile.generate_target_default().
+ +
+
+generate_target_install(mfile)
+
This is a reimplementation of +sipconfig.Makefile.generate_target_install().
+ +
+
+module_as_lib(mname) → string
+

This gets the name of a SIP v3.x module for when it is used as a +library to be linked against. An exception will be raised if it is +used with SIP v4.x modules.

+ +++ + + + + + +
Parameter:mname – the name of the module.
Returns:the corresponding library name.
+
+ +
+ +
+
+class sipconfig.ParentMakefile
+

This class is derived from sipconfig.Makefile.

+

This class encapsulates a Makefile that sits above a number of other +Makefiles in sub-directories.

+
+
+__init__(self, configuration, subdirs[, dir=None[, makefile[, ="Makefile"[, installs=None]]]])
+
+++ + + + +
Parameters: +
+
+ +
+
+generate_macros_and_rules(mfile)
+
This is a reimplementation of +sipconfig.Makefile.generate_macros_and_rules().
+ +
+
+generate_target_clean(mfile)
+
This is a reimplementation of +sipconfig.Makefile.generate_target_clean().
+ +
+
+generate_target_default(mfile)
+
This is a reimplementation of +sipconfig.Makefile.generate_target_default().
+ +
+
+generate_target_install(mfile)
+
This is a reimplementation of +sipconfig.Makefile.generate_target_install().
+ +
+ +
+
+class sipconfig.ProgramMakefile
+

This class is derived from sipconfig.Makefile.

+

This class encapsulates a Makefile to build an executable program.

+
+
+__init__(configuration[, build_file=None[, install_dir=None[, console=0[, qt=0[, opengl=0[, python=0[, threaded=0[, warnings=None[, debug=0[, dir=None[, makefile="Makefile"[, installs=None[, universal=None[, arch=None]]]]]]]]]]]]]])
+
+++ + + + +
Parameters: +
+
+ +
+
+build_command(source) → string, string
+

This creates a single command line that will create an executable +program from a single source file.

+ +++ + + + + + +
Parameter:source – the name of the source file.
Returns:a tuple of the name of the executable that will be created and the +command line.
+
+ +
+
+finalise()
+
This is a reimplementation of sipconfig.Makefile.finalise().
+ +
+
+generate_macros_and_rules(mfile)
+
This is a reimplementation of +sipconfig.Makefile.generate_macros_and_rules().
+ +
+
+generate_target_clean(mfile)
+
This is a reimplementation of +sipconfig.Makefile.generate_target_clean().
+ +
+
+generate_target_default(mfile)
+
This is a reimplementation of +sipconfig.Makefile.generate_target_default().
+ +
+
+generate_target_install(mfile)
+
This is a reimplementation of +sipconfig.Makefile.generate_target_install().
+ +
+ +
+
+class sipconfig.PythonModuleMakefile
+

This class is derived from sipconfig.Makefile.

+

This class encapsulates a Makefile that installs a pure Python module.

+
+
+__init__(self, configuration, dstdir[, srcdir=None[, dir=None[, makefile="Makefile"[, installs=None]]]])
+
+++ + + + +
Parameters: +
+
+ +
+
+generate_macros_and_rules(mfile)
+
This is a reimplementation of +sipconfig.Makefile.generate_macros_and_rules().
+ +
+
+generate_target_install(mfile)
+
This is a reimplementation of +sipconfig.Makefile.generate_target_install().
+ +
+ +
+
+class sipconfig.SIPModuleMakefile
+

This class is derived from sipconfig.ModuleMakefile.

+

This class encapsulates a Makefile to build a SIP generated Python +extension module.

+
+
+__init__(self, configuration, build_file[, install_dir=None[, static=0[, console=0[, opengl=0[, threaded=0[, warnings=None[, debug=0[, dir=None[, makefile="Makefile"[, installs=None[, strip=1[, export_all=0[, universal=None[, arch=None[, prot_is_public=0]]]]]]]]]]]]]]])
+
+++ + + + +
Parameters: +
+
+ +
+
+finalise()
+
This is a reimplementation of sipconfig.Makefile.finalise().
+ +
+ +
+ + +
+
+
+
+
+

Previous topic

+

Python API for Applications

+

Next topic

+

Building Your Extension with distutils

+ + +
+
+
+
+
+

Navigation

+ +
+
+ © Copyright 2010 Riverbank Computing Limited. + Created using Sphinx 0.6.4. +
+ + \ No newline at end of file -- cgit v1.2.3