shiroko/shirodeb repository overview

⁠ShiroDEB

ShiroDEB是一系列用来打包Deb包的脚本组合，主要用来构建符合UOS规范的deb软件包。

本项目依赖新版的bash（以UOS v20自带的版本为基准），并不兼容 POSIX 标准sh

⁠依赖

• bash, sed, dh-make, jq: 必要依赖
• imagemagick: 用于处理图标
• inkscape: 用于处理svg图标
• unsquashfs: 用于解包.snap格式的软件包，不需要安装（snap支持尚不完备）
• unar：用于解包一般格式的压缩包，例如.tar.*或.zip等。

⁠可用指令

在使用ShiroDEB之前请将项目目录下的bin文件夹加入到你的PATH环境变量中以使用shirodeb指令。当然你也可以直接使用路径调用shirodeb.sh，两种方法没有功能上的区别。

约定俗成的说明：使用方括号[]包裹的参数代表可选参数，使用尖括号<>包裹的参数代表必选参数

• ⁠shirodeb start [template]

  创建一个新打包工程，如果template参数给出，则从项目的templates/boilerplates文件夹中拷贝响应的模板文件。

  目前可用的模板：appimage、deb、raw

• ⁠shirodeb make [--stage1 | --stage2] [--no-build]

  构建软件包。 如果使用--stage1，则脚本构建完文件结构后就会结束，并不会调用dh_make构建deb包。 如果使用--stage2，则脚本不会修改文件结构，直接将现有的文件打包成deb包。 --stage1和--stage2提供了一种十分灵活的控制方式，尤其是你希望手动调整包内容的时候，虽然不是很建议，因为这样违背了脚本设计的初衷。花一小时自动化一个一分钟的流程是程序员的浪漫 如果使用--no-build，则脚本不会执行build.sh中的build函数。

• ⁠shirodeb download

  仅下载构建所需的文件。

• ⁠shirodeb purge

  清除下载的文件，同时清理缓存的下载内容。

• ⁠shirodeb clean

  删除项目文件夹下的src, pkg, downloads和output文件夹，保持项目文件夹整洁。（这四个文件夹也是不纳入版本管理系统的文件夹）

• ⁠shirodeb save

  保存构建好的deb文件和一些相关信息到DEB_UPLOAD_PATH文件夹。会将软件包的图标单独提取保存，同时生成一个info.txt包含一些软件包信息。info.txt用于使用MUSE插件在UOS上传后台中自动填写部分信息（而不用手动复制，当然不使用MUSE插件的话也可以手动复制info.txt中的内容啦）

• ⁠shirodeb install

  安装构建好的软件包。运行此命令前须保证软件包已经被构建。

• ⁠shirodeb remove

  卸载被安装的软件包（通过包名卸载）

• ⁠shirodeb dir [src|pkg|download|output]

  在标准输出中输出文件夹绝对路径，一般这么用：cd $(shirodeb dir)。

⁠build.sh 文件

build.sh 对于ShiroDEB来说是最重要的文件，称之为“Recipe（菜谱）”

ShiroDEB通过source引用build.sh来获取里面的必要信息，以及对于不同软件包也有的build函数（当然对于一些流程大同小异的软件包，可以共享build函数，即上文提到的模板。）。在构建过程中，ShiroDEB会通过执行build.sh来构建软件包需要的文件结构。

最简单的build函数就是直接从上游发布的二进制包中复制文件出来，或者更进一步，使用cmake、make等构建系统从源码构建程序。

目前ShiroDEB已经全面支持第三方自建库，从而摆脱UOS V20系统库版本过低的桎梏。关于这方面的细节会在其他文档说明。你也可以关注ingredients仓库⁠来获取更多信息。

⁠function build 函数说明

以下是一些在build函数内推荐使用的变量：

还有一些比较实用的函数于utils.sh中提供，可以阅读函数自带的注释了解使用方法。相关文档可能在后期完善。

⁠function prepare 函数说明

prepare 函数用来完成元信息（下载地址、描述、版本号甚至包名等）的自动获取（INGREDIENTS变量不能在此处重新赋值，但应该可以通过调用ingredients.add xxx来追加（不太确定））

对于不支持的源码获取方式（例如通过git等版本控制系统拉取源码等）也可以在此处完成，例：

function prepare() {
    if [[ "$1" != "download" && "$1" != "make" ]]; then
        return 0
    fi
    local giturl="https://github.com/siyuan-note/siyuan"
    mkdir -p "$ROOT_DIR/src"
    pushd "$ROOT_DIR/src"
    if [[ -d "$PACKAGE-$VERSION/.git" ]]; then
        if [[ $(git -C "$PACKAGE-$VERSION" describe --tags) != "v$VERSION" ]]; then
            log.info "delete old checkout"
            rm -rf "$PACKAGE-$VERSION"
            git clone --depth 1 --recursive --branch "v$VERSION" "$giturl" "$PACKAGE-$VERSION"
        else
            log.info "already checkout the tagged version"
        fi
    else
        git clone --depth 1 --recursive --branch "v$VERSION" "$giturl" "$PACKAGE-$VERSION"
    fi
    popd
}

⁠环境变量

一些环境变量会影响脚本行为，这些环境变量可以通过任何你想的方式配置。通常，通过如下三种方式配置环境变量是推荐的：

1. 直接修改~/.bashrc、~/.profile等全局启动脚本来修改环境变量。
2. 通过拷贝项目文件夹的profile.example到profile后，在其中修改环境变量。脚本在每次执行的时候都会自动包含profile中的内容。
3. 在build.sh中修改环境变量。

通过方法1和方法2修改的环境变量是全局的，而通过方法3修改的环境变量则只针对特定的打包项目有效。

⁠环境变量表

环境变量仅能在其推荐的作用域中指派，在其他作用域指派环境变量可能会导致构建脚本功能失常

⁠可用模板

通过模板构建可以批量重新打包较为一致的二进制软件包，例如AppImage。也可以减少部分通用流程的重复劳动。

• deb

  • 重新打包适用于Debian、Ubuntu等的deb二进制包。会自动从其中继承control文件的内容。需要手动指定EXEC_PATH，或可选地调整文件结构。可以使用shirodeb make check快速查看deb文件的内容。

• appimage

  • 重新打包AppImage应用，需要手动填写元信息。可以使用shirodeb make test来测试AppImage是否可以在系统上运行。

• raw

  • 空白模板，一生万物。

⁠Docker

目前ShiroDEB可以通过Docker进行软件包的构建。通过docker pull shiroko/shirodeb拉取最新版的ShiroDEB镜像，然后通过如下命令进行构建（请根据实际情况对绑定和环境变量进行修改）：

docker run \
  -e DEBFULLNAME="shiroko" \
  -e DEBEMAIL="[email protected]" \
  -v $(pwd)/artifacts:/artifacts \
  -v $(pwd)/downloads:/downloads \
  -v $(pwd)/org.wireshark:/recipe \
  shiroko/shirodeb

当前本Docker镜像的基础系统为UOS V20 Eagle，但之后可能会逐渐转移到deepin V23 Beige。