Theos（二）：NIC（New Instance Creator）

NIC 简介

NIC 全称叫 New Instance Creator（也叫 Nicolas!），是一个项目模板系统。它提供了一种基于模板创建项目（即 Instance）的方法，为不同的目的创建可立即构建的空项目。Theos 附带了一些有用的模板，而其他的模板也可以从社区中的各种开发者那里获得

本文参阅以下文档：

1. Theos GitHub Wiki：Features - NIC

2. iPhone Dev Wiki：NIC

3. iPhone Dev Wiki：NIC 2 - Templates

• NIC 用法

  最常见的是，NIC 以交互方式使用，以下是开发者在使用 NIC 创建项目时将看到的内容：

  # 通过运行存储在 $THEOS/bin/ 目录下的 Perl 脚本 nic.pl，根据指定的模板和开发者所提供的信息，创建可立即构建的空项目
  ~$ $THEOS/bin/nic.pl
  NIC 2.0 - New Instance Creator
  ------------------------------
    [1.] iphone/activator_event
    [2.] iphone/activator_listener
    [3.] iphone/application_modern
    [4.] iphone/application_swift
    [5.] iphone/control_center_module-11up
    [6.] iphone/cydget
    [7.] iphone/flipswitch_switch
    [8.] iphone/framework
    [9.] iphone/library
    [10.] iphone/notification_center_widget
    [11.] iphone/notification_center_widget-7up
    [12.] iphone/preference_bundle_modern
    [13.] iphone/theme
    [14.] iphone/tool
    [15.] iphone/tool_swift
    [16.] iphone/tweak
    [17.] iphone/tweak_with_simple_preferences
    [18.] iphone/xpc_service
  # 在创建所有类型的项目时，都需要开发者提供的通用信息
  Choose a Template (required): 16
  Project Name (required): Example
  Package Name [com.yourcompany.example]: com.hcg.example
  Authour/Maintainer Name [Airths LionHeart]: Airths LionHeart <994923259@qq.com>
  # 在创建 iphone/tweak 类型的项目时，需要开发者提供的额外信息
  [iphone/tweak] MobileSubstrate Bundle filter [com.apple.springboard]:
  [iphone/tweak] List of applications to terminate upon installation (space-separated, '-' for none) [SpringBoard]:
  # 在开发者提供完所有信息之后，NIC 会初始化一个可立即构建的空项目
  # 以上将在当前工作目录（~/）中创建一个名为 Example 的文件夹，请确保您在当前工作目录中具有创建文件夹的权限
  Instantiating iphone/tweak in example/...
  Done.
  

  NIC 将在创建项目之前提示开发者填写所有必要的信息，如果方括号 [] 中显示了默认值，您无需输入值，只需按回车键，将使用默认值。强烈建议作者名称字段（Authour/Maintainer Name）的值的格式为：Your Name <yourself@example.com>，因为这将使用户可以轻松地就错误和其他问题与您联系

  在几乎所有情况下，您都可以在新项目的目录中输入 make 命令，新项目将成功构建（假设 Theos 设置正确）。所生成的二进制文件很可能不会做任何事情 —— 这是完全由您决定的有趣的部分！

  # 1.1进入 example 目录
  ~$ cd example
  
  # 1.2查看 example 目录中 NIC 默认帮我们生成的模板文件
  ~/example$ ls
  Example.plist  Makefile  Tweak.x  control
  
  # 2.执行 make 指令会在当前目录（~/example）下生成一个 .theos 隐藏文件夹，并开始构建当前目录下的项目
  ~/example > make
  # 提示并行构建（即并行编译）不可用，构建速度可能会比较慢。建议升级 GNU Make
  ==> Notice: Build may be slow as Theos isn’t using all available CPU cores on this computer. Consider upgrading GNU Make: https://github.com/theos/theos/wiki/Parallel-Building
  # 提示开始构建项目
  ==> Making all for tweak Example…
  # 2.1构建 armv7 架构
  ==> Preprocessing Tweak.x…
  ==> Compiling Tweak.x (armv7)…
  ==> Linking tweak Example (armv7)…
  ==> Generating debug symbols for Example…
  warning: no debug symbols in executable (-arch armv7)
  rm /Users/Airths/example/.theos/obj/debug/armv7/Tweak.x.m
  # 2.2构建 arm64 架构
  ==> Preprocessing Tweak.x…
  ==> Compiling Tweak.x (arm64)…
  ==> Linking tweak Example (arm64)…
  ==> Generating debug symbols for Example…
  warning: no debug symbols in executable (-arch arm64)
  rm /Users/Airths/example/.theos/obj/debug/arm64/Tweak.x.m
  # 2.3构建 arm64e 架构
  ==> Preprocessing Tweak.x…
  ==> Compiling Tweak.x (arm64e)…
  ==> Linking tweak Example (arm64e)…
  ==> Generating debug symbols for Example…
  warning: no debug symbols in executable (-arch arm64e)
  rm /Users/Airths/example/.theos/obj/debug/arm64e/Tweak.x.m
  # 2.4合并以上的 CPU 架构，并进行签名
  ==> Merging tweak Example…
  ==> Signing Example…
  

  另外，在使用 $THEOS/bin/nic.pl 脚本创建项目时，$THEOS/bin/nic.pl 脚本还支持以下的命令行参数：

  1. -t（短标识） --template（长标识） string（参数类型）
     要使用的模板名称，如模板选择列表中所示，例如：iphone/tweak
     注意：一次只能使用 -t --template 和 --nic 其中的一个

  2. --nic（长标识） string（参数类型）
     要使用的 .nic.tar 或者 .nic 模板的路径，例如：libactivator_listener.nic
     注意：一次只能使用 -t --template 和 --nic 其中的一个

  3. -n（短标识） --name（长标识） string（参数类型）
     要使用的项目名称，例如：Example

  4. -p（短标识） --packagename（长标识） string（参数类型）
     要使用的包标识符，例如：com.hcg.example

  5. -u（短标识） --user（长标识） string（参数类型）
     要使用的作者名称，例如："Airths LionHeart <994923259@qq.com>"

  请注意，提供以上命令行参数并不能保证 $THEOS/bin/nic.pl 脚本不会提示您输入额外信息
  如果一个模板需要额外的变量，则还是必须手动提供额外的变量

  ~/Desktop/TheosDemo > $THEOS/bin/nic.pl -t iphone/tweak -n Example -p com.hcg.example -u "Airths LionHeart <994923259@qq.com>"
  NIC 2.0 - New Instance Creator
  ------------------------------
  [iphone/tweak] MobileSubstrate Bundle filter [com.apple.springboard]:
  [iphone/tweak] List of applications to terminate upon installation (space-separated, '-' for none) [SpringBoard]:
  Instantiating iphone/tweak in example/...
  Done.
  

  ~/Desktop/TheosDemo > $THEOS/bin/nic.pl --template iphone/tweak --name Example --package com.hcg.example --user "Airths LionHeart <994923259@qq.com>"
  NIC 2.0 - New Instance Creator
  ------------------------------
  [iphone/tweak] MobileSubstrate Bundle filter [com.apple.springboard]:
  [iphone/tweak] List of applications to terminate upon installation (space-separated, '-' for none) [SpringBoard]:
  Instantiating iphone/tweak in example/...
  Done.
  

