应用开发快速入门

简要介绍应用开发以及如何使用 Shotgun Pipeline Toolkit 轻松开发新工具。

简介

Shotgun Pipeline Toolkit 不仅是 Shotgun Software 维护的一套应用和插件，还是一个框架，以及一个可用来轻松快速构建自定义工作流工具的开发平台！本文档概述了这两种情况下的工作流，并介绍了一些关于应用开发的基础知识。

Shotgun Software 维护和发布的应用和插件全部是开源的，并可从 GitHub 获取

入门应用模板

当您着手开发新应用时，我们建议您了解一下我们的入门应用！了解一下我们的入门应用！这是一个“空白”的应用，您可以使用它作为构建新应用的基础。使用此应用，您可以获得所有的标准工具包样板代码。

Fork 一个现有应用

由于所有 Shotgun Toolkit 应用都是开源的，因此我们也可使用它们的源代码作为基础，进行进一步的应用开发。如果您觉得我们的某个默认应用缺少某项重要功能，可以在 GitHub 中克隆它，然后自己继续开发！我们欢迎大家提出 Pull 请求。因此，如果您觉得自己的更改对其他人有益，请随时以 Pull 请求的形式反馈给我们。我们可以随后将更改合并到应用的主版本中。

如果您认为我们缺少的功能一般来说是有用的功能，欢迎通过 support@shotgunsoftware.com 与我们联系，我们很乐意听取您的想法 - 也许我们已计划要实施这项修改，或者知道其他客户已做过这样的修改，又或者有其他方法可以实现相同的效果！我们非常希望了解客户认为我们应用的当前版本缺少哪些功能。

从头开始创建新应用

本部分介绍如何使用我们的入门模板创建新应用。我们假设您熟悉 GitHub 和 Git 工作流。但是请注意，即使您不使用 Git 作为源代码管理解决方案，也可以进行 Toolkit 开发。

创建开发沙盒

在进行其他任何操作之前，建议您先通过克隆项目配置来设置一个开发沙盒。这将为您提供一个单独的配置，您可以在其中进行开发和修改（有时也会弄出错误！），而不会影响生产环境中的其他人。您可以在以下文档中找到关于配置克隆的详细说明：

> 管理您的 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 更新应用时，所有不符合最低版本要求的已配置框架都将随应用一起自动更新。

有关框架及其用途的详细信息，请参见以下链接：

> QT 控件框架

> Shotgun 实用程序框架

将您的新库添加到环境

现在，我们要让这个应用在 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 参考文档包含用于操作上下文、文件系统模板和系统中其他核心机制的所有命令。

> 平台 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 非常方便。

动画电影“Big Buck Bunny”（大雄兔）由 (CC) Blender Foundation (www.blender.org) 提供

开发应用