uchan note

プログラミングや電子工作の話題を書きます

「30 日でできる!OS 自作入門」のような段階的に進展するプログラムについての解説書の執筆を Git で支援する

プログラムについての解説書を Git を用いて執筆する方法の提案です.

まえがき

プログラミングに関する解説書には大きく分けて 2 つの系統があります. 1 つはテーマごとにサンプルプログラムを提示して解説するもの,もう 1 つは特定のプログラムの各部分について解説するものです. 後者の中でも,完成形を用いるものと,段階的に進展する各時点での断面(スナップショット)を解説するものがあります. この記事は,後者の執筆を Git で支援するというものです. この形態の書籍としては「30 日でできる!OS 自作入門」が有名でしょう. OS の作り方を 30 章に分け,各章で少しずつ OS を作り上げていきます.

ロールプレイングゲームRPG)の作り方を説明する書籍を書くとします. 章立てはこんな感じになるかもしれません.

  1. プレイヤーキャラクタだけが登場するゲームループの基本形
  2. 扉を開ける,階段を上り下りする,NPC と会話する,というようなイベント
  3. 敵とのエンカウントと戦闘システム
  4. ゲーム全体のシナリオ

書籍では各段階の実装方法を記述し,また付録として各段階のスナップショットをディレクトリに分けて配布したいです. すなわち,次のようなファイル構成で執筆を進めていくことを考えます. 最終的に,text 以下をビルドした結果が書籍になり,読者には src 以下をそのまま配布することになります.

/               書籍のルートディレクトリ
    Makefile    書籍のビルドスクリプト(原稿から PDF などを生成する)
    text/       原稿ディレクトリ(Markdown とか Sphinx とか.今回は Re:VIEW を仮定)
    src/        対象のゲームプログラムのソースコード(付録用)
        sec1/   第 1 章に対応するソースコードのスナップショット
        secN/

Re:VIEW を使った執筆モデル

Re:VIEW という出版支援ツールがあります. 技術書典 という技術系の同人誌即売会でも割と人気のツールです. 専用のマークアップ記法を使って原稿を書くと,HTML,PDF,ePubInDesign などに向けて原稿を出力できます. 私は TeX よりも簡単にかけて,Markdown より表現力が高いので最近はずっと Re:VIEW を使っています.

段階的に進展するプログラムの解説書を Re:VIEW で書く場合,Re:VIEW が持つソースコード埋め込み機能1が便利です. これは,本文中に外部のファイル全体,またはファイルの中でマーキングした範囲を取り込む機能です. 本文中に手動でソースコードをコピペするのとやっていることは同じですが,コピペが自動化されることでソースコード更新時に本文への反映し忘れがありません.

「まえがき」で紹介したファイル構成になっていれば,第 N 章のソースコードを埋め込みたいときは secN ディレクトリの中のファイルを参照します. こうすることで,同一のファイルが各章で更新されていくようなプログラムの作り方をしたとしても,各章の時点でのソースコードを埋め込むことが可能です.

スナップショットの作成

さて,スナップショットをどのように作成するか( srcN ディレクトリの中身をどうやって生成するか)が工夫のしどころです. 原始的にやるなら,対象のゲームプログラムのファイルを手動でコピーすることができます. 対象プログラムが Git で管理されていて,各章に対応するバージョンにタグが付いているなら, git checkout TAG としてから必要なファイルを srcN にコピーすれば良いですね.

この方法は,ゲームプログラムの開発がスムーズに進行する間は何も問題がありません(もしくは,ゲームプログラムが完成している場合). しかし,執筆が進んでからゲームプログラムの初期のコミットにミスが発覚すると大問題です.

例えば,ゲームプログラムの開発が第 3 章の内容に差し掛かったときに,第 1 章で作ったプレイヤーキャラクタの名前が typo していることに気づいたとしましょう. 普通のゲームプログラム開発であれば,プレイヤーキャラクタの名前を修正するコミットを master に対して追加するだけですが,今やっているのは解説書のためのゲーム開発です. 第 1 章で引用するソースコードにおいてもプレイヤーの名前が正しくなっているべきです. Git のコミットの歴史を改ざんして,あたかも最初からプレイヤーの名前が正しかったかのようなコミットログにする必要があります. この場合,典型的にはプレイヤー名を実装したときのコミットを修正し,修正コミットに対して master を rebase することになります.

D 第 3 章実装中のコミット
↑
C 第 2 章実装中のコミット
↑
B 第 1 章実装中のコミット(typo 含む)
↑
A 初期コミット

という歴史を次のように書き換えたいです.