• Theos 默认包含的模板

  1. activator_event：一个 Activator 的 事件
  2. activator_listener：一个 Activator 的 监听器
  3. application_modern：一个标准的 iOS 应用程序（供非沙盒越狱使用）
  4. application_swift：一个标准的，基于 Swift 的 iOS 应用程序（供非沙盒越狱使用）
  5. control_center_module-11up：一个通过 CCSupport 部署的 iOS 11+ 自定义控制中心模块
  6. cydget：一个 Cydget 锁屏插件
  7. flipswitch_switch：一个用于 Flipswitch 的开关
  8. framework：一个供其他开发者使用的框架
  9. library：一个可链接的库（例如 /usr/lib/libblah.dylib）
  10. notification_center_widget：一个用于 iOS 5 – 6 今日通知中心的小部件（widget）
  11. notification_center_widget-7up：一个用于 iOS 7 – 9 今日通知中心的小部件（widget）
  12. preference_bundle_modern：一个基于 PreferenceLoader 的 preference bundle 子项目
  13. theme：一种使用 Theos 的打包功能，轻松地将主题打包成 .deb 的方法
  14. tool：一个命令行工具（例如 /usr/bin/blah）
  15. tool_swift：一个基于 Swift 的命令行工具（例如 /usr/bin/blah）
  16. tweak：一个基于 Cydia Substrate 的 Tweak 插件
  17. tweak_with_simple_preferences：一个基于 Cydia Substrate 的 Tweak 插件，带有基本的 preference bundle
  18. xpc_service：基于 C 的 XPC 服务（XPC 是 macOS 下的一种进程间通讯技术，它实现了权限隔离，使得沙盒机制更加完备）

  这只是 Theos 附带的模板列表，Theos 的功能远比您在上面的列表中能找到的要多得多。而且这些模板只能作为在不需要处理各种模板文件的前提下，开发越狱软件的起点

