使用 CLI

提示

推荐集成命令行自动补齐
推荐阅读 FAQ

Usage

combo [commands] [flags]

Commands: 命令是运行 Combo CLI 的具体 Feature。可以提供命令和子命令来执行特定的 Feature。

Flags: 标志(也称为参数)，通过提供额外配置来调整命令结果的选项，Flags 分为 Global Flags 和 Command Flags

Config

CLI 依赖 combo.yaml，可以通过指令 combo configure 生成配置

combo.yaml 分为一个主键与 3 个子键，主键是的值来自于 profile，具体可看 combo configure 与 --profile

demo:
  game-id: <YOUR_GAME_ID>
  build-key: <YOUR_BUILD_KEY>
  endpoint: https://api.seayoo.com

提示

the combo.yaml file located in .combo folder ($HOME on Unix-like systems, %USERPROFILE% on Windows).

Environment variables

CLI 在操作过程中使用了一些环境变量，从而实现更大的灵活性。

COMBO_CONFIG_FILE

CLI 默认会读取用户目录 .combo/combo.yaml，设置环境变量，会读取指定的 COMBO_CONFIG_FILE

COMBO_DATA_DIR

指定 CLI 读取的 数据目录，设置环境变量，setup 和 build 指令可以不需要显示指定参数 --data-dir

GRADLE_HOME

CLI 在构建 Android APK 会调用 gradle 命令，默认优先使用 GRADLE_HOME 环境变量，如果没有会继续搜索 PATH

JAVA_HOME

CLI 在处理 Android 分包任务时，会使用 Java JDK，默认优先使用 JAVA_HOME 环境变量，如果没有会继续搜索 PATH

Commands

Commands 包含 CLI 的所有核心功能

configure
android
ios
windows

configure

配置运行 CLI 所需要的配置

警告

configure 是必须首先执行的指令

Usage

combo configure --game-id <YOUR_GAME_ID> --build-key <YOUR_BUILD_KEY>

Flags

Flag	Required	Scope	Desc
--game-id	True	Local	由世游提供
--build-key	True	Local	由世游提供，一般以`bk`开头
--endpoint	False	Local	默认使用 `https://api.seayoo.com`
--profile	False	Global	项目填写，用于创建身份信息表示，如果不填默认使用 `--game-id`，详情可见 --profile

Results

将会生成 CLI 所需要的配置文件 combo.yaml

android

警告

运行指令需要保证目录位于 Android Project Root (项目导出 Android 工程的根目录)
依赖 gradle <= 7.5.1

android 主要是作为一个命令组，包含 6 个子命令:

list-distros
init
setup
build
gen-variant
get-variant
upload-symbols

list-distros

信息

list-distros 用于列出当前游戏业务有效的 distros (由世游发行平台配置)

Usage

combo android list-distros

Result

# Examples:
android (世游官网 Android 版本)
google_play (Google Play Android 版本)
xiaomi (小米游戏中心)

init

信息

游戏研发侧如果没有需求 Reproducible Builds，不需要使用此指令
init 会根据指定的 数据目录, 生成 Combo CLI 所需要的构建数据

Usage

combo android init --data-dir <value> --distros <values>

Flags

Flag	Type	Required	Scope	Desc
--data-dir	string	True	Local	指定 CLI 构建数据的存放目录 CLI 内部会自行组织目录结构
--distros	string[]	False	Local	由世游提供发行字符串 (通过逗号分隔) Notes: 如果不指定则会生成所有

Result

combo android init --data-dir ComboData

ComboData
├── android
  ├── android
    ├── game_icon.png
    ├── distro.json
  ├── huawei
    ├── game_icon.png
    ├── distro.json
├── demo.jks
├── signing_key.json
......

setup

信息

游戏研发侧如果没有需求使用 gradle 或者 Android Studio 手动构建 APK，则不需要使用此指令
setup 内部会调用 init 指令，然后将数据目录相应的 distro 资源装配到 android project

Usage

combo android setup --distro <value> --data-dir <value>

Flags

Flag	Type	Required	Scope	Desc
--distro	string	True	Local	由世游提供发行字符串
--data-dir	string	False	Local	如果有 Reproducible Builds 需求，则需要指定 CLI 读取的数据目录

Result

Name	Type	Desc
ComboSDK.gradle	File	主要包含 Android 配置和 Dependencies
ComboSDKRepo.gradle	File	Android 所需要的仓库地址
ComboSDKSigning.gradle	File	Android 签名信息文件
ComboSDK	Folder	主要包含 Android 资源文件

build

信息

为了更便捷的构建 APK，可直接使用 build 指令，不需要 init 和 setup
build 没有黑魔法，只是使用 gradle 的命令

Usage

combo android build [--distros <value>] --data-dir <value> [--debug] [--gradle-options <values>]

Flags

