========================= wxPython 项目 Phoenix

.. image:: demo/bitmaps/splash.png :align: center

简介

欢迎来到wxPython的Phoenix项目！Phoenix是改进后的下一代wxPython，"比以前更好、更强、更快"。这个新实现专注于提高速度、可维护性和可扩展性。就像"经典"wxPython一样，Phoenix封装了wxWidgets C++工具包，并提供了对wxWidgets API用户界面部分的访问，使Python应用程序能够在Windows、Mac或Unix系统上拥有原生GUI，具有原生外观和感觉，并且几乎不需要（如果有的话）任何特定于平台的代码。

.. note:: 本文档主要面向那些将在wxPython上工作或至少直接从GitHub获取源代码进行构建的人。如果你不属于这种情况，请参考wxPython网站<https://wxpython.org/pages/downloads/>_上的说明，了解如何获取适用于你的平台和所选Python环境的当前wxPython发布版。

.. contents:: 目录

如何构建wxPython Phoenix

首先，本README主要面向那些想要从wxPython Phoenix仓库检出的工作空间构建wxPython的人。如果你不是在对wxPython进行修改，或者不需要为某些不受支持的编译器或其他硬件架构构建它，那么你可能不需要让自己经历这种构建方式的痛苦。这是一个复杂的构建过程，有时即使对专家来说也可能令人困惑。相反，如果PyPI上可用的二进制文件不符合你的需求，你可以使用pip从发布的源代码归档或预发布快照构建中创建的源代码归档进行构建。请参阅以下网址的相关说明：

接下来，请查看下面关于先决条件的部分。

wxPython Phoenix构建的所有方面都通过build.py脚本提供的一系列命令来管理。对于那些习惯于标准distutils或setuptools类型构建的人来说，还有一个setup.py脚本可用。setup.py脚本假定所有代码生成步骤已经完成，因此它适用于从源代码快照tarball构建或使用easy_install或pip时使用。setup.py脚本将委托build.py进行实际构建，而build.py在执行类似setuptools的操作（如执行安装或构建wheel）时将委托给setup.py。

使用build.py脚本比setup.py允许对构建过程进行更大的控制，包括执行各种代码生成步骤的命令。因此，在Phoenix本身上工作或从Git检出构建的开发人员，而不是从源代码快照tarball构建的人，应该使用build.py脚本。build.py脚本提供了一个相当简单的命令行界面，由命令和选项组成。要查看完整列表，请运行python build.py --help。最重要的命令如下所列。

**Windows用户注意：**如果你在Windows上构建Phoenix，并且安装了非英语版本的Microsoft Visual Studio，那么你可能需要在控制台窗口中设置代码页，以避免Unicode解码错误。例如：

chcp 1252
python build.py <构建命令>...

此外，构建中的一些任务目前期望能够在Windows上使用Cygwin（https://www.cygwin.com/）来完成工作。如果你已经在默认位置之一（c:\cygwin或c:\cygwin64）安装了Cygwin，那么一切都很好。如果你将其安装在其他地方，则可以在环境中设置CYGWIN_BASE，构建工具将使用它作为基本目录。

另一方面，如果你只想使用setup.py进行标准的setuptools风格构建，并且使用的是完整的源代码tarball，那么你可以在此处停止阅读。如果你想从源代码仓库检出构建，或需要进行更改和/或重新生成一些生成的源文件，请继续阅读。

构建wxWidgets

由于build.py默认会构建wxWidgets和Phoenix，你还需要wxWidgets代码。源代码tarball已经包含了wxWidgets和Phoenix源代码，所以如果你是通过这种方式获取源代码的，那么你就已经准备好了。如果你是从GitHub获取的，你需要执行一个额外的步骤。git仓库设置为将wxWidgets代码作为git"子模块"引入，所以在克隆Phoenix仓库后，你可以使用以下命令获取wxWidgets源代码：

$ git submodule update --init --recursive

这将把wxWidgets仓库克隆到：Phoenix/ext/wxWidgets。一旦子模块更新完成，构建脚本应该能够构建wxWidgets。

如果你更愿意使用已经构建和安装的wxWidgets，那么通过更改一些选项也是可能的，有关详细信息，请参阅python build.py --help。但是请注意，这样做将需要一个与Phoenix代码非常接近的wxWidgets版本，至少对于未发布的预览快照而言是这样。换句话说，wxWidgets构建应该使用与Phoenix代码检出时间相差几天内的wxWidgets源代码仓库中的代码。目前，Phoenix的master分支正在跟踪wxWidgets的master分支。

