QT C++工程CI环境笔记

开发环境

Ubuntu18.04 or Ubuntu20.04
Qt Creator 4.6.x (Based on Qt 5.11.x)
APT list: apt-transport-https git dh-make build-essential autoconf autotools-dev qt5-default libssl-dev qt5keychain-dev devscripts

项目结构

项目主体结构是根据Qt, 用.pro文件组织, 项目最外层TEMPLATE用subdirs, 用于引入项目主pro文件, 这样便于将源代码放入子目录, 实际的项目pro文件在子目录下. 最外层还有对应的说明文件, 授权文件和Gitlab CI配置等.

├── .git 
├── .gitignore 
├── .gitlab-ci.yml # Gitlab CI配置文件
├── LICENSE 
├── README.md # 项目Readme
├── rockbb # 实际源代码目录
│   ├── app-entry # 为debian/ubuntu提供的桌面图标配置文件及图标文件
│   │   ├── rockbb.desktop
│   │   └── rockbb.png
│   ├── *.cpp
│   ├── *.h, *.ui
│   ├── config.h                 # 全局配置, namespace rockbb
│   ├── debian                   # deb打包时需要的文件
│   │   ├── changelog         # 软件历史版本信息, 有格式要求
│   │   ├── compat             # debhelper压缩级别, 最新的是10, 如果要兼容可以用9
│   │   ├── control              # 软件的包名, 维护者, 编译工具依赖, 安装依赖等
│   │   ├── copyright           # 标准版权信息, 例如GPLv3
│   │   └── rules                  # 编译和打包命令, 在这里将资源文件复制到deb包的标准位置
│   ├── res.qrc                    # 资源文件, 在这个文件里记录images目录里的各个文件
│   ├── images
│   │   ├── rockbb-off.png
│   │   ├── rockbb-on.png
│   │   ├── rockbb.png
│   ├── main.cpp                # 程序入口
│   └── rockbb.pro              # 主要项目文件
├── rockbb-project.pro        # 项目入口文件(用于引入rockbb.pro)
└── rockbb-project.pro.user # Qt Creator产生的本地开发配置文件, 需要从gitignore中排除

 Qt对非Qt项目文件的支持不好, 在project视图下不展示不相关的文件, 需要切换到File System视图, 另外需要在模块右上角选项中勾上"Show Hidden Files", 才会展示.gitlab-ci.yml这些文件.

开发编译和测试

在本地通过Qt Creator完成, 编译, Debug和运行有Ctrl+B, F5, Ctrl+R等快捷方式.

代码仓库

在本地通过 git remote add 将github添加为上游仓库, 这样项目对应的就有 origin 和 github 两个上游, 在本地编译通过后, push origin master可以触发测试环境的gitlab进行集成, 在gitlab测试通过后, 可以push gitlab master将代码提交到github.

测试集成

测试环境的持续集成, 使用Gitlab + Gitlab Runner实现. 有条件的话Gitlab Runner应当跑在独立的服务器上, 另外如果需要构建异构系统例如Windows, OSX等, 都需要将Runner跑在独立的服务器上. 如果只需要构建Linux下的发行版, 可以放在一起. Gitlab Runner需要Docker环境, 最好使用Ubuntu较新的发行版.

gitlab 12.10.6, gitlab-runner 12.10.2, docker 19.03.6

Gitlab配置

略. 这里主要是创建group, project, user, 获取group下的runner token

Gitlab Runner配置

准备Docker镜像, 对于不同的发行版发布, 要准备对应的发行版镜像, 再将这些镜像作为Runner, 注册到Gitlab. 举例Ubuntu18.04的Dockerfile

from ubuntu:bionic
ADD setup.sh /opt/
RUN /bin/bash /opt/setup.sh

 和setup.sh, 这个脚本用于切换到较快的apt源, 以及准备编译环境.

