Travis-CI与Latex构建开源中文PDF

博主有一本开源书籍，用 latex 排版，托管在Github上。但用 latex 不像是 Markdown，当tex文本更新时，用于最终浏览的PDF文件很难得到及时的更新， 所以博主一直想找到一套工具，实现以下两点愿望：

• 自动构建以测试是否可以成功编译生成PDF文件。
• 始终都能有一个最新版的PDF版本可供下载。

博主之前曾使用过Travis-CI进行单元测试的自动运行，所以猜测它能够实现博主的小心愿。最后一探索，果然可以，但网上相关的中文资料较少，遂自己摸索写下这一篇博客。主要的资料来源于Travis-CI官方文档。

自动构建第一步，安装latex环境

由于Travis-CI不再对 public repository 提供 Caching Dependencies , 所以我们针对 latex 的每次自动构建都需要下载texlive-full包。不过博主发现，在配置好后，自动构建的时间一般在 8 分钟左右，时间还是相当可以的。

首先创建一个.travis.yml文件，在文件中填入以下两行

sudo: required
dist: trusty

其中 dist: trusty是指定ubuntu版本为14.04。

为了能够成功编译中文PDF，我们可以使用xelatex。在这里博主直接下载了texlive-full包环境用于编译。所以我们在.travis.yml文件中加入环境配置的代码：

before_install:
- sudo apt-get update
- sudo apt-get -y install texlive-full

由于在服务器端一个中文字体都没有，博主建议开源书籍可以有一个fonts目录用于存放编译所用字体。如果在 ubuntu 下使用 xelatex ，默认字体是 Adobe的四款开源字体。接下来我们将仓库里的字体安装在服务器的环境下。Linux系统中安装字体很简单，将字体文件只需要放在usr/share/fonts文件目录下即可。这里有个小坑在于，服务器上没有usr/share/fonts目录，需要自己新建一个。博主安装字体的代码如下,opentype目录表示.otf格式字体。：

- sudo mkdir -p /usr/share/fonts/opentype/
- sudo mv ./guide-book/fonts/AdobeFangsongStd-Regular.otf /usr/share/fonts/opentype/
- sudo mv ./guide-book/fonts/AdobeHeitiStd-Regular\ \(v5.010\).otf /usr/share/fonts/opentype/
- sudo mv ./guide-book/fonts/AdobeKaitiStd-Regular\ \(v5.010\).otf /usr/share/fonts/opentype/
- sudo mv ./guide-book/fonts/AdobeSongStd-Light\ \(v5.010\).otf /usr/share/fonts/opentype/
- sudo mkfontscale
- sudo mkfontdir
- sudo fc-cache -fv

括号需要进行转义，并且需要使用sudo fc-cache -fv对字体列表进行更新。

如果在编译latex时出现The font "Adobe Song Std" cannot be found.，可以在 .travis.yml 中加入fc-list :lang=zh打印字体信息以进行 debug 。

自动构建第二步，编译生成PDF

在安装完 latex 环境后，我们接下来就可以使用xelatex进行编译了。

一般对于 latex 稍微熟悉一些的朋友应该都没有问题。将编译的指令写在scripts:下即可自动运行。

现在博主的.travis.yml长这样：

sudo: required
dist: trusty
before_install:
- sudo apt-get update
...
- sudo fc-cache -fv
script:
- cd guide-book
- make

在这里博主有两个小建议：

1. latex 使用 nonstopmode模式。在编译时，如果不加任何选项，出错时latex会等待用户输入一个新的tex文件名进行重新编译。但是自动构建并没有人帮我们输入，所以在前期摸索试错时，如果加上这个编译选项，可以更快地看到自动构建的结果，否则就需要等待较长时间(这时候是超时错误)。使用的方法如下：

xelatex SAMPLE.tex -interaction=nonstopmode

1. 可以写个 Makefile 文件，只需要 make 即可一步编译。博主就将 xelatex 执行的脚本写在了 Makefile 文件中。

自动构建第三步，PDF自动上传到Github

我们已经生成了PDF文件，下面我们来一步一步把它上传到Github上。

