diff options
author | Cristian Maureira-Fredes <Cristian.Maureira-Fredes@qt.io> | 2020-10-27 15:57:38 +0100 |
---|---|---|
committer | Cristian Maureira-Fredes <cristian.maureira-fredes@qt.io> | 2020-10-28 12:46:13 +0000 |
commit | a26b04fae0f055d7590c9e7380afe7a5fb67c58e (patch) | |
tree | 383503840a542040bb9d63e1b3216a2acec12d15 | |
parent | 2a2a0827fa54b2eeb48e0e2090dfc503492ef33e (diff) |
doc: move setup.py docs and updates
* Moves the huge docstring from setup.py to the README.md file,
* Adding README.cmake.md as a new section of the README.md file,
* Update versioning and do partial updates respect to Qt 6
Change-Id: I4d97f14ebcc1e17fe349aaf5c68b4ce4505c882f
Reviewed-by: Friedemann Kleint <Friedemann.Kleint@qt.io>
-rw-r--r-- | README.cmake.md | 39 | ||||
-rw-r--r-- | README.md | 248 | ||||
-rw-r--r-- | README.pyside2.md | 45 | ||||
-rw-r--r-- | README.shiboken6-generator.md | 33 | ||||
-rw-r--r-- | setup.py | 220 |
5 files changed, 290 insertions, 295 deletions
diff --git a/README.cmake.md b/README.cmake.md deleted file mode 100644 index 60c446e8d..000000000 --- a/README.cmake.md +++ /dev/null @@ -1,39 +0,0 @@ -# CMake super project -For development convenience, a CMake super project is included in the root of the repository. - -The super project can be built using standalone CMake, or using an IDE's CMake integration -(Qt Creator for example). - -Nevertheless the default build process is done via setup.py, in which case each of the -sub-projects are built and installed separately, as mentioned, the super project is just -for development convenience. - -## IDE (Qt Creator) case - -When using an IDE, just open the root CMakeLists.txt file as a new project, and make sure to -specify the following things: - - * LLVM_INSTALL_DIR - the environment variable should point to your libclang library location - * Qt - either select a Qt Kit when configuring the project, or make sure that the - qmake binary is present in the PATH environment variable. - * Python - the PATH environment variable should also point to the Python interpreter - which you wish to use for building the projects (can either be a system - interpreter, or a virtualenv one for example) - -Once that is done, just re-run CMake, so that it picks up the new environment values. -If needed, all other cache variables defined by the project files can be re-adjusted -(for example FORCE_LIMITED_API). - -## Command line CMake case - -When building using the command line CMake binary, make sure to invoke it in a separate -build directory, and not in the root source directory. - -Make sure you have the correct environment variables set up, as described in the previous section. - -The invocation would then look like: -```bash -mkdir build && cd build -cmake -DCMAKE_BUILD_TYPE=Release .. -# make or nmake or msbuild or jom -``` @@ -1,9 +1,249 @@ # Qt For Python -Qt For Python is the [Python Qt bindings project](http://wiki.qt.io/PySide2), providing -access to the complete Qt 5.x framework as well as to generator tools for rapidly -generating bindings for any C++ libraries. +Qt For Python is the [Python Qt bindings project](http://wiki.qt.io/PySide2), +providing access to the complete Qt framework as well as to generator tools for +rapidly generating bindings for any C++ libraries. -shiboken6 is the generator used to build the bindings. +Shiboken is the generator used to build the bindings. See README.pyside2.md and README.shiboken6.md for details. + +## Building + +To build both Shiboken and PySide simply execute: + + * `python setup.py build`, or + * `python setup.py install` + +to build and install into your current Python installation. + +The same setup.py script is used to build all the components of the project: + + * shiboken6 (the supporting Python module) + * shiboken6-generator (the bindings generation executable) + * PySide2 + +Preferably, a Qt (build) environment should be used to automatically pick up +the associated `qmake`, but optionally one can specify the location of `qmake` +and `cmake` if it is not in the current PATH with: + + * `--qmake=/path/to/qt/bin/qmake`, and + * `--cmake=/path/to/bin/cmake` + +respectively. + +By default, all of the above is built when no special options are passed to the +script. You can use the --build-type parameter to specify which things should +be built: + + * `--build-type=shiboken6`, build/package only the python module + * `--build-type=shiboken6-generator`, build/package the generator executable + * `--build-type=pyside2`, build/package the PySide2 bindings. + * `--build-type=all`, the implicit default to build all of the above + +When building PySide2, optionally, one can specify the location of the +shiboken6 cmake config path if it is not on the current PATH with: + + * `--shiboken-config-dir=/path/to/shiboken/cmake/config/dir` + +This is useful if you did a cmake installation of shiboken6 into a custom +location. + +For Windows, if OpenSSL support is required, it's necessary to specify the +directory path that contains the OpenSSL shared libraries `libeay32.dll` and +`ssleay32.dll`, for example: + +* `--openssl=C:\OpenSSL-Win64\bin` + +This will make sure that the libraries are copied into the PySide2 package and +are found by the QtNetwork module. + +## Building 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 project +every time: + +e.g.: + +* First, we create a bdist_wheel from a full PySide2 build: + ``` + python setup.py bdist_wheel --qmake=c:\Qt\5.12\bin\qmake.exe + --cmake=c:\tools\cmake\bin\cmake.exe + --openssl=c:\libs\OpenSSL32bit\bin + ``` +* Then, we create a bdist_egg reusing the PySide2 build with option + `--only-package`: + ``` + python setup.py bdist_egg --only-package + --qmake=c:\Qt\5.15\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 using the internal `qt.conf` file. + +## Development Options + +For development purposes the following options might be of use, when +using `setup.py build`: + + * `--ignore-git`, will skip the fetching and checkout steps for supermodule + and all submodules. + * `--limited-api=yes|no`, default yes if applicable. Set or clear the limited + API flag. Ignored for Python 2. + * `--module-subset`, allows for specifying the Qt modules to be built. + A minimal set is: `--module-subset=Core,Gui,Test,Widgets`. + * `--package-timestamp`, allows specifying the timestamp that will be used as + part of the version number for a snapshot package. + For example given `--package-timestamp=1529646276` the package version will + be `5.x.y.dev1529646276`. + * `--reuse-build`, option allows recompiling only the modified sources and not + the whole world, shortening development iteration time. + * `--sanitize-address`, will build the project with address sanitizer. + * `--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-docs`, skip the documentation generation. + * `--skip-make-install`, will not run make install (or equivalent) for each + module built. + * `--skip-modules`, allows for specifying the Qt modules that will be skipped + during the build process. + For example: `--skip-modules=WebEngineCore,WebEngineWidgets` + * `--skip-packaging`, will skip creation of the python package, enabled (Linux + or macOS only). + * `--verbose-build`, will output the compiler invocation with command line + arguments, etc. + +## Requirements + + * Python 3.6+ are supported, + * CMake: Specify the path to cmake with `--cmake` option or add cmake to the + system path. + * Qt 5.12+ is supported. Specify the path to qmake with `--qmake` option or + add qmake to the system path. + +### Optional + +#### OpenSSL: + +Specifying the `--openssl` option only affects Windows. It is a no-op for other +platforms. + +Please note that official Windows packages do not ship the OpenSSL libraries +due to import/export restrictions as described in +http://doc.qt.io/qt-5/ssl.html#import-and-export-restrictions + +You can specify the location of the OpenSSL DLLs with the following option: +`--openssl=</path/to/openssl/bin-directory>`. + +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. + +#### macOS SDK: + +You can specify which macOS SDK should be used for compilation with the option +`--macos-sysroot=</path/to/sdk>`, for example: +``` +--macos-sysroot=/Applications/Xcode.app/.../Developer/SDKs/MacOSX10.12.sdk/ +``` + +#### macOS minimum deployment target: + +You can specify a custom macOS minimum deployment target with the option +`--macos-deployment-target=<value>`, for example: +``` +--macos-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. + + +## CMake super project + +For development convenience, a CMake super project is included in the root of +the repository. + +The super project can be built using standalone CMake, or using an IDE's CMake +integration (Qt Creator for example). + +Nevertheless the default build process is done via setup.py, in which case each +of the sub-projects are built and installed separately, as mentioned, the super +project is just for development convenience. + +## IDE (Qt Creator) case + +When using an IDE, just open the root CMakeLists.txt file as a new project, and +make sure to specify the following things: + + * `LLVM_INSTALL_DIR`, the environment variable should point to your libclang + library location + * `Qt`, either select a Qt Kit when configuring the project, or make sure that + the qmake binary is present in the PATH environment variable. + * `Python`, the PATH environment variable should also point to the Python + interpreter which you wish to use for building the projects (can either be + a system interpreter, or a virtualenv one for example) + +Once that is done, just re-run CMake, so that it picks up the new environment +values. If needed, all other cache variables defined by the project files can +be re-adjusted (for example FORCE_LIMITED_API). + +## Command line CMake case + +When building using the command line CMake binary, make sure to invoke it in +a separate build directory, and not in the root source directory. + +Make sure you have the correct environment variables set up, as described in +the previous section. + +The invocation would then look like: +```bash +mkdir build && cd build +cmake -DCMAKE_BUILD_TYPE=Release .. +# make or nmake or msbuild or jom +``` diff --git a/README.pyside2.md b/README.pyside2.md index 94cdd16e3..0133c4c5e 100644 --- a/README.pyside2.md +++ b/README.pyside2.md @@ -17,7 +17,9 @@ Since the release of the [Technical Preview](https://blog.qt.io/blog/2018/06/13/ it is possible to install via `pip`, both from Qt's servers and [PyPi](https://pypi.org/project/PySide2/): - pip install PySide2 +``` +pip install PySide2 +``` #### Dependencies @@ -29,13 +31,17 @@ higher is required for building. Prebuilt versions of it can be downloaded from After unpacking the archive, set the environment variable *LLVM_INSTALL_DIR* to point to the folder containing the *include* and *lib* directories of Clang: - 7z x .../libclang-release_60-linux-Rhel7.2-gcc5.3-x86_64-clazy.7z - export LLVM_INSTALL_DIR=$PWD/libclang +``` +7z x .../libclang-release_100-linux-Rhel7.2-gcc5.3-x86_64-clazy.7z +export LLVM_INSTALL_DIR=$PWD/libclang +``` On Windows: - 7z x .../libclang-release_60-windows-vs2015_64-clazy.7z - SET LLVM_INSTALL_DIR=%CD%\libclang +``` +7z x .../libclang-release_100-windows-vs2015_64-clazy.7z +SET LLVM_INSTALL_DIR=%CD%\libclang +``` ### Building from source @@ -43,18 +49,22 @@ For building PySide2 from scratch, please read about [getting started](https://wiki.qt.io/Qt_for_Python/GettingStarted). This process will include getting the code: - git clone https://code.qt.io/pyside/pyside-setup - cd pyside-setup - git branch --track 5.12 origin/5.12 - git checkout 5.12 +``` +git clone https://code.qt.io/pyside/pyside-setup +cd pyside-setup +git branch --track 5.14 origin/5.15 +git checkout 5.15 +``` then install the dependencies, and following the instructions per platform. A common build command will look like: - python setup.py install --qmake=<path/to/qmake/> --parallel=8 --build-tests +``` +python setup.py install --qmake=path/to/qmake/ --parallel=8 --build-tests +``` -You can obtain more information about the options to build PySide -and Shiboken in [our wiki](https://wiki.qt.io/Qt_for_Python/). +You can obtain more information about the options to build PySide and Shiboken +in [our wiki](https://wiki.qt.io/Qt_for_Python/). ### Documentation and Bugs @@ -67,11 +77,12 @@ our [guidelines](https://wiki.qt.io/Qt_for_Python/Reporting_Bugs). ### Community -Check *#qt-pyside*, our official IRC channel on FreeNode, -or contact us via our [mailing list](http://lists.qt-project.org/mailman/listinfo/pyside). +Check *#qt-pyside*, our official IRC channel on FreeNode, or contact us via our +[mailing list](http://lists.qt-project.org/mailman/listinfo/pyside). ### Licensing -PySide2 is available under both Open Source (LGPLv3/GPLv2) and commercial license. -Using PyPi is the recommended installation source, because the content of the wheels is valid for both cases. -For more information, refer to the [Qt Licensing page](https://www.qt.io/licensing/). +PySide2 is available under both Open Source (LGPLv3/GPLv2) and commercial +license. Using PyPi is the recommended installation source, because the +content of the wheels is valid for both cases. For more information, refer to +the [Qt Licensing page](https://www.qt.io/licensing/). diff --git a/README.shiboken6-generator.md b/README.shiboken6-generator.md index 3b77edcf2..c57af2d94 100644 --- a/README.shiboken6-generator.md +++ b/README.shiboken6-generator.md @@ -1,34 +1,33 @@ # Shiboken6-generator -Shiboken is the generator used by the Qt for Python project. -It outputs C++ code for CPython extensions, which can be compiled -and transformed into a Python module. +Shiboken is the generator used by the Qt for Python project. It outputs C++ +code for CPython extensions, which can be compiled and transformed into +a Python module. -C++ projects based on Qt can be wrapped, but also projects -which are not related to Qt. +C++ projects based on Qt can be wrapped, but also projects which are not +related to Qt. ## How does it work? -Shiboken uses an API Extractor that does most of the job, -but it requires a typesystem (XML file) to customize how the -C++ classes/methods will be exposed to Python. +Shiboken uses an API Extractor that does most of the job, but it requires +a typesystem (XML file) to customize how the C++ classes/methods will be +exposed to Python. -The typesystem allows you to remove arguments from signatures, -modify return types, inject code and add conversion rules -from the C++ data types to Python data types, manipulate -the ownership of the objects, etc. +The typesystem allows you to remove arguments from signatures, modify return +types, inject code and add conversion rules from the C++ data types to Python +data types, manipulate the ownership of the objects, etc. # Examples -An example related to wrap a C++ library not depending on Qt -can be found in our [repository](https://code.qt.io/cgit/pyside/pyside-setup.git/tree/examples/samplebinding). +An example related to wrap a C++ library not depending on Qt can be found in +our [repository](https://code.qt.io/cgit/pyside/pyside-setup.git/tree/examples/samplebinding). Additionally, you can find a couple of tests inside the [git repository](https://code.qt.io/cgit/pyside/pyside-setup.git/tree/sources/shiboken6/tests). -For a more advanced case regarding extending a Qt/C++ application -with Python bindings based on the idea of the PySide module, -you can check the [scriptableapplication](https://code.qt.io/cgit/pyside/pyside-setup.git/tree/examples/scriptableapplication) +For a more advanced case regarding extending a Qt/C++ application with Python +bindings based on the idea of the PySide module, you can check the +[scriptableapplication](https://code.qt.io/cgit/pyside/pyside-setup.git/tree/examples/scriptableapplication) example in our repository. # Documentation @@ -40,224 +40,8 @@ from __future__ import print_function """ -This is a distutils setup-script for the Qt for Python project - -To build both shiboken6 and PySide2 simply execute: - - python setup.py build - -or - - python setup.py install - -to build and install into your current Python installation. - -The same setup.py script is used to build all the components of the -project: - - shiboken6 (the supporting Python module) - - shiboken6-generator (the bindings generation executable) - - PySide2 - - pyside2-tools - -Preferably, a Qt (build) environment should be used to automatically -pick up the associated `qmake`, but optionally one can specify the -location of `qmake` and `cmake` if it is not in the current PATH with: - - --qmake=/path/to/qt/bin/qmake - -and - - --cmake=/path/to/bin/cmake - -respectively. - -By default, all of the above is built when no special options are -passed to the script. You can use the --build-type parameter to specify -which things should be built: - - --build-type=shiboken6 - build / package only the python module - --build-type=shiboken6-generator - build / package the generator - executable - --build-type=pyside2 - build / package the PySide2 bindings and - and pyside2-tools - --build-type=all - the implicit default to build all of the above - - -When building PySide2, optionally, one can specify the location of the -shiboken6 cmake config path if it is not on the current PATH with: - - --shiboken-config-dir=/path/to/shiboken/cmake/config/dir - -This is useful if you did a cmake installation of shiboken6 into -a custom location. - -For Windows, if OpenSSL support is required, it's necessary to specify -the directory path that contains the OpenSSL shared libraries -"libeay32.dll" and "ssleay32.dll", for example: - - --openssl=C:\\OpenSSL-Win64\\bin - -This will make sure that the libraries are copied into the PySide2 -package and are found by the QtNetwork module. - -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 project every time: - -e.g.: - -* First, we create a bdist_wheel from a full PySide2 build: - - python setup.py bdist_wheel --qmake=c:\\Qt\\5.12\\bin\\qmake.exe - --cmake=c:\\tools\\cmake\\bin\\cmake.exe - --openssl=c:\\libs\\OpenSSL32bit\\bin - -* Then, we create a bdist_egg reusing the PySide2 build with option - `--only-package`: - - python setup.py bdist_egg --only-package - --qmake=c:\\Qt\\5.12\\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 using the internal `qt.conf` file. - -DEVELOPMENT OPTIONS: - -For development purposes the following options might be of use, when -using `setup.py build`: - - --ignore-git will skip the fetching and checkout steps for - supermodule and all submodules. - --limited-api=yes|no default yes if applicable - Set or clear the limited API flag. Ignored for Python 2. - --module-subset allows for specifying the Qt modules to be built. - A minimal set is: --module-subset=Core,Gui,Test,Widgets - --package-timestamp allows specifying the timestamp that will be - used as part of the version number for a snapshot package. - For example given --package-timestamp=1529646276 - the package version will be 5.x.y.dev1529646276. - --reuse-build option allows recompiling only the modified sources and - not the whole world, shortening development iteration time. - --sanitize-address will build the project with address sanitizer. - --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-docs skip the documentation generation. - --skip-make-install will not run make install (or equivalent) for - each module built. - --skip-modules allows for specifying the Qt modules that will be - skipped during the build process. - For example: --skip-modules=WebEngineCore,WebEngineWidgets - --skip-packaging will skip creation of the python package, - enabled (Linux or macOS only). - --verbose-build will output the compiler invocation with command line - arguments, etc. - -REQUIREMENTS: - -* Python: 2.7 and 3.5+ are supported -* CMake: Specify the path to cmake with `--cmake` option or add cmake - to the system path. -* Qt: 5.11+ is supported. Specify the path to qmake with - `--qmake` option or add qmake to the system path. - -OPTIONAL: - -* OpenSSL: - Specifying the --openssl option only affects Windows. - It is a no-op for other platforms. - - Please note that official Windows packages do not ship the - OpenSSL libraries due to import / export restrictions as - described in - http://doc.qt.io/qt-5/ssl.html#import-and-export-restrictions - - You can specify the location of the OpenSSL DLLs with the - following option: - - --openssl=</path/to/openssl/bin-directory>. - - 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 2018.10.24 - -* macOS SDK: - You can specify which macOS SDK should be used for compilation with - the option: - - --macos-sysroot=</path/to/sdk>. - - e.g.: "--macos-sysroot=/Applications/Xcode.app/.../Developer/SDKs/MacOSX10.12.sdk/" - -* macOS minimum deployment target: - You can specify a custom macOS minimum deployment target with the - option: - - --macos-deployment-target=<value> - - e.g.: "--macos-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. +This is a distutils setup-script for the Qt for Python project. +For more information see README.md """ import os |