The Embedded Rust Book翻訳の気づきメモ③～CI環境構築～

Rust embedded translation

The Embedded Rust Bookを翻訳しています。下記から見ることができます。 Getting startedのQEMUまで、翻訳完了しています。

導入 - The Embedded Rust Book

お仕事でもRustをやりたいな、と考えて、組込みでRustを広めるために翻訳を行っています。 翻訳を進める中で、技術的にも英語的にも、学びがあるので、それを綴っていきます。

フィードバックやコントリビューションをお待ちしております。

github.com

CI環境構築

構築、と言ってもTravis CIでレポジトリをactivateして、GitHub tokenを登録するだけでした。fork元レポジトリがCI環境を構築してくれていたおかげです。

今後、もう少し運用して、pull requestのときにちゃんとCIが走るか、ということを確認していきます。

travis.yml

travis.ymlは、下記の内容でした。

language: rust

install:
  - bash ci/install.sh

script:
  - bash ci/script.sh

after_success:
  - bash ci/after-success.sh
...

rustをインストールしています。 The Embedded Rust Bookでは、mdbookを使っています。

rust-lang-nursery.github.io

mdbookはRust製のドキュメントビルダーです。markdownから、上記のmdbookのページのようなページを生成してくれます。 cargoを使うので、rust環境をインストールします。

その後は、install、script、after_successでそれぞれスクリプトを実行します。

ci/install.sh

mdbookと、補助ツールであるlinkcheckerをインストールしています。linkcheckerはページ内にリンク切れがないか、をチェックしてくれるツールのようです。

set -euxo pipefail

main() {
    local tag=$(git ls-remote --tags --refs --exit-code https://github.com/rust-lang-nursery/mdbook \
                    | cut -d/ -f3 \
                    | grep -E '^v[0.1.0-9.]+$' \
                    | sort --version-sort \
                    | tail -n1)
    # Temporarily use older version until packages are available for 0.2.2 (or newer)
    local tag="v0.2.1"
    curl -LSfs https://japaric.github.io/trust/install.sh | \
        sh -s -- --git rust-lang-nursery/mdbook --tag $tag

    pip install linkchecker --user
}

main

ci/script.sh

mdbookをビルドし、linkchekerでリンク切れをチェックします。

set -euxo pipefail

main() {
    mdbook build

    # FIXME(rust-lang-nursery/mdbook#789) remove `--ignore-url` when that bug is fixed
    linkchecker --ignore-url "print.html" book

    # now check this as a directory of the bookshelf
    rm -rf shelf
    mkdir shelf
    mv book shelf
    # FIXME(rust-lang-nursery/mdbook#789) remove `--ignore-url` when that bug is fixed
    linkchecker --ignore-url "print.html" shelf

    mv shelf/book .
    rmdir shelf
}

main

後半のshelfディレクトリを操作しているあたりが、イマイチ何をやっているのかわかっていません。

ci/after-success.sh

mdbookのビルド成功後は、GitHub pagesを更新します。 ghp-importは、対象ディレクトリを、gh-pagesブランチにコピーするスクリプトです。

github.com

set -euxo pipefail

main() {
    mkdir ghp-import
    curl -Ls https://github.com/davisp/ghp-import/archive/master.tar.gz |
        tar --strip-components 1 -C ghp-import -xz

    ./ghp-import/ghp_import.py book

    # NOTE(+x) don't print $GH_TOKEN to the console!
    set +x
    git push -fq https://$GH_TOKEN@github.com/$TRAVIS_REPO_SLUG.git gh-pages && echo OK
}

if [ $TRAVIS_BRANCH = master ] && [ $TRAVIS_PULL_REQUEST = false ]; then
    main
fi

手元の環境にcloneして、手動で手順を追ってみると、./ghp-import/ghp_import.py book実行後、ローカルのbranchにgh-pagesが追加されます。

$ git branch
* gh-pages
  master

このbranchをcheckoutすると、ビルドしたmdbookのファイルのみが置かれていました。

後は、このgh-pages branchを-fコマンド付きでpushすれば、更新完了です。

ということで、少なくともmasterへのpush時と、dailyのビルドはうまく走るはず、です！