• 通过 NIC 的配置文件 .nicrc 设置默认值

  NIC 从 ~/.nicrc 文件中读取配置数据。~/.nicrc 文件使用简单的键值对格式，key = "value"。"value" 必须用引号 " " 括起来，即使它是一个数字

  ① Instance Metadata（项目元数据）：

  1. package_prefix 字符串。默认情况下用于反向 DNS 包标识符的前缀。默认为 com.yourcompany。例如：设置 package_prefix = "ws.hbang"，然后创建一个名为 Example Instance 的新项目，将使默认包标识符变成 ws.hbang.exampleinstance

  2. skip_package_name 布尔值。是提示输入包标识符，还是始终使用 NIC 生成的包标识符。如果您使用 skip_package_name 布尔值，则您很可能也想设置 package_prefix 字符串。默认为值为 0（即，提示输入包标识符）

  3. username 字符串。用作新项目的 author/maintainer 字段的值。设置此键值对将导致 NIC 跳过询问作者姓名的步骤。建议作者姓名中包含用尖括号 <> 括起来的电子邮件地址。默认值为当前登录用户的名称。例子：username = "HASHBANG Productions <support@hbang.ws>"

  ② Theos Reference（Theos 引用）：

  1. link_theos 布尔值。是使用指向 Theos 位置的 Theos 符号链接（theos symlink），还是依赖于 Theos 的环境变量（$THEOS）。默认值为 0（即，依赖于 Theos 的环境变量 $THEOS）。这与原始的 Theos 不同，原始的 Theos 的默认值为 1（即，使用指向 Theos 位置的 Theos 符号链接 theos symlink）。如果使用默认值 0 是不可取的，则您可以将其值重新设置为 1

  2. ignore_parent_theos 布尔值。当 link_theos 设置为 1，如果从父项目中创建子项目，则子项目使用父项目的符号链接目标地址（theos symlink）。如果 ignore_parent_theos 设置为 0，则子项目将使用 Theos 的环境变量（$THEOS）。默认值为 0（即，子项目将使用 Theos 的环境变量 $THEOS）

  ③ 举例说明：

  开发者可以通过创建文件 ~/.nicrc 来设置一些供 NIC 使用的默认值。如果在 ~/.nicrc 文件中写入以下几行：

  username = "Dustin L. Howett <dustin@howett.net>"
  package_prefix = "net.howett"
  

  将使 NIC 不要求再次输入用户名（username）。并且，在提示输入包名（packagename）时：

  # 原来的提示
  Package Name [com.yourcompany.iphonedevwiki]:
  
  # 现在的提示
  Package Name [net.howett.iphonedevwiki]:
  

  如果开发者在用户名（username）中像这样添加电子邮件地址：

  username = "Dustin L. Howett <dustin@howett.net>"
  

  将在 Cydia 的包描述中创建一个 Author 单元格，并将邮件地址自动填充到 To 字段

• Building templates（创建模板）

  模板采用 .nic.tar 格式，一个标准的 tar 存档，存档内部的布局可被 NIC 识别

  Theos 附带了与 NIC 一起使用的额外脚本：nicify.pl 和 denicify.pl，它们分别用于创建和提取 .nic.tar 文件

  # 提取存储在 tweak.nic.tar 存档中的模板文件到 tweak 目录
  ~$ $THEOS/bin/denicify.pl $THEOS/templates/ios/theos/tweak.nic.tar tweak
  
  # 查看被提取到 tweak 目录中的模板文件
  ~$ ls tweak/
  @@PROJECTNAME@@.plist  Makefile  Tweak.xm  control  pre.NIC  theos
  
  # 修改 tweak 目录中的模板文件
  ... ...
  
  # 将 tweak 目录中的模板文件打包成 iphone_tweak.nic.tar 存档
  ~$ $THEOS/bin/nicify.pl tweak/
  [warning] Using legacy pre.NIC as ./NIC/control.
  [info] 6 entries.
  [info] 1 prompt.
  [info] 0 constraints.
  [info] Archived template "iphone/tweak" to iphone_tweak.nic.tar.
  
  # 查看打包好的 iphone_tweak.nic.tar 存档
  ~$ ls *.nic.tar
  iphone_tweak.nic.tar
  

  .nic.tar 文件的前身是 .nic 文件，.nic 文件是一个纯文本文件。.nic 文件已经升级为当前的基于 .tar 的格式，以实现更高的保真度，例如：保留文件权限、包含二进制文件

  （待做：应该在这里讨论模板的语法。不幸的是，DHowett 关于 NIC 的文档已经 消失，并且没有存档在 Wayback Machine 上。最好的替代方案就是对现有模板使用 denicify.pl 进行提取，然后看看它们是如何工作的）

