IT工程師數位筆記本

博主有一本開源書籍，用 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

2. 可以寫個 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中看到剛剛自動構建的成果，比如博主的倉庫。

如果有遺漏與錯誤之處還望各位指出～