Open-Source PyMOL 安装构建全指南:从 README 到源码的分子可视化系统构建解析

原创2026-10-14 16:25:081,874 阅读
文章标签:图形学科学计算生物信息学桌面应用

Open-Source PyMOL 安装构建全指南:从 README 到源码的分子可视化系统构建解析

本文基于 Open-Source PyMOL 仓库的 README 及其直接关联的 INSTALL、DEVELOPERS、LICENSE 文档展开,梳理该项目的定位、依赖要求、完整安装命令、构建参数默认值与运行方式,并延伸到测试框架与贡献规范。读完后你将能够:在自己的机器上从源码编译安装 PyMOL,正确配置 PYMOL_PATH 等环境变量,理解 pip 安装背后自定义构建后端(PEP 517)的工作机制,并知道如何运行其 Python 与 C++ 双层测试。

一、项目定位:Open-Source PyMOL 是什么

README.md 对项目的定义十分凝练:

Open-source foundation of the user-sponsored PyMOL molecular visualization system.

即 Open-Source PyMOL 是用户资助型 PyMOL 分子可视化系统的开源基础,商业版(Incentive PyMOL)则提供维护与支持。仓库 pyproject.toml 中的项目描述进一步说明了能力范围:

description = """
PyMOL is a Python-enhanced molecular graphics tool.
It excels at 3D visualization of proteins, small molecules, density,
surfaces, and trajectories. It also includes molecular editing,
ray tracing, and movies. Open Source PyMOL is free to everyone!
"""

从这段描述可以确认其核心功能域:蛋白质、小分子、电子密度、表面与轨迹的 3D 可视化,外加分子编辑、光线追踪(ray tracing)和电影(动画)生成。

README 正文其余部分由三个入口构成,本文逐一深入:

README 章节 指向文档 本文对应章节
Installation INSTALL 第三、四、五节
Contributing DEVELOPERS 第八节
License LICENSE 第二节

License 说明版权方为 Schrodinger, LLC,以 BSD-like license 发布;LICENSE 全文授予"使用、复制、修改、分发及分发修改版"的权利,前提是保留版权声明、不得使用 Schrodinger, LLC 名称做广告宣传;同时附有条款要求含 PyMOL 源码的衍生软件在宣传中必须与 Schrodinger 官方产品明确区分(PyMOL 商标声明)。

README 顶部还带有 CI 徽章,对应仓库中的 build.yml GitHub Actions 工作流:该工作流在 ubuntu-22.04 上对 Python 3.10 ~ 3.13 做矩阵构建,测试命令为:

pymol -ckqy testing/testing.py --run all

二、仓库结构速览(帮助理解安装产物从哪里来)

理解安装流程前,先快速建立对源码布局的认知(以 INSTALL 与 setup.py 中的引用为准):

三、编译安装:依赖要求

INSTALL 列出了源码编译的全部前置条件。核心依赖是:

依赖 是否必需 说明
C++17 编译器(gcc 8+) 必需 CMakeLists.txt 中以 target_compile_features(... cxx_std_17) 强制 C++17
CMake 3.13+ 必需 与 cmake_minimum_required(VERSION 3.13) 一致
Python 3.9+ 必需 与 pyproject.toml 的 requires-python = ">=3.9" 一致
pip + build 子模块 必需 pip install build(conda 包名为 python-build)
OpenGL / GLEW / glm 必需 渲染三件套
libpng / freetype 必需 图像与字体
Pmw(Python Megawidgets) 可选 传统 GUI/插件需要
GLUT(freeglut) 可选 --glut=true 启用
libxml2 可选 COLLADA 导出,--libxml=no 关闭
msgpack-c 2.1.5+ / mmtf-cpp 可选 快速 MMTF 加载与导出,--use-msgpackc=no 关闭
PyQt5 / PyQt6 / PySide2 / PySide6 可选 缺失时若以 --glut=true 编译则回退 Tk 界面
catch2 可选 --testing=true 启用 C 层测试
openvr 1.0.x 可选 --openvr=true 启用 VR 支持
libnetcdf 可选 VMD molfile 插件,--vmd-plugins=no 关闭

注意一个细节:pyproject.toml 中运行时唯一声明的 Python 依赖是 numpy>=2.0,其余(freetype、GLEW 等)都是 C 层系统库,需要预先安装到系统或写入搜索路径——这正是 INSTALL 中 PREFIX_PATH 等环境变量的用途。

四、安装命令与环境变量

4.1 两条标准安装命令

INSTALL 给出两种安装方式:

# 干净构建并安装
pip install .

# 推荐开发者使用(保留构建输出、支持增量构建、同时构建 C++ 单元测试)
pip install --verbose --no-build-isolation --config-settings testing=True .

