![]() |
应用开发快速入门简要介绍应用开发以及如何使用 Shotgun Pipeline Toolkit 轻松开发新工具。 |
目录:
简介
Shotgun Pipeline Toolkit 不仅是 Shotgun Software 维护的一套应用和插件,还是一个框架,以及一个可用来轻松快速构建自定义工作流工具的开发平台!本文档概述了这两种情况下的工作流,并介绍了一些关于应用开发的基础知识。
Shotgun Software 维护和发布的应用和插件全部是开源的,并可从 GitHub 获取
入门应用模板
当您着手开发新应用时,我们建议您了解一下我们的入门应用!了解一下我们的入门应用!这是一个“空白”的应用,您可以使用它作为构建新应用的基础。使用此应用,您可以获得所有的标准工具包样板代码。
Fork 一个现有应用
由于所有 Shotgun Toolkit 应用都是开源的,因此我们也可使用它们的源代码作为基础,进行进一步的应用开发。如果您觉得我们的某个默认应用缺少某项重要功能,可以在 GitHub 中克隆它,然后自己继续开发!我们欢迎大家提出 Pull 请求。因此,如果您觉得自己的更改对其他人有益,请随时以 Pull 请求的形式反馈给我们。我们可以随后将更改合并到应用的主版本中。
如果您认为我们缺少的功能一般来说是有用的功能,欢迎通过 support@shotgunsoftware.com 与我们联系,我们很乐意听取您的想法 - 也许我们已计划要实施这项修改,或者知道其他客户已做过这样的修改,又或者有其他方法可以实现相同的效果!我们非常希望了解客户认为我们应用的当前版本缺少哪些功能。
从头开始创建新应用
本部分介绍如何使用我们的入门模板创建新应用。我们假设您熟悉 GitHub 和 Git 工作流。但是请注意,即使您不使用 Git 作为源代码管理解决方案,也可以进行 Toolkit 开发。
创建开发沙盒
在进行其他任何操作之前,建议您先通过克隆项目配置来设置一个开发沙盒。这将为您提供一个单独的配置,您可以在其中进行开发和修改(有时也会弄出错误!),而不会影响生产环境中的其他人。您可以在以下文档中找到关于配置克隆的详细说明:
Fork 或下载入门应用库
最简单的入门方法是 Fork 我们的入门应用。该应用位于此处。
如果您现在还不想使用 Git 源代码管理方案,可以只从 GitHub 下载 zip 格式的文件,然后在磁盘的某个位置解压缩这些文件。稍后可以轻松将其添加到 Git(或其他源代码管理软件包)。如果您确定需要使用 Git 库,也可以在自己的 Git 服务器上 Fork 入门应用的库,然后将内容检出到您本地的开发环境。无论使用哪种方法,目的都是将入门应用的代码加入本地开发环境中,以便可以开始开发。
添加参数和框架
如果您确定将会使用框架或者需要特定的清单文件参数,此阶段是完成这些设置的好时机!因为在下一步中,当我们将应用安装到环境中时,系统会自动帮您完成所有配置。
例如,如果您计划为应用使用控件和 Shotgun 实用程序框架,请将以下内容添加到 info.yml
清单文件中:
# the frameworks required to run this app frameworks: - {"name": "tk-framework-shotgunutils", "version": "v2.x.x"} - {"name": "tk-framework-qtwidgets", "version": "v1.x.x"}
框架版本最低要求
如果框架对版本有最低要求,可以在清单文件中使用minimum_version
设置:info.yml
# the frameworks required to run this app frameworks: - {"name": "tk-framework-shotgunutils", "version": "v2.x.x"} - {"name": "tk-framework-qtwidgets", "version": "v1.x.x", "minimum_version": "v1.5.0"}
上面的代码将确保应用可以使用 v1.5.0
版本的 tk-framework-qtwidgets
。如果这个版本不可用,应用将不会在启动时加载,并在控制台显示错误。当使用 tank updates
更新应用时,所有不符合最低版本要求的已配置框架都将随应用一起自动更新。
有关框架及其用途的详细信息,请参见以下链接:
将您的新库添加到环境
现在,我们要让这个应用在 Toolkit 内运行起来!
您的开发沙盒中会有一个特定的 tank
或 tank.bat
二进制文件,您可以使用它实现这个特殊配置。打开终端并导航到您的开发沙盒。使用本地 tank
命令,运行 install_app
命令。在安装应用时,您需要选择要将应用安装到的环境和插件。插件是您要运行的应用程序,因此可以是 tk-maya
或 tk-nuke
等。环境是您想对特定工作区域运行的一系列工具。在我们的默认配置中,当处理镜头时,环境称为 shot_step
,当处理资产时,环境称为 asset_step
。
例如,如果您的新应用代码位于 /Users/manne/dev/tk-multi-mynewapp
中,可运行以下命令进行安装:
> cd /your/development/sandbox > ./tank install_app shot_step tk-maya /Users/manne/dev/tk-multi-mynewapp
安装命令将自动安装您的应用需要的所有框架。现在,如果您为刚刚安装应用的环境启动 Maya,应该会看到这个入门应用出现在菜单上!
模板入门应用剖析
模板入门应用包含以下基本结构:

