Goコードの書き方

Version:	Build version go 1.1.1
original:	http://golang.org/doc/code.html

Contents

イントロダクション
コードの取り扱い
テスト
リモートパッケージ
その他

イントロダクション

このドキュメントではシンプルなGoパッケージの開発を実際にやってみて、Goパッケージやコマンドをフェッチ、ビルド、およびインストールする標準的な方法である goツールを紹介します。

goツールは、あなたのコードが指定の方法で整理されている必要があります。このドキュメントを注意深く読んでください。Goのインストレーションを組み上げ、実行するための最も簡単な方法を説明しています。

同様の説明がスクリーンキャストとして利用可能です。

コードの取り扱い

ワークスペース

Goツールは公開リポジトリでメンテナンスされているオープンソースコードで動作するように設計されています。あなたのコードを公開する必要はありませんが、環境の設定方法のモデルはコードを公開してもしなくても同様に動作します。

Goコードはワークスペース内に保存する必要があります。ワークスペースは、ルートに３つのディレクトリを持つディレクトリ階層です:

src はパッケージ単位(１ディレクトリ毎に１パッケージ)に整理されたGoソースファイルを、
pkg はパッケージオブジェクトを、そして
bin は実行可能なコマンドを含みます。

Goツールはソースパッケージをビルドして pkg と bin ディレクトリに結果のバイナリをインストールします。

src サブディレクトリは通常、１つまたは複数のソースパッケージの開発を追跡する、複数の(GitやMercurialのような)バージョン管理リポジトリを含んでいます。

実際のワークスペースがどのようなものかが分かるように、例を示します:

bin/
    streak                         # command executable
    todo                           # command executable
pkg/
    linux_amd64/
        code.google.com/p/goauth2/
            oauth.a                # package object
        github.com/nf/todo/
            task.a                 # package object
src/
    code.google.com/p/goauth2/
        .hg/                       # mercurial repository metadata
        oauth/
            oauth.go               # package source
            oauth_test.go          # test source
    github.com/nf/
        streak/
            .git/                  # git repository metadata
            oauth.go               # command source
            streak.go              # command source
        todo/
            .git/                  # git repository metadata
            task/
                task.go            # package source
            todo.go                # command source

このワークスペースは、２つのコマンド(streak, todo)と２つのライブラリ (oauth, task)を含む、３つのリポジトリ(goauth2, streak および todo)が含まれています。

コマンドとライブラリは異なる種類のソースパッケージからビルドされます。区別については後で説明します。

GOPATH 環境変数

GOPATH 環境変数はワークスペースの場所を指定します。これは恐らくGoコードを開発するときにだけ設定する必要がある環境変数です。

まずはじめにワークスペースのディレクトリを作成し、それに応じてGOPATHを設定します。ワークスペースは好きな場所に配置できますが、このドキュメントでは$HOME/goを使用します。これはGoのインストレーションと同じパスであってはいけないことに注意してください。

$ mkdir -p $HOME/go
$ export GOPATH=$HOME/go

便宜的に、ワークスペースの bin サブディレクトリをPATHに追加します:

$ export PATH=$PATH:$GOPATH/bin

パッケージパス

標準ライブラリのパッケージには、"fmt"や"net/http"などの短いパスを与えられています。独自のパッケージでは、標準ライブラリへの将来の追加や他の外部ライブラリとまず衝突することのないベースパスを選択する必要があります。

あなたがどこかのソースリポジトリにコードを保管しているのなら、ベースパスとしてそのソースリポジトリのルートを使う必要があります。例えば github.com/user という Github アカウントを持っている場合は、それがベースパスであるべきです。

ビルドができるよりも前にリモートリポジトリにコードを公開する必要はない、ということに注意してください。ただ、いずれは公開するつもりでコードを整理しておくのは良い習慣です。実際には、標準ライブラリと、より大きなGoエコシステムに於いてユニークである限りは、任意のパス名を選択できます。

私たちはベースパスとして github.com/user を使用します。ワークスペースの中にソースコードを保存するディレクトリを作りましょう:

$ mkdir -p $GOPATH/src/github.com/user

初めてのライブラリ

ライブラリを書いて hello プログラムからそれを使ってみましょう。

繰り返しになりますが、最初の手順はパッケージのパス(ここでは github.com/user/newmath を使います)を選択して、パッケージのディレクトリを作成することです:

$ mkdir $GOPATH/src/github.com/user/newmath

次に、以下の内容で、そのディレクトリに sqrt.go という名前のファイルを作成します。

// Package newmath is a trivial example package.
package newmath

// Sqrt returns an approximation to the square root of x.
func Sqrt(x float64) float64 {
    z := 1.0
    for i := 0; i < 1000; i++ {
            z -= (z*z - x) / (2 * z)
    }
    return z
}

さて、 go build でそのパッケージのコンパイルを試します:

$ go build github.com/user/newmath

またはパッケージのソースディレクトリで作業をしているなら、単に:

$ go build

これは出力ファイルを生成しません。ワークスペースの pkg ディレクトリ内にパッケージオブジェクトを配置するためには、 go install を使わなければなりません。

newmathパッケージがビルドされたことを確認したあと、それを使用するために、オリジナルの ($GOPATH/src/github.com/user/hello にある) hello.go を変更します:

package main

import (
    "fmt"

    "github.com/user/newmath"
)

func main() {
    fmt.Printf("Hello, world.  Sqrt(2) = %v\n", newmath.Sqrt(2))
}

goツールはパッケージやバイナリをインストールするたびに、それが持つあらゆる依存関係もインストールします。そのため hello プログラムをインストールするときには:

$ go install github.com/user/hello

newmathパッケージも同様に、自動的にインストールされます。

プログラムの新しいバージョンを実行すると、いくつか数値の出力が目に付くでしょう:

$ hello
Hello, world.  Sqrt(2) = 1.414213562373095

上記の手順の後、ワークスペースは次のようになります。

bin/
    hello              # command executable
pkg/
    linux_amd64/       # this will reflect your OS and architecture
        github.com/user/
            newmath.a  # package object
src/
    github.com/user/
        hello/
            hello.go   # command source
        newmath/
            sqrt.go    # package source

go installがnewmath.aオブジェクトを、そのソースディレクトリをそっくり映した pkg/linux_amd64 ディレクトリに配置していることに注意してください。これはgo toolの将来の呼び出しがパッケージオブジェクトを見つけて、パッケージの不必要な再コンパイルを避けることができるようにするためです。 linux_amd64 の部分は、クロスコンパイルを支援するためにあり、あなたのシステムのオペレーティングシステムとアーキテクチャに反映されます。

Goコマンド実行可能ファイルは静的にリンクされています; パッケージオブジェクトはGoのプログラムを実行するために存在する必要はありません。

パッケージの名前

Goソースファイルの最初の行は

package name

となり、 name はインポートのためのパッケージのデフォルトの名前でなければなりません。 (パッケージ内の全てのファイルは同じ名前を使用しなければなりません。)

Goの規約では、パッケージ名はインポートパスの最後の要素になります: "crypto/rot13"としてインポートされるパッケージは"rot13"という名前を付ける必要があります。

実行可能コマンドは、常にパッケージ main を使わなければなりません。

パッケージ名は、単一のバイナリにリンクされている全てのパッケージの中で一意である必要はなく、ただ１つインポートパス(それらの完全なファイル名)が一意であることが要件です。

Goの命名規則について詳細を知るためには、 Effective Go を参照してください

テスト

Goはgo testコマンドと testing パッケージで構成される軽量のテストフレームワークを持っています。

func (t *testing.T) シグネチャを持つ TestXXX という名前の関数を含んだ、 _test.go で終わる名前のファイルを作成して、テストを書きます。テストフレームワークではそのような関数を実行します; もし関数が t.Error や t.Fail のような障害関数を呼び出した場合、そのテストは失敗したと見做されます。

以下のGoコードを含むファイル $GOPATH/src/github.com/user/newmath/sqrt_test.go を作成してnewmathパッケージにテストを追加しましょう。

package newmath

import "testing"

func TestSqrt(t *testing.T) {
    const in, out = 4, 2
    if x := Sqrt(in); x != out {
            t.Errorf("Sqrt(%v) = %v, want %v", in, x, out)
    }
}

そうしたら、go testでテストを実行します:

$ go test github.com/user/newmath
ok          github.com/user/newmath 0.165s

いつものように、パッケージディレクトリからgoツールを実行している場合は、パッケージパスを省略できます:

$ go test
ok          github.com/user/newmath 0.165s

詳しいことについては、 go help test を実行して testingパッケージドキュメントを参照してください。

リモートパッケージ

インポートパスは、GitやMercurialのようなバージョン管理システムを使用してパッケージのソースコードを取得する方法を記述することができます。goツールはリモートリポジトリから自動的にパッケージを取得するために、このプロパティを使用しています。例えば、本ドキュメントに記載されている例はGoogle Code code.google.com/p/go.example にホストされたMercurialリポジトリに保管されています。もしあなたがパッケージのインポートパスにリポジトリのURLを含めているなら、go getはそれを自動的に取得して、ビルドし、そしてインストールします:

$ go get code.google.com/p/go.example/hello
$ $GOPATH/bin/hello
Hello, world.  Sqrt(2) = 1.414213562373095

指定されたパッケージがワークスペース内に存在しない場合、go getはまずGOPATHで指定されたワークスペース内に配置します(パッケージが既に存在する場合、go getはリモートの取得をスキップし、go installと同じ様に振る舞います)。

上記のgo getコマンドを発行した後、ワークスペースのディレクトリツリーは次のようになります:

bin/
    hello                 # command executable
pkg/
    linux_amd64/
        code.google.com/p/go.example/
            newmath.a     # package object
        github.com/user/
            newmath.a     # package object
src/
    code.google.com/p/go.example/
        hello/
            hello.go      # command source
        newmath/
            sqrt.go       # package source
            sqrt_test.go  # test source
    github.com/user/
        hello/
            hello.go      # command source
        newmath/
            sqrt.go       # package source
            sqrt_test.go  # test source

Google Codeでホストされている hello コマンドは、同じリポジトリ内のnewmathパッケージに依存しています。 hello.go ファイルの中のインポートは、同じインポートパス規則を使っているので、go getコマンドは依存するパッケージも見つけてインストールすることもできます。

import "code.google.com/p/go.example/newmath"

この規則は、あなたのGoパッケージを他の人が利用可能にするための最も簡単な方法です。 Go Wiki と godoc.org では外部のGoプロジェクトの一覧を提供しています。

goツールを使ったリモートリポジトリの利用に関する詳細については、 go help remote を参照してください。

その他

わかり易く、慣用的なGoコードを書く上でのヒントは、 Effective Go を参照してください。

言語をきちんと学習するには A tour of Go をやりましょう。

Go言語とそのライブラリやツールについての詳細な記事ひとそろいは、ドキュメントページをご覧ください。

shkumagai/how_to_write_go_code.rst