D' 第 3 章実装中のコミット
↑
C' 第 2 章実装中のコミット
↑
B' 第 1 章実装中のコミット(ammend したもの)
↑
A 初期コミット

これは Git の操作としてはそれほど難しくありません. また,書籍が出版されるまではきっとゲームプログラムのリポジトリを非公開にしておくと思いますので,上記のような歴史改ざんを行っても他人に迷惑をかけることはありません.安心してできます.

さて,ゲームプログラム側の修正はできましたが,この変更を第 3 章以前のすべてのスナップショットディレクトリ( src1 から src3 まで)に反映する必要があります. この作業は typo の修正パッチをすべてのディレクトリに適用するようなものです. スナップショットを細かく切っていればいるほど,パッチの適用作業が大変になります. すべての必要なパッチ適用を漏らさない自信があるでしょうか.自動化したくなるはずです.

git-extract-tags

ここで登場するのが私が作ったツール git-extract-tags です. このツールは,指定した Git リポジトリの各タグに対応するファイルをコピーする機能を持ちます.

ゲームプログラムの Git リポジトリで,書籍の各章に対応するタグを rpgbook-sec1 などと付けておきます. 書籍で引用するためのタグには統一されたプレフィクス(ここでは rpgbook- )を付けておく必要があります. この状態で git-extract-tags を使うと次のように動作します.

  • そのプレフィクスで始まるタグを検索する.
  • 各タグの時点でのリポジトリのファイルを git archive で取り出す.
  • タグ名からプレフィクスを取り除いたディレクトリ(例えば sec1 )にファイルを展開する.

この機能を使うと,手動でスナップショットのファイルをコピーしたり,バグ修正後にパッチを当ててまわる作業を自動化できます.

具体例

例えば次のようなファイル構成だったとします.

rpgbook/        書籍の Git リポジトリ
    Makefile
    text/
    src/
myrpg/          ゲームプログラムの Git リポジトリ
    ソースコード群

myprg リポジトリにはゲームプログラムのソースコードが格納されていて,書籍の各章に対応する rpgbook-secN のようなタグ(軽量タグ)が適切なコミットに付いているとします. この時,次のコマンドを実行すると,各タグに対応するソースコードrpgbook/src/secN に展開されます.

$ cd rpgbook
$ git extract-tags rpgbook- ../myrpg

git-extract-tags PREFIX PROG_REPO という引数です. PREFIX には書籍用のプレフィクスを指定します. PROG_REPO には対象プログラムのリポジトリへのパスを指定します.

--src-base SRC_BASE オプションにより展開先のディレクトリを src 以外に変更できます. --add-ignore オプションを指定すると src/secN.gitignore に自動的に追加します.

注意点がいくつかあります.

  • git-extract-tags は .git ディレクトリの位置を自動検出するので,書籍リポジトリのルートディレクトリ以外で実行した場合でも rpgbook/src/secN にファイルを展開します.
  • ファイルを展開する前に src/secN ディレクトリを完全に消去するので,ゲームプログラムのリポジトリに存在しないファイルがあった場合,消えてしまいます.

git-extract-tags を使って快適な執筆ライフを!

git-extract-tags のセットアップ

git-extract-tags は GitPython に依存します. pip install gitpython でインストールしてください.

後は git-extract-tags を PATH が通ったディレクトリに置くだけです. $HOME/bin に PATH が通っているとしたら,こんな感じにするといいと思います.

$ cd path/to/somewhere
$ git clone https://github.com/uchan-nos/git-extract-tags.git
$ cd ~/bin
$ ln -s path/to/somewhere/git-extract-tags/git-extract-tags ./

SSD 周りの用語まとめ(M.2,PCIe,SATA,AHCI,NVMe)

SSD 関連の用語で違いがよく分からなかったりしませんか? 特に,M.2,PCIe(PCI Express),SATASerial ATA),AHCI,NVMe(NVM Express)などの用語が飛び交っていて,筆者も少しあいまいだったので,今回調査してまとめてみました.

概要

  • M.2 は「フォームファクタ」と言って,コネクタの物理的な形の規格名です.
  • PCIe と SATA はどちらもシリアル通信を用いる周辺機器のインターフェース規格です.
  • AHCI と NVMe はどちらもホストが SSD を制御するためのコントローラの規格です.

簡単にまとめると上記の通りです.以下,もう少し詳細に説明していきます.

続きを読む

OS自作入門の入門

