newgem-0.10.4を使ったrubyforgeプロジェクトの管理

を作るにあたり、プロジェクトテンプレートとして、newgemを使いました。

これは

newgem -n "PatternMatching module" -t rspec -v 0.1.0 patternmatching

などのようにして、Rakefileなどがそろった雛形が作られます。

そこに、lib以下に作っておいたライブラリをコピーし、いくつかのファイルを修正してやれば、あっというまにRubyforgeにあったプロジェクトのファイル構造を作ることができます。アップロードしたサイトも(素のHTMLに比べれば)それなりに見栄えのするように作ってくれます。

修正していくファイル

  • README.txt
    • rdocで生成するAPI文書のトップページにもなるので、RDoc形式で記述しましょう。
  • History.txt
    • RDoc形式です。パッケージのアップロード時に使われます。
  • Manifest.txt
    • rakeのパッケージ作成で、パッケージに含めるファイルの一覧です。
  • License.txt
    • デフォルトではMIT Licenseです。
  • Rakefile
    • DESCRIPTION、依存パッケージ等、細かい修正が必要です。
  • lib/patternmatching.rb
    • 必要なrbファイルはここでrequire します。
  • lib/patternmatching/version.rb
    • バージョン情報はここで設定します。
  • spec/patternmatching_spec.rb
    • デフォルトでは失敗するようになっているので、修正します。
  • website/index.txt
    • Textile形式です。index.htmlを生成するソースなので、適切に修正しましょう。

rspecのRakefileはデフォルトではrspecタスクにlibのパスが通っていないので、追加しましょう。

desc "Run the specs under spec/models"
Spec::Rake::SpecTask.new do |t|
  t.spec_opts = ['--options', "spec/spec.opts"]
  t.spec_files = FileList['spec/*_spec.rb']
  t.libs << "lib" # <= これ必要
end

Manifest.txtは以下のmakemanifest.rbをscriptsにおいて、実行して自動生成させてます。

#!/usr/bin/ruby

base_dir = File.join(File.dirname(__FILE__), "..")
glob_pattern = File.join("**", "*")
exclude_patterns = [
  /^pkg/,/^doc/,
]

Dir.chdir(base_dir)
files = Dir.glob(glob_pattern).delete_if do |fname|
  File.directory?(fname) or
  exclude_patterns.find do |pattern|
    pattern =~ fname
  end
end
manifest = File.new("Manifest.txt", "w")
manifest.puts files.sort.join("\n")
manifest.close

puts "Manifest.txt updated"

タスク

rake --tasksで一覧が出ます。以下よく使うものです。

  • rake spec
    • rspecでチェックします
ファイル生成系
  • rake clobber
    • 生成したpkg/とdoc/にあるファイルを消します。
  • rake package
    • pkg/下ににパッケージを作成します。
  • rake docs
    • doc/下にrdoc生成します。
  • rake website_generate
    • website/index.html を生成します。
アップロード系

生成時のRakefileでは、rake releaseではpublish_docsされません。
もし、同時にアップロードしたいなら、以下のように書き換えるといいでしょう。

task :website => [:website_generate, :website_upload, :publish_docs]

修正後、リリース時に行うこと

  • 必ず、rake spec でエラーがでないようにする
  • example/, README.txt, index.txt ほか、 現状のAPIに合わせる
  • Histrory.txt に変更履歴を入れる
  • 最後に lib/*/version.rb を更新する
  • 上記ファイルを確認してから、 rake VERSION=x.y.z deploy
  • truncをtagsにsvn cpする

注意点

いくつかのタスクでは、コマンドrubyforge setupやrubyforge configを適切に行っている必要があります。newgemが生成する設定は、このようにRubyForgeの構造に依存した部分があるので、その他のプロジェクト管理システムのためのプロジェクトにはあまり向いてません。

また、rdocはトップレベルのmoduleのドキュメントは生成しません。トップレベルmoduleで機能が必要な場合は、内側に内部moduleをつくり、そこにメソッドやドキュメントを置いて、下でincludeしてあげるといいでしょう。

docsやridocsとかで生成したファイルをリポジトリやパッケージに含める必要はありません。導入側のgem installで適切に生成してくれます。

あと、rubygemsでは、どうもメソッドyがObjectに追加されるので、"y"という変数やメソッドは、コアはもちろん例やspecで使わないほうがいいです。念のため。ほかにもrspecとかでぶつかるmatch等、避けたいメソッドは結構あったりします。