- 应用入口点和菜单注册信息可在
app.py
文件中找到。这里通常是设置类、进行初始化和注册菜单项的地方。 - 清单文件定义此应用安装时需要的所有不同设置。当您需要可重用的应用、不想以硬编码方式向应用本身写入任何值时,这些设置通常非常有用。
dialog.py
文件包含逻辑和事件回调等。这将生成主应用窗口。dialog.py
文件会加载位于 UI 文件夹中的一个自动生成的控件文件。此文件包含对话框用户界面的所有基本布局和属性。- 在 resources 文件夹中,
dialog.ui
文件是一个 QT Designer 文件,您可以打开并使用它快速设计和定义应用的外观。完成更改后,您需要执行构建脚本,将 UI 文件转换为 Python 代码。
开发
现在一切准备就绪,您可以开始开发了!为方便起见,只要您的配置中有一个或多个开发项,Toolkit 就会自动向 Maya、Nuke 等应用程序内的菜单中添加一个“Reload and Restart”选项。单击此选项将重新加载您的配置和代码,然后重新启动插件。这意味着您可以快速进行迭代:只需启动 Maya 一次,之后每次做出所需的代码或配置更改时,只需单击“Reload and Restart”按钮,即可调用这些更改。请注意,如果屏幕上有任何用户界面处于激活状态,这些用户界面将不会自动更新,您必须进入菜单重新启动它们。
测试
当您想要测试代码时,可以轻松邀请其他用户访问您的开发沙盒,方法是将他们添加到 Shotgun 的工作流配置项中。添加完用户后,他们将在自己 Shotgun 内的菜单上看到新的菜单项。

