[Latex] 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中看到刚刚自动构建的成果,比如博主的仓库

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

posted @ 2016-03-28 20:50 SivilTaram 阅读(...) 评论(...) 编辑 收藏