开发应用

应用开发快速入门

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

简介

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

Shotgun Software 维护和发布的应用和插件全部开源,并可从 GitHub 获取:https://github.com/shotgunsoftware

入门应用模板

当您着手开发新应用时,我们建议您前往 https://github.com/shotgunsoftware/tk-multi-starterapp 了解一下我们的入门应用!这是一个“空白”的应用,您可以使用它作为构建新应用的基础。使用此应用,您可以获得所有的标准工具包样板代码。

Fork 一个现有应用

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

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

从头开始创建新应用

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

创建开发沙盒

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

Fork 或下载入门应用库

最简单的入门方法是 Fork 我们的入门应用。该应用位于此处:https://github.com/shotgunsoftware/tk-multi-starterapp

如果您现在还不想使用 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 内运行起来!

您的开发沙盒中会有一个特定的 tanktank.bat 二进制文件,您可以使用它实现这个特殊配置。打开终端并导航到您的开发沙盒。使用本地 tank 命令,运行 install_app 命令。在安装应用时,您需要选择要将应用安装到的环境和插件。插件是您要运行的应用程序,因此可以是 tk-mayatk-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,应该会看到这个入门应用出现在菜单上!

模板入门应用剖析

位于 https://github.com/shotgunsoftware/tk-multi-starterapp 的模板入门应用包含以下基本结构:

  • 应用入口点和菜单注册信息可在 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 非常方便。

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

0 评论

登录写评论。