この記事では OS 自作の最初の一歩の部分を紹介します.OS 開発を始める前に雰囲気をつかみたい,という方に向けて書いています. 「セキュリティキャンプ 2018」の「OS 開発ゼミ・フルスクラッチ OS を書こう!」の補足資料でもあります.

続きを読む

OS を作る!? 夏の集中開発ゼミ開催!

2018 年の夏季 3 日間で集中して OS を開発するイベントのご紹介です。なんと参加費、交通費、宿泊費など無料なので、学生さんは奮ってご参加ください!

概要

オペレーティングシステム(OS)は IT システムを構成する重要な要素です。しかし OS の中身を知らなくてもアプリケーションを開発できるため、多くの人にとっては OS が具体的に何をするかは謎ですし、謎のままでそんなに困っていないかもしれません。

f:id:uchan_nos:20180426162030j:plain

しかし、性能を求めるソフトウェアシステムを構成したり、低レイヤ部分に原因がある問題を解析したりするためには OS についての深い知識が欠かせません。特にこのレイヤにセキュリティ脆弱性があると、単一のアプリーションにとどまらず、システム全体の安全を脅かします。2018 年頭から世間を賑わわせている Spectre & Meltdownはその代表例でしょう。多数の顧客が同一システムに載るクラウドサービスが全盛の現代では、低レイヤを深く知る重要性がより高まっていると言えます。

そこで、学生に OS についての知識を会得してもらうために、x86 CPU 向けの OS を集中的に開発する 「OS 開発ゼミ」を開催します。テーマは「フルスクラッチ OS を書こう!」「最先端 OS 談義」「Linux 開発者を目指そう!」の 3 つです。夏の 3 日間で OS 開発にチャレンジしてみませんか?それぞれのテーマを得意とする講師がみなさまをバックアップします。

もっと詳しく

OS 開発ゼミを講師自ら紹介する動画を公開しております.是非ご覧ください.

各テーマの紹介文は別記事 seccamp2018 を参照してください。

応募するには?

IPA の応募要項ページ からエントリーをお願いします。

基本情報

  • 開催日:2018/08/15 - 17
  • 場所:クロス・ウェーブ府中(東京都)
  • イベント:セキュリティキャンプ全国大会 2018
  • ゼミ:集中開発コース システムプログラミングトラック OS 開発ゼミ
  • 講師:粟本(@liva_jy)、武内(@satoru_takeuchi)、内田(@uchan_nos)
  • 対象者:2019/03/31 時点で 22 歳以下の生徒、学生
  • 選考:書類選考のうえ決定
  • 応募締め切り:2018/05/28
  • 参加費:無料(交通費、宿泊費、食費など主催者負担)

【技術書典4】USB 3.0 ホストドライバ自作入門を出します(ダウンロード頒布有)

大人気の技術書オンリーの同人誌即売会技術書典 4」が、2018/04/22(日)に秋葉原 UDX で開かれます。

今回は「USB 3.0 ホストドライバ自作入門」を出しますので、そのお知らせです。

頒布情報

  • 日時 2018 年 4 月 22 日(日)
  • 場所 秋葉原 UDX アキバ・スクエア
  • ブース け 51「windhole」 windhole のサークルページ
  • 書名 USB 3.0 ホストドライバ自作入門
    • windhole ブースでは他にも Linux や自作 OS 系の低レイヤな同人誌を頒布しています。
  • ページ数 52(表紙含む)

f:id:uchan_nos:20180414175839j:plain:w150

続きを読む

seccamp2018

このページはセキュリティキャンプ全国大会 2018 の集中開発コース「OS 開発ゼミ」の紹介ページです.

OS 開発ゼミ 基本情報

OS 開発ゼミの基本的な情報は以下の通りです。

  • イベント:セキュリティキャンプ全国大会 2018
  • コース:集中開発コース
  • トラック:システムプログラミングトラック
  • ゼミ:OS 開発ゼミ
  • 時間帯:3 日間連続(8/15 - 8/17)
  • 必要機材:PC、その他必要に応じて仕様書や参考書など
  • 事前学習:あり(詳しくは後述)
  • 講師:粟本さん,武内さん,内田
続きを読む

x86-64 モードのプログラミングではスタックのアライメントに気を付けよう

x86-64 モードというのは x86 系 CPU の動作モードの一つです.64 ビットモードとかロングモードと呼ばれることもあります. x86-64 モードではページングが必須だったり,セグメント CS や DS に設定するベースアドレスやリミットが無視されるなど,CPU 自体の制約事項もあります. それ以外に,x86-64 モードでよく使われる ABI による制約もあり,ハマりやすい部分でもあるので本記事で説明します.

続きを読む