第二条命令里有两个关键点值得展开:

  1. --no-build-isolation:跳过 pip 的隔离构建环境,直接复用本机已装好的 CMake/numpy/setuptools([build-system] requires 声明的三件套);
  2. --config-settings testing=True:pip 把该键值传给 PEP 517 构建后端。本项目用了一个自定义后端 _custom_build/backend.py(pyproject.toml 中 backend-path = ["_custom_build"]、build-backend = "backend" 指定):
class _CustomBuildMetaBackend(backend_class):
    def run_setup(self, setup_script="setup.py"):
        if self.config_settings:
            flags = [
                f"--{k}={v}"
                for k, v in self.config_settings.items()
            ]
            sys.argv = sys.argv[:1] + ["build_ext"] + flags + sys.argv[1:]
        return super().run_setup(setup_script)

也就是说,pip 的 --config-settings k=v 会被原样翻译成 setup.py build_ext --k=v 的命令行参数。这就解释了为什么所有构建开关既可以从 pip 传(--config-settings glut=true),也可以直接 python setup.py build_ext --glut=true。

4.2 构建开关与默认值

setup.py 用 argparse 定义了完整的开关集,其默认值集中在 setup.py:

参数 默认值 作用
--glut False 链接 GLUT(传统 GUI)
--osx-frameworks True macOS 上用原生框架而非 XQuartz
--jobs / -j 处理器数 并行编译
--libxml True 关闭则禁用 COLLADA 导出
--use-openmp 非 macOS 为 yes OpenMP 支持
--use-vtkm no 用 VTK-m 做等值面,可选 2.0~2.3
--use-msgpackc guess c++11/c/guess/no,控制 MMTF 快速路径
--testing False 构建 C 层测试(catch2)
--openvr False VR 支持
--vmd-plugins True VMD molfile 插件(依赖 libnetcdf)

布尔参数通过 str2bool(setup.py)解析,接受 true/yes 与 false/no。

依赖库的搜索路径由 PREFIX_PATH 环境变量控制(setup.py 的 get_prefix_path()):冒号分隔的目录列表,构建时在其中查找 include、lib、lib64 等子目录。例如把 msgpack-c 装在 ~/msgpack-c、mmtf-cpp 装在 ~/mmtf-cpp,则:

export PREFIX_PATH=$HOME/mmtf-cpp:$HOME/msgpack-c

其余标准环境变量沿用工具链惯例(INSTALL):CXX/CC 指定编译器命令,CXXFLAGS/CFLAGS/CPPFLAGS/LDFLAGS 分别传编译与链接参数。

4.3 特殊安装选项与环境变量

  • --pymol-path=:指定 PyMOL 数据安装目录(对应 $PYMOL_PATH),见 setup.py 中 install_pymol_path 的处理;
  • --no-launcher:跳过 pymol 启动脚本的安装;
  • 系统包管理器场景下,PACKAGING 推荐:
python setup.py install --pymol-path=/usr/share/pymol

并把 modules/ 下的 Python 包放入 site-packages,data/、scripts/ 放入 /usr/share/pymol/(运行时必须)。

4.4 运行环境变量的自动推导

PACKAGING 说明,常规安装无需手动设置环境变量,PyMOL 启动时会按优先级自行推导:

PYMOL_PATH = 依次取:
  - <pymol python module> + "/pymol_path"
  - 启动脚本匹配 "modules/pymol/__init__.py" 时取 modules 目录的父目录
  - sys.prefix + "/share/pymol"
PYMOL_DATA    = $PYMOL_PATH/data
PYMOL_SCRIPTS = $PYMOL_PATH/scripts

因此只要 pymol Python 包正常安装,数据文件路径就能被自动找到;只有当数据被安装到非默认位置时,才需要显式 export PYMOL_PATH=...(modules/pymol/init.py 开头的文档字符串也明确提示了这一点)。

五、启动方式

INSTALL 指明安装后的入口:

$PYMOL_PATH/bin/pymol
# 或
$PYTHONUSERBASE/bin/pymol

pymol 命令由 pyproject.toml 的入口点声明提供:pymol = "pymol:launch"。除此之外,modules/pymol/init.py 的文档注释列出了全部支持方式:

# 1) 直接以脚本运行
shell> python /path/to/pymol/__init__.py [args]

# 2) pymol 模块在 PYTHONPATH 中时
shell> python -m pymol [args]
# 3) 在 Python 主线程内(阻塞解释器)
import pymol
pymol.launch()

# 4) 主线程内派生新线程(带 GUI;macOS 不支持此方式)
import pymol
pymol.finish_launching()

modules/pymol/main.py 则实现了 python -m pymol 入口:sys.exit(pymol.launch())。

六、构建产物与 CMake 的关系