#!/bin/sh
echo "deb http://mirrors.ustc.edu.cn/ubuntu/ bionic main restricted" > /etc/apt/sources.list
echo "deb http://mirrors.ustc.edu.cn/ubuntu/ bionic-updates main restricted" >> /etc/apt/sources.list
echo "deb http://mirrors.ustc.edu.cn/ubuntu/ bionic universe" >> /etc/apt/sources.list
echo "deb http://mirrors.ustc.edu.cn/ubuntu/ bionic-updates universe" >> /etc/apt/sources.list
echo "deb http://mirrors.ustc.edu.cn/ubuntu/ bionic multiverse" >> /etc/apt/sources.list
echo "deb http://mirrors.ustc.edu.cn/ubuntu/ bionic-updates multiverse" >> /etc/apt/sources.list
echo "deb http://mirrors.ustc.edu.cn/ubuntu/ bionic-backports main restricted universe multiverse" >> /etc/apt/sources.list
echo "deb http://security.ubuntu.com/ubuntu bionic-security main restricted" >> /etc/apt/sources.list
echo "deb http://security.ubuntu.com/ubuntu bionic-security universe" >> /etc/apt/sources.list
echo "deb http://security.ubuntu.com/ubuntu bionic-security multiverse" >> /etc/apt/sources.list

# requirements
apt-get update
apt-get -y install apt-transport-https git dh-make build-essential autoconf autotools-dev qt5-default libssl-dev qt5keychain-dev devscripts

 对于Ubuntu20.04, 在apt install 过程中会出现tzdata等需要交互的安装导致镜像制作失败, 需要在apt-get update前加上这句

export DEBIAN_FRONTEND=noninteractive

制作镜像, 将镜像注册为Runner

# 制作镜像
docker build -t ubuntu_focal_runner:1.0 ubuntu_focal/

# 注册到gitlab
gitlab-runner register --non-interactive --url "http://172.17.54.139/" --registration-token "x7sx4rte_acSXrmznJBz" --description "Ubuntu 20.04 x64 runner" --executor "docker" --docker-image "ubuntu_focal_runner:1.0" --tag-list "ubuntu-2004-64" --run-untagged="false" --locked="false" --access-level="not_protected"

测试镜像是否可用:

对于刚建好的容器镜像, 需要在跑任务前实际执行一下构建, 可以通过 docker run -it --rm [image] bash 的方式, 在命令行下手动git clone项目文件, 执行编译. 如果有问题, 需要在这一步重新制作镜像来解决. 不同的发行版, gcc/g++版本可能会不一样, Ubuntu16.04(GCC 5.4), Ubuntu18.04(GCC 7.5), Ubuntu20.04(GCC9.3), Debian8&10(GCC 8.3)

对于runner, 需要注意的有两点:

1. 每个runner需要带一个 --tag-list "ubuntu-2004-64" 参数, 里面可以配一个或多个tag, 这个tag-list 结合 .gitlab-ci.yml文件里的 tags 参数, 可以让发行版各自执行对应的任务.

2. 如果希望Runner就近pull镜像, 在注册完runner后, 需要修改 /etc/gitlab-runner/config.toml 文件, 在每个runner的[runners.docker]配置下, 增加一行配置. 默认为"always", 会主动去docker hub 拉取, 因为自建的镜像只存在本地, 从而导致任务失败.

    volumes = ["/cache"]
    pull_policy = "if-not-present"  # 增加这行
    shm_size = 0

项目 .gitlab-ci.yml 配置

参考

https://docs.gitlab.com/ee/ci/quick_start/
https://docs.gitlab.com/ee/ci/yaml/

根据.gitlab-ci.yml里的任务配置, gitlab在收到新的push后, 会触发产生pipeline, 里面是满足条件的, 分配到对应runner的job. 如果中途有job失败, 整个pipeline就会失败, 不再往下执行.

Github发布

对于版本间一个完整的开发周期, 以上一个版本号Tag提交为开始, 以下一个版本号提交为结束.

开发阶段

假设已经发布的版本号为1.1, 进入当前开发周期后, 首先修改以下文件

• config.h: 版本号修改为 1.2-dev

因为测试集成产生的版本号为特殊版本号, 并且会完全覆盖debian/changelog, 故这一阶段还不需要修改changelog

预发布阶段

在测试结束后, 进入发布准备工作, 需要修改以下文件

• config.h: 版本号修改为 1.2
• debian/changelog: 加入自上个版本至今的改动说明

对commit ID打tag, 并生成正式版的release

# 加tag
git tag -a 0.1.0 94ca32cbc4bd685774f22d95c66d58c79dccf95f

# 触发测试执行任务, 打包正式版
push origin --tags

本地对release进行测试

发布阶段

将tag推送到github

git push github --tags

之后, github会自动对新tag产生release, 可以手工在此release下添加文字和对应的release软件包