命令行工具

除受到全局 进程调度 的脚本进程外，你还可以使用 Lua 命令行解释器来执行另外的脚本。

警告

本章中所介绍的命令行工具，都需要 root 权限才能执行。

激活环境

通过 OpenSSH 登录到设备后，你需要执行以下命令来激活 XXTouchNG 命令行环境。否则后续章节中的命令将无法执行。

$ . xxtouch

运行模式

交互式模式

Lua 命令行解释器可以在交互式模式下运行（REPL 模式），这意味着你可以在命令行中输入 Lua 代码并立即执行。激活环境后，交互式模式可以通过以下命令启动：

$ lua

随后你将看到 Lua 命令行解释器的提示符，键入 Lua 表达式并按下回车键，它将立即执行并显示结果：

Lua 5.3.6  Copyright (C) 1994-2020 Lua.org, PUC-Rio
> print("Hello, World!")
Hello, World!
> 

增强型交互式模式

croissant 是交互式模式的一个变体，它提供了额外的代码高亮、自动展开等增强特性。激活环境后，增强型交互式模式可以通过以下命令启动：

$ . xxtouch
$ croissant

随后你将看到 Lua 命令行解释器的提示符，键入 Lua 表达式并按下回车键，它将立即执行并显示结果：

🥐  Croissant 0.0.1 (C) 2019 Benoit Giannangeli
Lua 5.3 Copyright (C) 1994-2018 Lua.org, PUC-Rio
→ pasteboard
{  -- table: 0x12bd2d870
  _VERSION = "3.0.1",
  read = function: 0x105ea9424,
  write = function: 0x105ea9558,
}
→ 

解释器模式

将脚本保存为文件并上传至设备 /path/to/script.lua，然后使用 Lua 命令行解释器来执行它。

$ lua /path/to/script.lua

备注

如果希望省略 lua 命令，可以将脚本文件以 #!/usr/bin/env lua 开头，扩展名改为 .lua。

$ /path/to/script.lua

备注

如果希望进一步省略路径，可以将脚本文件放置于 /usr/local/bin 目录下。

$ script.lua

守护者模式 daemon.lua

守护者模式比 守护模式 更为底层，是一个由 launchd 启动的系统级服务。
当设备处于非局域网环境却需要集中控制，就可以启用一个守护者主动与外界的服务器保持通讯。

• 守护者可使用 launchctl 来管理
• 守护者随系统启动自动运行，发生异常崩溃会在 30 秒后自动重启
• 开发者可进一步使用 lockfile 函数锁定一个文件以确保其单例状态

说明

你可以编写以 daemon.lua 命名的守护者，上传到 /usr/local/xxtouch/bin/daemon.lua。

限制

守护者模式将在重启、软重启或重启 XXTouchNG 后生效。

示例

本节示例中的守护者将每 3 秒向进程队列字典 xxtouch.daemon.test 中压入一个描述当前时间的文本。

daemon.lua

if not G_reload then
  if not lockfile("/tmp/daemon.lua.singleton") then
    return  -- 如果文件已经被别的进程锁定，那么说明不需要再次运行
  end
else
  G_reload = nil
end
--
local daemon_file_name = "/var/mobile/Media/1ferver/bin/daemon.lua"
local socket = require("socket")
local lfs = require("lfs")
--
function file_change_date(file_name)
  local fattr = lfs.attributes(file_name)
  if type(fattr) == "table" and fattr.mode == "file" then
    return fattr.change
  end
  return 0
end
--
local orig_change = file_change_date(daemon_file_name)
--
while true do
  sys.log(string.format("daemon.lua: %d", os.time()))
  proc_queue_push("xxtouch.daemon.test", string.format("daemon.lua: %d", os.time()))
  if file_change_date(daemon_file_name) ~= orig_change then
    break
  end
  socket.sleep(3)
end
--
G_reload = true
dofile(daemon_file_name)

已集成的命令行工具

快照实用工具 (ngtool)

说明

ngtool 是一个用于备份和恢复 App 的命令行实用工具。

声明

本节仅列出 ngtool 的一级参数和二级指令，各指令的使用方法和具体参数，请参考 ngtool help <subcommand> 的输出。

$ ngtool
OVERVIEW: A utility for performing application backup and restore.

USAGE: ngtool [--verbose] [--quiet] <subcommand>

OPTIONS:
  --verbose               Verbose logging, including debug and trace information.
  --quiet                 No logging is required.
  --version               Show the version.
  -h, --help              Show help information.

SUBCOMMANDS:
  launch                  Launch one or more applications from SpringBoard Services.
  kill                    Kill one or more applications by sending STOPJOB command via launchd.
  list                    View details of applications from Launch Services.
  clean                   Free from dirt, marks, or stains.
  archive                 Make a tarball archive using command-line tar.
  unarchive               Extract from a tarball archive using command-line tar.
  peek                    View details of an archive without extract it, or view details of a snapshot.
  backup                  Collect application related stuffs, and make an extra copy of them to somewhere.
  restore                 Bring back applications to previous states from archives or snapshots.

  See 'ngtool help <subcommand>' for detailed help.

登录 App Store (appstore.lua)

声明

usage: appstore.lua [login|background-login|logout|account]

说明

appstore 模块封装的命令行工具。

示例

$ appstore.lua login example@icloud.com ThisIsMyPassword678!  # 登录 App Store

$ appstore.lua logout   # 登出 App Store

$ appstore.lua account  # 显示当前登录的 Apple ID

录制 HID 事件 (hidrecorder)

说明

用于转储 HID 事件流到标准输出，详见 录制回放脚本。

示例

hidrecorder > /path/to/hid-events.lua

安装、卸载 App (installer.lua)

声明

usage: installer.lua install   [ipa-path]
       installer.lua uninstall [bundle-id]

参数及返回值

• ipa-path IPA 安装包文件路径
• bundle-id 已安装的 App 标识符

示例

$ installer.lua install /path/to/MyApp.ipa   # 安装 App

$ installer.lua uninstall com.example.MyApp  # 卸载 App

启动、停止远程访问 (remote-access.lua)

声明

remote-access.lua [on|off]

说明

效果等同于 打开远程访问。

示例

$ remote-access.lua on   # 启动远程访问

$ remote-access.lua off  # 停止远程访问

远程锁定、解锁 (remote-lock.lua)

声明

usage: remote-lock.lua unlock [password]
       remote-lock.lua lock
       remote-lock.lua status

参数及返回值

• password 设备锁屏密码

示例

$ remote-lock.lua unlock       # 无密码解锁设备

$ remote-lock.lua unlock 1234  # 有密码解锁设备

$ remote-lock.lua lock         # 锁定设备

$ remote-lock.lua status       # 显示设备锁屏状态，返回 `true` 或 `false`

卸载 XXTouchNG (uninstall-xxtouch.sh)

示例

uninstall-xxtouch.sh

危险

此操作不可逆。
将同时移除所有与 XXTouchNG 有关的 用户数据。