nic.pl 如何工作

NIC 模板是开发者在添加任何自定义代码之前用于代表基本项目的文件的集合

• 术语和语义

  约束（Constraint）：创建文件、目录或者符号链接时的条件。如果给一个文件设置一个创建条件，则该文件就被称为受到一个约束

  • required：此标签所标识的条目必须存在

  • optional：此标签所标识的条目是可选的

  • text：text 所标识的文本必须是指令的一部分，并且不能被任何其他值所取代

  • ...：... 前面的标记可以选择用指定的分隔符重复

• 包控制数据 NIC/control

  每个 NIC 模板都需要一个控制文件，该控制文件包含有关模板的基本静态信息

  • ① 指令（Directives）：

    指令：name "name"
    可选性：required
    说明：用于指定此 NIC 模板的名称

    指令：prompt variable "prompt text" "default value"
    可选性：optional
    说明：
    用于提示用户提供附加信息，用户提供的附加信息将存储在变量 variable 中
    可选地支持包含一个默认值，用户可以通过不输入任何内容来接受该默认值
    用户有机会用其 ~/.nicrc 覆盖提示的变量

    指令：constrain "path" to constraint
    可选性：optional
    说明：只有在满足约束条件时才能创建的给定文件、目录或者符号链接路径

    指令：ignore built-in variable
    可选性：optional
    说明：不要提示输入给定的内置变量。支持以下内置变量（USER、PACKAGENAME）

  • ② 内置约束（Built-in Constraints）：

    约束：package
    说明：
    在期望将新项目制作成 package 时默认设置。反之，!package 表示只有在项目没有被制作成 package 时，才可以用来创建文件
    Theos 附带的 NIC 模板使用 package 约束来避免创建不必要的 control 文件

    约束：link_theos
    说明：
    在某些模板中用于包含指向 Theos 的可选链接。可以在用户的 ~/.nicrc 中设置或者重写 link_theos
    Theos 附带的 NIC 模板使用 link_theos 约束来避免创建不必要的 theos/ 符号链接

  • ③ NIC/control 示例：

    name "Awesome Template"
    constrain "control" to package
    prompt PIES "Number of Pies to create" "10"
    