另一方面，最好还是让wxPython构建并捆绑wxWidgets。默认情况下，构建工具将以一种允许将wxWidgets与wxPython扩展模块捆绑在一起作为wxPython包的一部分的方式构建wxWidgets，这意味着它可以与你可能已经安装的任何wxWidgets库和平共存。这种wx共享库的捆绑在Windows、OSX和Linux上都有效，可能还包括任何其他使用基于ELF标准的共享库的类Unix系统。这些库的构建方式使其可重定位，这意味着它们不必位于文件系统上的固定位置就可以被wxPython扩展模块找到。这也意味着你可以做一些事情，比如使用pip在一个或多个虚拟环境中安装wxPython wheel，将wx包移动到版本化文件夹，甚至如果需要的话，将其移动到你自己的项目中，所有这些都不需要重新构建二进制文件。（当然，假设在所有情况下都使用兼容的Python。）

build.py脚本的构建阶段将把wxWidgets和Phoenix构建的结果复制到Phoenix源代码树中的wx文件夹中。这将允许你直接从源代码树运行和测试Phoenix，而无需安装它（如果需要的话）。你只需适当设置PYTHONPATH，或者你可以使用python setup.py develop或pip install -e .在当前Python site-packages文件夹中安装一个.egg-link文件，该文件将指向你构建wxPython Phoenix的文件夹。当你完成测试后，你可以像对待其他Python包一样使用install或bdist命令之一。

重要的build.py命令

以下build.py命令是从头开始构建Phoenix所必需的。换句话说，从一个pristine源代码树开始，其中还没有生成的代码。它们可以单独运行，也可以按给定的顺序在单个命令行上指定所有命令。一旦一个命令在build.py的一次运行中成功，就不需要在以后的运行中再次运行该命令，除非你更改了该命令负责处理的内容。许多命令需要早期命令的结果，所以至少在你第一次运行构建时，你需要按给定顺序使用所有4个命令（或它们的复合命令等效项）。

dox：从wxWidgets文档源构建XML文件，这将作为etg命令的输入。
etg：从dox XML文件中提取信息，对提取的数据结构运行手写的调整代码，并对结果运行各种生成器以生成下一步的代码。这一步骤中为每个项目运行的代码位于Phoenix源代码树中的etg文件夹中。
sip：此命令处理etg命令中生成的文件，并生成将成为wxPython Phoenix Python扩展模块的C++代码。
build：构建wxWidgets和wxPython。如果只想构建其中一个，还有其他命令可用。构建结果将放在Phoenix/wx文件夹中，如果需要,可以通过设置PYTHONPATH让Python找到Phoenix/wx包目录,从而无需安装即可使用。

一些其他有用的命令和选项：

clean：清理之前build.py运行产生的构建产物。还有其他clean命令可以清理部分构建内容。
touch：更新所有etg脚本的时间戳，以强制在下次构建时重新运行它们。当wxWidgets文档发生变更需要在构建中传播时这很有用，因为etg命令还不能完全检查输入的依赖关系。
M.N：这是要构建扩展模块的Python主版本号和次版本号,如"3.3"。这允许你用不同于构建目标的Python运行build.py,这对于需要为其他版本构建的虚拟环境中运行的构建机器很方便。

如果build.py无法根据命令行中的M.N找到正确的Python,你可以用"--python"选项指定想要使用的python可执行文件的完整路径。
test：运行Phoenix的所有单元测试。
--nodoc：此选项在运行etg脚本时关闭sphinx生成器。如果你不打算生成文档,这将加快etg命令的处理速度。

请查看"python build.py --help"的输出,了解这里未提及的命令和选项信息。如果本文档与build.py脚本中的源代码有任何不一致,以源代码为准。

build.py脚本会根据需要为你的平台下载doxygen、sip和waf,如果它们还不在你的Phoenix/bin文件夹中。如果你的平台没有预构建版本的这些工具,build.py将会报错退出。要继续构建,你需要获取适用于你平台的工具副本,然后按错误消息中的说明使用环境变量告诉build.py在哪里找到它。

构建命令行示例

要从完全干净的git工作空间进行完整构建,你需要使用上面列出的几个命令。例如:

python build.py dox etg --nodoc sip build

如果没有需要重新运行某些命令的变更,后续构建可以省略一些命令。例如,如果你只想重新构建Phoenix扩展模块,可以这样做:

python build.py build_py

如果你更改了某个etg文件,需要重新生成和重建受该更改影响的源码,可以使用如下命令:

python build.py etg --nodoc sip build build_py

项目目录结构

这个目录下有很多子文件夹,以下是对新手的简要解释:

build：构建过程产生的中间文件存储在这里。这个文件夹不应提交到源代码仓库。
buildtools：这是一个Python包,包含build.py和setup.py使用的模块,用于配置和运行构建。
etg："提取器-调整器-生成器"脚本存储在这里。这些脚本由构建调用,它们会读取Doxygen生成的XML文件,并为SIP生成接口定义文件。
etgtools：这个Python包包含用于解析XML文件、调整解析器生成的对象集合,以及后端代码或文档生成的模块。
ext：这个文件夹包含Phoenix使用的外部项目(目前只有wxWidgets)的源码,作为git子模块。这允许Phoenix使用其他项目代码的特定版本,而不依赖于开发者自己获取正确版本的代码。

当你首次用git检出Phoenix源码时,需要告诉git也获取子模块,像这样:

cd Phoenix git submodule init git submodule update --recursive
sip/gen：ETG脚本生成的代码(.sip文件)放在这个文件夹中。
sip/cpp：运行SIP时生成的代码放在这个文件夹中。它包括C++源码和头文件,以及一些包含生成的源文件信息的额外文件,以便构建知道要编译哪些文件。
sip/siplib：这是SIP运行时库的副本。我们有自己的副本,以便将其作为具有唯一名称(wx.siplib)的扩展模块包含在wxPython构建中,并且不要求目标系统上安装SIP作为运行时依赖。希望与wxPython集成的第三方扩展应确保它们"#include"的sip.h是这个文件夹中的版本。
src：这个文件夹用于任何其他手动编辑而不是由某些工具生成的源代码(SIP、C++、Python或其他任何内容)。
wx：这是wxPython包的顶层。对于就地构建,扩展模块和任何相关文件将放入这个文件夹。子文件夹包含wx包的纯Python子包,如wx.lib等。

文件命名

为了在查找需要处理的内容时更容易一些,Phoenix项目中的文件名将与wxWidgets接口头文件夹中的文件名相呼应。例如,如果有一个interface/wx/FOO.h,我们正在处理为该文件生成的XML,那么用于处理这些类和其他项目的ETG脚本将命名为etg/FOO.py,它将生成sip/gen/FOO.sip,单元测试将在unittests/test_FOO.py中,以此类推。

在大多数情况下,多个ETG/SIP文件将用于创建单个Python扩展模块。在这些情况下,将有一个ETG脚本用于将所有其他脚本整合到单个扩展模块中(例如,通过使用后端生成器的include功能)。这些脚本的名称将以下划线开头,如etg/_core.py,所有打算包含在该扩展模块中的脚本都应在其MODULE变量中指定该名称。

先决条件

以下是一些关于自行构建Phoenix所需内容的提示。可能还有一些其他未在此处提及的内容,如果你发现应该提及的其他内容,请提交PR更新本文档。

Windows

wxWidgets和wxPython Phoenix所需的所有源代码都包含在wxWidgets和Phoenix源码树中。除了标准的Python安装,你还需要Visual Studio 2008(用于Python 2.7兼容性)或Visual Studio 2015(用于Python 3.x支持)的副本。使用Mingw32构建也应该可能,但需要对构建脚本进行一些修改以支持它。

你可能还想获取MS SDK的副本,以获得Windows API的较新定义。我通常在Visual Studio 2008中使用7.0或7.1版本。

不幸的是,Microsoft不再分发Visual Studio 2008。但不要慌!他们最近提供了一个"Microsoft Visual C++ Compiler for Python 2.7"包,也可用于为Python 2.7构建Phoenix。而且它是免费的!你可以在这里获取:http://www.microsoft.com/en-us/download/details.aspx?id=44266

如果你想构建带有调试信息的Phoenix,则需要首先构建Python的调试版本,然后使用该Python(python_d.exe)来构建Phoenix。

Linux 在Ubuntu上，应该安装以下开发包及其依赖项以构建Phoenix。其他类似debian的发行版可能也有这些或类似名称的软件包可用，或者较新版本的Ubuntu可能已有所演变，需要对此列表进行修改。根据其他Linux发行版或其他Unix系统相应地推断其他包名。