Flag	Type	Required	Scope	Desc
--distros	string[]	False	Local	由世游提供发行字符串 (通过逗号分隔) Notes: 如果不指定参数会构建所有的 Distro APK
--data-dir	string	False	Local	如果有 Reproducible Builds 需求，则需要指定 CLI 读取的数据目录
--debug	bool	False	Local	是否构建 Debug 版本，若不加该参数，默认构建 Release 版本
--gradle-options	string[]	False	Local	Gradle 命令行选项，具体可参考 Gradle Command-line Options

提示

--gradle-options Flags

如需离线构建，添加 --offline 参数:
combo android build --gradle-options "--offline"
如需添加多个选项，使用 逗号（英文格式） 分隔:
combo android build --gradle-options "--stacktrace,--info,--continue"

Result

生成的 APK 会在当前 CLI 运行目录的 APKs 文件夹

gen-variant

信息

gen-variant 用于生成一个分包 (目前分包由世游负责生成)

Usage

combo android gen-variant --variant <value> --apk <value>

Flags

Flag	Type	Required	Scope	Desc
--variant	string	True	Local	世游提供的分包标识
--apk	string	True	Local	需要分包的 APK
--subvariant	string	False	Local	世游提供的二级分包标识
--output	string	False	Local	新的 APK 输出目录

Result

会根据指定的输出目录生成一个新的 APK

get-variant

信息

get-variant 从 APK 提取分包信息

Usage

combo android get-variant --apk <value>

Flags

Flag	Type	Required	Scope	Desc
--apk	string	True	Local	已分包的 APK

Result

variant=hykb
subvariant=9527

upload-symbols

信息

上传符号表至 Sentry, 应用崩溃时提供更多的信息

Usage

combo android upload-symbols --project <project> --auth-token <authToken> --symbols <symbolPath>

Flags

Flag	Type	Required	Scope	Desc
--project	string	True	Local	Sentry 项目名称获取
--auth-token	string	True	Local	研发同学登录 Sentry 后生成的 auth token 获取
--symbols	string	True	Local	符号表路径 (会递归搜索查找)

Result

上传符号表至 Sentry

ios

警告

iOS 暂时不提供 build 指令，游戏研发侧可使用 Xcode 打包
游戏研发侧需要保证 CLI 生成的 ComboSDK.json 会放置于 Xcode 工程内 (高级技巧见: Unity 自动装配)

init
setup
upload-symbols

init

信息

游戏研发侧如果没有需求 Reproducible Builds，不需要使用此指令
init 会根据指定的 数据目录, 生成 Combo CLI 所需要的构建数据

Usage

combo ios init --data-dir <value>

Flags

Flag	Type	Required	Scope	Desc
--data-dir	string	True	Local	指定 CLI 构建数据的存放目录 CLI 内部会自行组织目录结构

Result

combo ios init --data-dir ComboData

ComboData
├── ios
  ├── app_store
    ├── distro.json
......

setup

信息

setup 内部会调用 init 指令，然后在 CLI 当前运行目录生成 ComboSDK.json

Usage

combo ios setup --data-dir <value>

Flags

Flag	Type	Required	Scope	Desc
--data-dir	string	False	Local	如果有 Reproducible Builds 需求，则需要指定 CLI 读取的数据目录

Result

在 CLI 当前运行目录生成 ComboSDK.json

upload-symbols

信息

上传符号表至 Sentry, 应用崩溃时提供更多的信息

Usage

combo ios upload-symbols --project <project> --auth-token <authToken> --symbols <symbolPath>

Flags

Flag	Type	Required	Scope	Desc
--project	string	True	Local	Sentry 项目名称获取
--auth-token	string	True	Local	研发同学登录 Sentry 后生成的 auth token 获取
--symbols	string	True	Local	符号表路径 (会递归搜索查找)

Result

上传符号表至 Sentry

windows

警告

Windows 没有 build 指令，游戏研发侧可直接使用 Unity 打包
游戏研发侧需要保证 CLI 生成的 ComboSDK.json 可通过 Resources.Load()

init
setup
upload-symbols

init

信息

游戏研发侧如果没有需求 Reproducible Builds，不需要使用此指令
init 会根据指定的 数据目录, 生成 Combo CLI 所需要的构建数据

Usage

combo windows init --data-dir <value>

Flags

Flag	Type	Required	Scope	Desc
--data-dir	string	True	Local	指定 CLI 构建数据的存放目录 CLI 内部会自行组织目录结构

Result

combo windows init --data-dir ComboData

ComboData
├── windows
  ├── windows
    ├── distro.json
......

setup

信息

setup 内部会调用 init 指令，然后在 CLI 当前运行目录生成 ComboSDK.json

Usage

combo windows setup --data-dir <value>

Flags

