Tutorial

We introduce how to use Packnga with Packnga’s Rakefile and gemspec in this page.

Install

You can install Packnga from Rubygems.

% sudo gem install packnga

Prepare to create tasks

Before using Packnga, you should create spec variable with Gem::Specification.new or Jeweler::Tasks.new. Packnga create tasks with spec in Rakefile.

Create spec with Gem::Specification.new

We introduce to create spec with Gem::Specification.new in a gemspec file. Please see below gemspec example with Gem::Specification.new.

version = Packnga::VERSION.dup

readme_path = File.join(base_dir, "README.textile")
entries = File.read(readme_path).split(/^h2\.\s(.*)$/)
entry = lambda do |entry_title|
  entries[entries.index(entry_title) + 1]
end

authors = []
emails = []
entry.call("Authors").each_line do |line|
  if /\*\s*(.+)\s<([^<>]*)>$/ =~ line
    authors << $1
    emails << $2
  end
end

clean_white_space = lambda do |entry|
  entry.gsub(/(\A\n+|\n+\z)/, '') + "\n"
end
description = clean_white_space.call(entry.call("Description"))
summary, description = description.split(/\n\n+/, 2)

Gem::Specification.new do |s|
  s.name = "packnga"
  s.version = version
  s.authors = authors
  s.email = emails
  s.summary = summary
  s.description = description

  s.extra_rdoc_files = ["README.textile"]
  s.files = ["README.textile", "Rakefile", "Gemfile"]
  Dir.chdir(base_dir) do
    s.files += Dir.glob("lib/**/*.rb")
    s.files += Dir.glob("doc/text/*.*")
  end

  s.homepage = "http://ranguba.org/"
  s.licenses = ["LGPLv2"]
  s.require_paths = ["lib"]

  s.add_runtime_dependency("rake")
  s.add_runtime_dependency("yard")
  s.add_runtime_dependency("gettext")
  s.add_development_dependency("test-unit")
  s.add_development_dependency("test-unit-notify")
  s.add_development_dependency("bundler")
  s.add_development_dependency("RedCloth")
end

Next, we should get spec value in Rakefile from gemspec, so we write below source code in Rakefile.

helper = Bundler::GemHelper.new(base_dir)
helper.install
spec = helper.gemspec

Create spec with Jeweler::Tasks.new

If you want to create spec with Jeweler::Tasks.new in your Rakefile, please see below example. This source code is written in old Packnga’s Rakefile.

spec = nil
Jeweler::Tasks.new do |_spec|
  spec = _spec
  spec.name = "packnga"
  spec.version = version
  spec.homepage = "http://ranguba.org/"
  spec.authors = ["Haruka Yoshihara", "Kouhei Sutou"]
  spec.email = ["yoshihara@clear-code.com", "kou@clear-code.com"]
  entries = File.read("README.textile").split(/^h2\.\s(.*)$/)
  description = cleanup_white_space(entries[entries.index("Description") + 1])
  spec.summary, spec.description, = description.split(/\n\n+/, 3)
  spec.license = "LGPLv2"
  spec.files = FileList["lib/**/*.rb",
                        "Rakefile",
                        "README.textile",
                        "Gemfile",
                        "doc/text/**"]
  spec.test_files = FileList["test/**/*.rb"]
end

Create tasks

Packnga’s classes has charge of each tasks. This table describes Packnga’s classes.

Packnga::DocumentTask

This class create tasks for generating references. It define tasks to generate YARD documentation and po files. It also defines tasks to translate documents with po files.

Packnga::ReleaseTask

This class create tasks for uploading references and package and preparing to upload them. It defines a task to tag the current version in git and a task to user-install gem for test.

Please see below for creating tasks.

Packnga::DocumentTask.new(spec)
Packnga::ReleaseTask.new(spec)

Set the document path.

You can set parameters with block when creating object of Packnga::DocumentTask and Releasetask. For example, We introduce to how to set base directory for document. Document is created in this directory. You can write Rakefile to set this directory path, see below.

NOTE: Please set same path to each clasess.

Packnga::DocumentTask.new(spec) do |task|
  task.base_dir = "doc/"
end

Packnga::ReleaseTask.new(spec) do |task|
  task.base_dir = "doc/"
end

You can set other parameters. Please see Packnga’s reference manual in detail.