From c36553a1fe425fa9575c1b1b8b96c1d427b65fcd Mon Sep 17 00:00:00 2001 From: Cristian Maureira-Fredes Date: Fri, 23 Mar 2018 10:39:08 +0100 Subject: Update docstring from setup.py Change-Id: Icecb81aff1a5a496f64c4ce3467afc72e34670b6 Reviewed-by: Friedemann Kleint --- setup.py | 223 ++++++++++++++++++++++++++++++++++++++++++--------------------- 1 file changed, 148 insertions(+), 75 deletions(-) (limited to 'setup.py') diff --git a/setup.py b/setup.py index 73d06fa9f..7500b79d8 100644 --- a/setup.py +++ b/setup.py @@ -40,90 +40,163 @@ from __future__ import print_function from distutils.version import LooseVersion -"""This is a distutils setup-script for the PySide2 project +""" +This is a distutils setup-script for the Qt for Python project To build PySide2 simply execute: - python setup.py build --qmake= [--cmake=] [only Windows --openssl=] + python setup.py build or - python setup.py install --qmake= [--cmake=] [only Windows --openssl=] + python setup.py install to build and install into your current Python installation. -On Linux and macOS you can use option --standalone, to embed Qt libraries into the PySide2 package. -The option does not affect Windows, because it is used implicitly, i.e. all relevant DLLs have to -be copied into the PySide2 package anyway, because there is no proper rpath support on the platform. - -You can use option --rpath="your_value" to specify what rpath values should be embedded into the -PySide2 modules and shared libraries. This overrides the automatically generated values when the -option is not specified. - -You can use option --only-package, if you want to create more binary packages (bdist_wheel, bdist_egg, ...) -without rebuilding entire PySide2 every time: - # First time we create bdist_wheel with full PySide2 build - python setup.py bdist_wheel --qmake=c:\Qt\5.6\bin\qmake.exe --cmake=c:\tools\cmake\bin\cmake.exe --openssl=c:\libs\OpenSSL32bit\bin - - # Then we create bdist_egg reusing PySide2 build with option --only-package - python setup.py bdist_egg --only-package --qmake=c:\Qt\5.6\bin\qmake.exe --cmake=c:\tools\cmake\bin\cmake.exe --opnessl=c:\libs\OpenSSL32bit\bin - -You can use the option --qt-conf-prefix to pass a path relative to the PySide2 installed package, -which will be embedded into an auto-generated qt.conf registered in the Qt resource system. This -path will serve as the PrefixPath for QLibraryInfo, thus allowing to choose where Qt plugins -should be loaded from. This option overrides the usual prefix chosen by --standalone option, or when -building on Windows. -To temporarily disable registration of the internal qt.conf file, a new environment variable called -PYSIDE_DISABLE_INTERNAL_QT_CONF is introduced. You should assign the integer "1" to disable the -internal qt.conf, or "0" (or leave empty) to keep use the internal qt.conf file. - -For development purposes the following options might be of use, when using "setup.py build": - --reuse-build option allows recompiling only the modified sources and not the whole world, - shortening development iteration time, - --skip-cmake will reuse the already generated Makefiles (or equivalents), instead of invoking, - CMake to update the Makefiles (note, CMake should be ran at least once to generate the files), - --skip-make-install will not run make install (or equivalent) for each built module, - --skip-packaging will skip creation of the python package, - --ignore-git will skip the fetching and checkout steps for supermodule and all submodules. - --verbose-build will output the compiler invocation with command line arguments, etc. - --sanitize-address will build all targets with address sanitizer enabled. + +Optionally, one can specify the location of qmake and cmake if it is +not on the current PATH with: + --qmake=/path/to/qt/bin/qmake +and + --cmake=/path/to/bin/cmake +respectively. + +For windows, if OpenSSL support is required, it is necessary to specify +the directory with: + --openssl=/path/to/openssl/bin + +ADDITIONAL OPTIONS: + +On Linux and macOS you can use the option `--standalone` to embed Qt +libraries into the PySide2 package. +The option does not affect Windows, because it is used implicitly, +i.e. all relevant DLLs have to be copied into the PySide2 package +anyway, because there is no proper rpath support on the platform. + +You can use the option `--rpath=/path/to/lib/path` to specify which +rpath values should be embedded into the PySide2 modules and shared +libraries. +This overrides the automatically generated values when the option is +not specified. + +You can use the option `--only-package` if you want to create more +binary packages (bdist_wheel, bdist_egg, ...) without rebuilding the +entire PySide2 every time: + +e.g.: + +* First, we create a bdist_wheel from a full PySide2 build: + + python setup.py bdist_wheel --qmake=c:\Qt\5.9\bin\qmake.exe + --cmake=c:\tools\cmake\bin\cmake.exe + --openssl=c:\libs\OpenSSL32bit\bin + +* Then, we create a bdist_egg reusing PySide2 build with option + `--only-package`: + + python setup.py bdist_egg --only-package + --qmake=c:\Qt\5.9\bin\qmake.exe + --cmake=c:\tools\cmake\bin\cmake.exe + --openssl=c:\libs\OpenSSL32bit\bin + +You can use the option `--qt-conf-prefix` to pass a path relative to +the PySide2 installed package, which will be embedded into an +auto-generated `qt.conf` registered in the Qt resource system. +This path will serve as the PrefixPath for QLibraryInfo, thus allowing +to choose where Qt plugins should be loaded from. +This option overrides the usual prefix chosen by `--standalone` option, +or when building on Windows. + +To temporarily disable registration of the internal `qt.conf` file, a +new environment variable called PYSIDE_DISABLE_INTERNAL_QT_CONF is +introduced. + +You should assign the integer "1" to disable the internal `qt.conf`, +or "0" (or leave empty) to keep usining the internal `qt.conf` file. + +DEVELOPMENT OPTIONS: + +For development purposes the following options might be of use, when +using `setup.py build`: + + --reuse-build option allows recompiling only the modified sources and + not the whole world, shortening development iteration time, + --skip-cmake will reuse the already generated Makefiles (or + equivalents), instead of invoking, CMake to update the + Makefiles (note, CMake should be ran at least once to generate + the files), + --skip-make-install will not run make install (or equivalent) for + each module built, + --skip-packaging will skip creation of the python package, + --ignore-git will skip the fetching and checkout steps for + supermodule and all submodules. + --verbose-build will output the compiler invocation with command line + arguments, etc. + --sanitize-address will build the project with address sanitizer + enabled (Linux or macOS only). REQUIREMENTS: -- Python: 2.6, 2.7, 3.3, 3.4, 3.5 and 3.6 are supported -- Cmake: Specify the path to cmake with --cmake option or add cmake to the system path. -- Qt: 5.5 and 5.6 are supported. Specify the path to qmake with --qmake option or add qmake to the system path. + +* Python: 2.7 and 3.3+ are supported +* CMake: Specify the path to cmake with `--cmake` option or add cmake + to the system path. +* Qt: 5.9 and 5.11 are supported. Specify the path to qmake with + `--qmake` option or add qmake to the system path. OPTIONAL: -OpenSSL: - Specifying the --openssl option is only required on Windows. It is a no-op for other platforms. - You can specify the location of OpenSSL DLLs with option --openssl=. - You can download OpenSSL for Windows here: http://slproweb.com/products/Win32OpenSSL.html - - Official Qt packages do not link to the SSL library directly, but rather try to find the library - at runtime. - - On Windows, official Qt builds will try to pick up OpenSSL libraries at application path, - system registry, or in the PATH environment variable. - On macOS, official Qt builds use SecureTransport (provided by OS) instead of OpenSSL. - On Linux, official Qt builds will try to pick up the system OpenSSL library. - - Note: this means that Qt packages that directly link to the OpenSSL shared libraries, are not - currently compatible with standalone PySide2 packages. - -OS X SDK: You can specify which OS X SDK should be used for compilation with the option --osx-sysroot=. - For e.g. "--osx-sysroot=/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.11.sdk/". - -OS X Minimum deployment target: - You can specify a custom OS X minimum deployment target with the --osx-deployment-target= - option. - For example: "--osx-deployment-target=10.10". - - If the option is not set, the minimum deployment target of the used Qt library will be used - instead. Thus it is not necessary to use the option without a good reason. - If a new value is specified, it has to be higher or equal to both Python's and Qt's minimum - deployment targets. - - Description: - OS X allows specifying a minimum OS version on which a binary will be able to run. This implies - that an application can be built on a machine with the latest OS X version installed, with - latest Xcode version and SDK version and the built application can still run on an older OS - version. + +* OpenSSL: + Specifying the --openssl option is only required on Windows. + It is a no-op for other platforms. + + You can specify the location of OpenSSL DLLs with option: + --openssl=. + + You can download OpenSSL for Windows here: + http://slproweb.com/products/Win32OpenSSL.html (*) + + Official Qt packages do not link to the SSL library directly, but + rather try to find the library at runtime. + + On Windows, official Qt builds will try to pick up OpenSSL + libraries at application path, system registry, or in the PATH + environment variable. + + On macOS, official Qt builds use SecureTransport (provided by OS) + instead of OpenSSL. + + On Linux, official Qt builds will try to pick up the system OpenSSL + library. + + Note: this means that Qt packages that directly link to the OpenSSL + shared libraries, are not currently compatible with + standalone PySide2 packages. + + (*) Revised on 23.03.2018 + +* macOS SDK: + You can specify which macOS SDK should be used for compilation with + the option: + --osx-sysroot=. + + e.g.: "--osx-sysroot=/Applications/.../Developer/SDKs/MacOSX10.11.sdk/" + +* macOS minimum deployment target: + You can specify a custom macOS minimum deployment target with the + option: + --osx-deployment-target= + + e.g.: "--osx-deployment-target=10.10" + + If the option is not set, the minimum deployment target of the used + Qt library will be used instead. Thus it is not necessary to use + the option without a good reason. + + If a new value is specified, it has to be higher or equal to both + Python's and Qt's minimum deployment targets. + + Description: macOS allows specifying a minimum OS version on which + a binary will be able to run. This implies that an + application can be built on a machine with the latest + macOS version installed, with latest Xcode version and + SDK version and the built application can still run on + an older OS version. """ import os -- cgit v1.2.3