首先，执行sudo gem install travis安装travis.

如果没有gem的话，首先需要安装gem,安装方法请自行寻找。

如果在安装travis时失败了，可能是因为网络原因。博主推荐使用ruby淘宝源，淘宝源已经不再支持http，之前配置成http的朋友记得更换。如果是第一次配置，使用gem sources -a https://ruby.taobao.org/ --remove http://rubygems.org/即可替换源。

安装信息如下：

Fetching: ethon-0.8.1.gem (100%)
Successfully installed ethon-0.8.1
Fetching: typhoeus-0.8.0.gem (100%)
Successfully installed typhoeus-0.8.0
Fetching: travis-1.8.2.gem (100%)
Successfully installed travis-1.8.2
Parsing documentation for ethon-0.8.1
Installing ri documentation for ethon-0.8.1
Parsing documentation for typhoeus-0.8.0
Installing ri documentation for typhoeus-0.8.0
Parsing documentation for travis-1.8.2
Installing ri documentation for travis-1.8.2
Done installing documentation for ethon, typhoeus, travis after 10 seconds
3 gems installed

在成功下载了travis后，我们首先要登录，进入你要自动构建的git 仓库目录下，使用sudo travis login --auto进行登录。

qian@thinkpad:~/BUAAOS-guide-book# sudo travis login --auto
We need your GitHub login to identify you.
This information will not be sent to Travis CI, only to api.github.com.
The password will not be displayed.

Try running with --github-token or --auto if you don't want to enter your password anyway.

Username: SivilTaram
Password for SivilTaram: ****************
Successfully logged in as SivilTaram!

博主在这里一开始遇到了坑。在windows下使用cmd，在输入密码时都显示明文密码，并且回车后无响应，如果有朋友知道解决方法或者原因，烦请赐教。最后博主用ubuntu，在shell里成功登录。

登录后，我们来使用travis setup releases来指定要上传的文件

 sudo travis setup releases
[sudo] password for qian:
Detected repository as SivilTaram/BUAAOS-guide-book, is this correct? |yes| yes
Username: SivilTaram
Password for SivilTaram: ***************
File to Upload: guide-book/guide-book.pdf
Deploy only from SivilTaram/BUAAOS-guide-book? |yes| yes
Encrypt API key? |yes| yes

其中Encrypt API key是用于加密的，建议选择 yes。

在完成这一步后，我们可以发现我们的.travis.yml文件中多了几行，博主的文件增加内容如下：

deploy:
  provider: releases
  api_key:
    secure: xxxxxxxx
  file: guide-book/guide-book.pdf
  on:
    repo: SivilTaram/BUAAOS-guide-book

但是注意，deploy 设置还没有结束！根据官方文档,Travis-CI会在script执行结束后，默认清除所有生成的文件，所以一定要加上一句skip_cleanup: true。现在我们完整的.travis.yml文件应该类似于下面的结构:

sudo: required
dist: trusty
before_install:
- sudo apt-get update
- sudo apt-get -y install texlive-full
- sudo tex -v
script:
- cd guide-book
- make
deploy:
  provider: releases
  api_key:
    secure: xxxxx
  file: guide-book/guide-book.pdf
  skip_cleanup: true
  on:
    repo: SivilTaram/BUAAOS-guide-book

如果想添加多个上传文件，将 file: 的选项更改成:

file:
    - "FILE 1"
    - "FILE 2"

当我们在某次 commit 时已经预先知道本次 commit 无法通过编译，不想自动构建时，可以使用git commit -m "[ci skip] xxxx"跳过自动构建。

如果想触发自动构建并上传的话，需要打tag，如果不打tag，在realese里的名字会很难看。打的tag将成为最新版本的名字。可以按照如下步骤进行push。注意commit中不要使用[ci skip]。

git tag -a v1.1.1 -m "tags content"
git push --tags
git push

其中 v1.1.1即版本号

如果自动构建成功的话，你将在仓库的releases中看到刚刚自动构建的成果，比如博主的仓库。

如果有遗漏与错误之处还望各位指出～