• 包控制脚本 NIC/control.pl

  包控制脚本是对 NIC 格式的可选补充。控制脚本是用 Perl 编写的，并且可以访问当前的模板

  • API：

    开发者可以通过 NIC 脚本接口使用各种对象：

    • Public Methods（公有方法）

      代码：print $data
      类型：method
      说明：向用户显示信息

      代码：warn $warning
      类型：method
      说明：显示警告

      代码：error $error
      类型：method
      说明：显示错误并中止构建模板

      代码：exit $status_code
      类型：method
      说明：退出控制脚本。除了 1 之外的任何状态码都将中止构建模板

      代码：prompt($prompt_text , {default => $default_value})
      类型：method
      说明：提示用户提供附加信息。默认值是可选的。返回用户的响应

    • NIC

      NIC 对象用于表示当前的模板

      Metadata Manipulation（元数据操作）：

      1. 代码：NIC->name
         权限：read/write
         说明：当前模板的名称

      2. 代码：NIC->variables
         权限：read-only
         说明：当前在此模板上设置的变量列表

      3. 代码：NIC->variable($name)
         权限：read/write
         说明：给定名称 name 所标识的变量的值。可以作为赋值符的左侧值使用，例如：NIC->variable("NAME") = "Value"

      4. 代码：NIC->prompt($variable, $prompt_text , {default => $default_value})
         类型：method
         说明：
         提示用户提供其他信息，将用户的响应附加到提供的 NIC 变量 variable 中
         默认值是可选的
         如果未指定 $variable，则 NIC->prompt(...) 将会返回用户的响应，但是不会将其存储在模板中
         prompt(...) 和 NIC->prompt(...) 之间的关键区别是，用户是否有机会用自己的 ~/.nicrc 覆盖提示的变量

      5. 代码：NIC->setConstraint($constraint)、NIC->clearConstraint($constraint)
         类型：methods
         说明：设置或者清除由 $constraint 给出的约束条件

      Files, Directories, and Symbolic Links（文件、目录和符号链接）：

      1. 代码：NIC->lookup($name)
         类型：method
         说明：在模板的存档中查找已有的文件、目录或者符号链接。如果查找成功，则返回检索到的 NICType；如果查找失败，则返回 undef

      2. 代码：NIC->mkfile($name , $mode)
         类型：method
         说明：创建一个具有给定名称 name 和给定模式 mode（可选）的新文件。返回新创建的 File 对象

      3. 代码：NIC->mkdir($name , $mode)
         类型：method
         说明：创建一个具有给定名称 name 和模式 mode（可选）的新目录。返回新创建的 Directory 对象

      4. 代码：NIC->symlink($target, $destination)
         类型：method
         说明：
         使用一个指向给定目标的给定名称，创建一个新的符号链接
         $target 是通过 NIC->lookup、NIC->mkdir、NIC->mkfile、NIC->symlink 获得的对象
         $target 也可以是一个字符串
         返回新创建的符号链接对象

    • NICType

      NICType 对象是模板内容的化身。每个文件、目录或者符号链接都由 NICType 的子类的一个实例表示。NICType 对象共享一些通用的属性：

    1. 属性：$nictype->name
       权限：read/write
       说明：给定的 NICType 对象的名称（文件名、目录名、符号链接名）

    2. 属性：$nictype->mode
       权限：read/write
       说明：给定的 NICType 对象的模式。文件类型的 NICType 对象的默认的模式为 0644，目录类型的 NICType 对象的默认的模式为 0755

    3. 属性：$nictype->constraints
       权限：read-only
       说明：附加到当前对象的约束列表

    4. 代码：$nictype->constrain($constraint)
       类型：method
       说明：将给定的约束 constraint 应用于当前对象。类似于 NIC/control 的 constrain ...

    • File <- NICType

      代表模板中的一个文件

    1. 代码：$file->data
       权限：read/write
       说明：文件的数据

    • Directory <- NICType

      表示模板中的目录

      不包含其他方法

    • Symlink <- NICType

      表示模板中的符号链接

      代码：$symlink->target
      权限：read/write
      描述：符号链接的目标，作为对 NICType 对象或者字符串的引用

  • NIC/control.pl 示例：

    # 获取用户指定的包名
    my $packageName = NIC->variable("PACKAGENAME");
    my $packageDirectory = $packageName;
    
    # 将包名转换为一个包目录，用 / 替换 .
    # s!old!new!g 作为搜索和替换的表达式
    $packageDirectory =~ s!\.!/!g;
    
    # 使用刚刚转换的目录名称创建一个新的目录
    my $directory = NIC->mkdir($packageDirectory);
    
    # 查找 "main.m" 文件，并将其名称设置为包含新路径
    NIC->lookup("main.m")->name = $directory->name . "/main.m";
    

补充

• Tar 命令与 .tar 格式

  tar 是 Unix 和类 Unix 系统上的（打包和压缩）工具，可以将多个文件合并为一个文件，打包后的文件后缀名为 .tar。tar 文件格式已经成为 POSIX 标准，最初是 POSIX.1-1988，当前是 POSIX.1-2001。tar 工具最初的设计目的是将文件备份到磁带上（tape archive），因而得名 tar

  常用的 tar 工具是自由软件基金会开发的 GNU 版，稳定版本是 1.28，发布于 2014 年 7 月 27 日。tar 命令是 Unix/Linux 系统中备份文件的可靠方法，几乎可以工作于任何环境中，它的使用权限是所有用户

  .tar 代表已打包但未压缩的文件。已压缩的 tar 文件则会附加压缩文件的扩展名，如经过 gzip 压缩后的 tar 文件，扩展名为 .tar.gz。由于受到 DOS8.3 文件名格式的限制，常使用下列缩写：

  1. .tgz == .tar.gz
  2. .tbz 与 .tb2 == .tar.bz2
  3. .taz == .tar.Z
  4. .tlz == .tar.lzma
  5. .txz == .tar.xz