Flag	Type	Required	Scope	Desc
--data-dir	string	False	Local	如果有 Reproducible Builds 需求，则需要指定 CLI 读取的数据目录

Result

在 CLI 当前运行目录生成 ComboSDK.json

upload-symbols

信息

上传符号表至 Sentry, 应用崩溃时提供更多的信息

Usage

combo windows upload-symbols --project <project> --auth-token <authToken> --symbols <symbolPath>

Flags

Flag	Type	Required	Scope	Desc
--project	string	True	Local	Sentry 项目名称获取
--auth-token	string	True	Local	研发同学登录 Sentry 后生成的 auth token 获取
--symbols	string	True	Local	符号表路径 (会递归搜索查找)

Result

上传符号表至 Sentry

Reproducible Builds

https://en.wikipedia.org/wiki/Reproducible_builds

背景

Combo CLI 在 setup 和 build 执行中每次都会请求 Build REST API 获取世游 Console 配置参数，所以 无法保证 确定性

使用

可查看 3 个平台的 init 指令

ios
android
windows

Combo CLI 的 setup、build 指令同时也支持 --data-dir 传入本地数据目录，保证客户端的构建 可以 具有确定性。

即，在游戏客户端代码库不做变更的情况下，每次通过 Combo CLI 构建获得的客户端，具有相同的内容，在功能和行为上不产生变化。

提示

如果游戏研发侧对于可重现构建并无明确诉求，可以不使用指令 init。
init 生成的构建数据，预期游戏研发侧是可以提交代码仓库的。

Completion

提示

进阶型指令 (Optional Command)
可通过 Tab 键快速填充 Commands 与 Flags
首次配置，需要开启新的 Session 才会生效

Support Shells:

bash
zsh
powershell

Bash
Zsh
Powershell

Enable autocompletion

To load completions in your current shell session:

    source <(combo completion bash)

To load completions for every new session, execute once:

#### Linux:

    combo completion bash > /etc/bash_completion.d/combo

#### macOS:

    combo completion bash > $(brew --prefix)/etc/bash_completion.d/combo

Help

combo completion bash -h

Enable autocompletion

If shell completion is not already enabled in your environment you will need
to enable it.  You can execute the following once:

    echo "autoload -U compinit; compinit" >> ~/.zshrc

To load completions in your current shell session:

    source <(combo completion zsh)

To load completions for every new session, execute once:

#### Linux:

    combo completion zsh > "${fpath[1]}/_combo"

#### macOS:

    combo completion zsh > $(brew --prefix)/share/zsh/site-functions/_combo

Help

combo completion zsh -h

Powershell 的效果并不是很好，更推荐 Windows 用户使用 WSL2

Enable autocompletion

To load completions in your current shell session:

    combo completion powershell | Out-String | Invoke-Expression

For more information, see Cobra’s documentation on Generating shell completions.

Global Flags

全局指令包含所有 Command 都可以使用的参数

--help

Provides additional help information from the CLI.

Usage

combo --help
combo <command> --help

./combo -h
Combo CLI is a powerful and versatile command-line interface developed as part of the sdk build system.

Usage:
  combo [command]

Available Commands:
  android     This command groups subcommands for android build.
  completion  Generate the autocompletion script for the specified shell
  configure   Configure combosdk with --game-id, --build-key and --profile
  ios         This command groups subcommands for iOS build.
  version     Show the combo version information.
  windows     This command groups subcommands for Windows build.

Flags:
  -h, --help             help for combo
  -p, --profile string   Use a specific profile from the ".combo/combo.yaml" file located in ($HOME on Unix-like systems, %USERPROFILE% on Windows).
                         You can also set the profile using the COMBO_PROFILE environment variable.
                         If not specified, the first profile from the combo.yaml file is used by default.

Use "combo [command] --help" for more information about a command.

--profile

切换不同的身份信息 (可能会有出现多个项目的情况，可以根据 --profile 切换不同的配置项，切换的数据源来自 combo.yaml)

Examples

combo android build --profile <YOUR_PROFILE>

Usage​

Config​

Environment variables​

COMBO_CONFIG_FILE​

COMBO_DATA_DIR​

GRADLE_HOME​

JAVA_HOME​

Commands​

configure​

Flags​

android​

list-distros​

init​

setup​

build​

gen-variant​

get-variant​

upload-symbols​

ios​

init​

setup​

upload-symbols​

windows​

init​

setup​

upload-symbols​

Reproducible Builds​

Completion​

Global Flags​

--help​

--profile​

Usage

Config

Environment variables

COMBO_CONFIG_FILE

COMBO_DATA_DIR

GRADLE_HOME

JAVA_HOME

Commands

configure

Flags

android

list-distros

init

setup

build

gen-variant

get-variant

upload-symbols

ios

init

setup

upload-symbols

windows

init

setup

upload-symbols

Reproducible Builds

Completion

Global Flags

--help

--profile