zoukankan      html  css  js  c++  java
  • [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中看到刚刚自动构建的成果,比如博主的仓库

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

  • 相关阅读:
    Java面试题(3)Java new一个对象的过程中发生了什么
    spring boot(九):Spring Boot中Redis的使用
    intellij idea 2018
    springboot(八)自定义Filter、自定义Property
    springboot(六)SpringBoot问题汇总
    Java Web之路(五)JSP
    Java
    instrument(2)
    Instrumentation(1)
    Dubbo中订阅和通知解析
  • 原文地址:https://www.cnblogs.com/SivilTaram/p/travis-ci_latex_auto-build_github.html
Copyright © 2011-2022 走看看