然后,他们可以进入菜单,例如单击与您的开发沙盒关联的“Launch Maya”菜单项。当 Maya 启动时,他们会从您的配置中运行它,并像您一样,可以看到您当前正在进行的工作。注意:还要确保他们有权限查看您的应用代码,否则应用将不会加载。
准备第一个版本发布
当您认为已经准备好创建第一个版本发布时,如果您尚未使用源代码管理工具,我们建议您开始使用这类工具,以确保所做的更改能得到跟踪。Toolkit 从一开始就支持 Git (http://git-scm.com/),因此我们强烈建议您使用此工具。本文档的其余部分假定您熟悉 Git,并且已在自己的计算机上设置了此工具。
现在,您可能已经为自己的应用设置了 Git 库。如果还没有,请现在创建它,并 Push 您的第一个内容提交。Toolkit 的 Git 库需要只包含一个应用 - 基本上,您的 Git 库结构应该与获取源代码的入门应用库相同。
当您进行开发时,Toolkit 会在环境文件中使用一个类似如下的开发位置:
location: {path: /Users/manne/dev/tk-multi-mynewapp, type: dev}
此设置指示 Toolkit 直接从磁盘的给定位置加载应用代码,对于需要不停更改代码的开发工作来说,这种做法非常方便。
对于发布的软件,我们想确保对所有内容实施版本控制,以便它们可以安全轻松地进行升级。Toolkit 内置的所有应用均使用 Toolkit 应用商店跟踪更新和版本发布,它们带有一个类似如下的位置标记:
location: {name: tk-multi-setframerange, type: app_store, version: v0.1.7}
通过该标记,Toolkit(例如 tank updates
命令)可以检查何时有更新可用,并以一种非常安全的方式更新和维护配置。每当有新版本可用时,Toolkit 会自动下载代码,将代码放在磁盘的一个本地“应用缓存”中,并确保用户可以访问它。
对于内部工具,您也可以采用相同的原则,只是不使用 Toolkit 应用商店,而是在 Git 中使用标记。因此,对于您的新应用,请创建一个新标记并 Push 到 Git。需要注意的是,如果您克隆了我们的入门应用,这些标记是已经定义好的。在创建标记时,强烈建议您使用语义版本控制(请参见 http://semver.org)。Toolkit 将使用这些版本号尝试确定哪个版本是最新版本,按照 vX.Y.Z
这样的约定,您的应用的版本控制可以与 Toolkit 兼容。
将更改安装至生产配置
当您在 Git 中创建好第一个标记后(例如 v1.0.0
),我们便可以安全地将应用安装到您的生产配置中。这意味着生产环境中的每个人都将能够访问这个新工具。安装应用的操作通过安装应用命令来完成。运行安装命令时,请确保使用的是属于主生产配置的 tank 命令:
> cd /your/primary/tank/configuration > ./tank install_app shot_step tk-maya user@remotehost:/path_to/tk-multi-mynewapp.git
此命令将在 Git 中查找最高的版本标记,并将其安装到环境中。安装之后,您可以直接运行 tank updates
,如果已创建了新标记,程序将提示您是否要升级。此时,整个工作流便与官方应用商店的流程完全相同。
修改现有应用
有时,我们并不会使用空白的入门模板从头创建应用,而是需要为现有应用(例如 Shotgun Software 的某个标准应用)添加一项小功能。处理修改版的应用时,您通常会想要比照源应用,确保定期下载更改和错误修复。
当您进行这类开发时,首先是提取父代码,然后应用自己的更改,再将此版本发布到您的工作流中。您发布的版本实际上由应用的基础版本和您应用的本地更改组成。我们建议您为现有版本号添加版本后缀。这种做法非常适合 Toolkit,并且看起来相对直观。下面的工作流说明了整个操作:
- 您对父应用执行 Fork 操作,并创建自己的库。通过 Fork 操作,您获得所有 Git 标记。最新的标记为
v0.2.12
,主分支基本上与此标记中的内容相同。 - 您应用自己的更改,并提交至主分支。这时得到的基本上是
v0.2.12
加上您的更改。将此版本发布到生产环境时,您需要创建一个标记。将该标记命名为v0.2.12.1
,以表示您的代码基于v0.2.12
,并且是第一个版本发布。 - 现在有人发现您的修改中有一个错误。您修复此错误、更新标记并发布
v0.2.12.2
。 - 父库中发布了多项重要的错误修复。您将它们下载到您的库。由于父库中发布了若干个版本,最新标记现在为
v0.2.15
。将您的更改合并到主分支,并进行测试。这时得到的基本上是父应用v0.2.15
与您的更改合并后的结果。更新标记为v0.2.15.1
。
上面概括的标记方案可保证 Toolkit 更新能够正确工作,并且便于您快速了解 Fork 中每个标记基于哪些代码。
文档资源
除了本文档外,我们还提供其他一些对应用开发有帮助的文档资源:
核心 API 参考文档包含用于操作上下文、文件系统模板和系统中其他核心机制的所有命令。
平台 API 参考文档涵盖插件和应用基类,并包含有关编写应用代码时各种可用选项的详细信息。
应用配置参考文档概述了为应用设置参数和配置的各种方法。
以交互方式访问 Toolkit
如果您只是想用一种更具互动性的方式体验 Toolkit,可以在例如 NUKE 或 Maya 这样的应用程序中启动 Toolkit 插件,在看到 Shotgun 菜单后,轻松体验一番。您可以通过当前运行的插件访问整个 Toolkit,并且可在 Maya 或 Nuke 的 Python Shell 内按如下所示检索当前运行的插件:
import sgtk engine = sgtk.platform.current_engine()
能够访问插件后,您可以体验到当前加载的环境的其他大多数方面:
# A Shotgun API instance engine.shotgun # The toolkit API instance engine.sgtk # The current work area object engine.context # All the apps currently loaded engine.apps
如果您位于一个可访问 tank
命令的命令 Shell 中,可通过运行 tank shell
命令,轻松打开交互式 Python 会话。Toolkit 会尝试为您启动尽可能多的系统,但是根据上下文的不同,您可能会获得有限的一组访问函数:
> tank Shot ABC123 shell Welcome to the Shotgun Pipeline Toolkit! For documentation, see https://support.shotgunsoftware.com Will search across all Shotgun Projects. - Found Shot ABC123 (Project 'Chasing the Light') - Using configuration 'Primary' and Core v0.14.214 - Setting the Context to Shot ABC123. - Started Shell Engine version v0.3.4 - Environment: /mnt/software/tank/chasing_v2/config/env/shot.yml. - Running command shell... ---------------------------------------------------------------------- Command: Shell ---------------------------------------------------------------------- Welcome to Shotgun Pipeline Toolkit Python! 2.7.1 (r271:86832, Jul 31 2011, 19:30:53) [GCC 4.2.1 (Based on Apple Inc. build 5658) (LLVM build 2335.15.00)] Running on darwin - A tk API handle is available via the tk variable - A Shotgun API handle is available via the shotgun variable - Your current context is stored in the context variable - The shell engine can be accessed via the engine variable >>>
当您想要进行快速调试或运行小段脚本时,使用 Toolkit Shell 非常方便。