顶层 CMakeLists.txt 并不完整——它依赖 setup.py 先行收集源码(get_sources() 扫描各 layer 目录下的 .c/.cpp)并通过变量 TARGET_NAME、ALL_SRC、ALL_COMP_ARGS 等注入:

add_library(${TARGET_NAME} SHARED ${ALL_SRC})
target_compile_features(${TARGET_NAME} PRIVATE cxx_std_17)

即 CMake 只负责把 C++ 核心编成一个共享库(供 Python 扩展加载),而依赖发现、源码收集、着色器文本生成(create_shadertext,见 setup.py 与独立脚本 create_shadertext.py)、PYMOL_PATH 数据复制、启动脚本生成都由 setup.py 编排。这是阅读构建逻辑时应记住的主从关系:pip → 自定义后端 → setup.py → CMake。

版本号并非独立配置,而是解析 layer0/Version.h 中 _PyMOL_VERSION "..." 宏得到(setup.py)。结合 ChangeLog 可见当前主线版本为 3.1.0(2025-01-24),新增 BCIF 导入、压缩 SDF 导入、delete_states 命令等;上一版 3.0.0(2024-04-09)引入了卤键检测、fnab 命令与改进的 CGO builder API。

七、测试:Python 框架 + C++ 单元测试 + CI

仓库提供三层测试能力,均可从 README 的 CI 徽章入口找到实证:

  1. Python 测试框架(testing/,pytest 驱动,配置见 testing/pytest.ini)。testing/README.md 说明每个测试方法基于一个干净的 PyMOL 会话(reinitialize)并从测试文件所在目录启动;运行方式:

    pymol -cq /path/to/pymol-testing/runall.pml
    # 或 PyMOL 命令行内
    PyMOL> run /path/to/pymol-testing/testing.py
    PyMOL> run_testfiles path/to/*.py
    
  2. C++ 单元测试(layerCTest/,catch2 框架)。构建时需 --testing=True(开发者安装命令即如此),CI 工作流中通过 pip install -v --config-settings testing=True '.[dev]' 启用。

  3. CI 工作流(build.yml):Linux 矩阵覆盖 Python 3.10~3.13,系统依赖包括 catch2、libfreetype6-dev、libglew-dev、libglm-dev、libmsgpack-dev、libnetcdf-dev、libpng-dev、libxml2-dev,并额外 clone mmtf-cpp 头文件到 include/;最终测试命令 pymol -ckqy testing/testing.py --run all 即上文 Python 框架的入口。

八、贡献路径与许可证约束

DEVELOPERS(PyMOL Developer Notice,2006-01-28)定义了三种参与方式,各自的版权与许可证约束不同:

  1. 在主源码树上工作:改进代码的版权须转让给 Schrodinger, LLC(或放入公有领域),且不得附加任何超出 LICENSE 的条件。方式是在每个源文件头部加入版权转让或公有领域声明(文档中给出了两段标准注释模板)。
  2. 在 contrib/ 目录开发自包含功能:可保留自己的版权,但代码必须采用 "Python" 许可证或同等宽松许可(即无限制免费使用的 BSD 风格条款,文档内附完整注释模板)。仓库现存的 contrib/champ/、contrib/mmtf-c/ 等正是此模式的实例。
  3. 开发基于 PyMOL Python API 的独立项目:可不受 PyMOL 发行版约束、自行决定许可;但若希望并入官方 PyMOL 发行包,须采用 PyMOL 许可证或同等宽松开源许可证(明确注明 GPL 不允许)。

九、快速参考清单

# 1. 装好系统依赖(freetype/GLEW/glm/libpng/msgpack-c/mmtf-cpp 等)
# 2. 指定依赖搜索路径(如适用)
export PREFIX_PATH=$HOME/mmtf-cpp:$HOME/msgpack-c

# 3a. 普通安装
pip install .

# 3b. 开发者安装(增量构建 + C 层测试)
pip install --verbose --no-build-isolation --config-settings testing=True .

# 4. 运行
$PYMOL_PATH/bin/pymol        # 安装后
python -m pymol              # 模块在 PYTHONPATH 时
pymol.launch()               # Python 内嵌

# 5. 跑测试
pymol -ckqy testing/testing.py --run all

适用前提与限制:以上流程基于当前仓库主线(3.1.0 开发线),要求 Python ≥ 3.9、CMake ≥ 3.13、C++17 编译器;PYMOL_PATH/PYMOL_DATA/PYMOL_SCRIPTS 仅当数据目录非默认位置时需要手工设置;Qt 界面与 GLUT/Tk 回退、VTK-m 等值面、OpenVR 等均为可选项,按需通过对应开关启用即可。

登录后查看全文
pymol-open-source