The Project class provides the location of specific directories and files in the project, plus access to the projects metadata, etc.
New project with metadata fully loaded.
# File lib/pom/project.rb, line 36 def self.load(*path_opts) path = path_opts.shift unless Hash===options.first opts = path_opts.last opts[:load] = true new(path, opts) end
Instantiate a new Project looking up the root directory form a given local.
Project.lookup(local)
# File lib/pom/project.rb, line 28 def self.lookup(*path_opts) path = path_opts.shift unless Hash===options.first opts = path_opts.last opts[:lookup] =true new(path, opts) end
Instantiate a new project.
If a root directory is not given, it will be looked-up starting from the current working directory until a meta/ directory is found.
The :lookup option can be used to induce a lookup from a given location.
# File lib/pom/project.rb, line 55 def initialize(*root_opts) root = root_opts.shift unless Hash===root_opts.first opts = root_opts.last || {} if opts[:lookup] || !root root = self.class.root(root) raise("cannot locate project root -- #{root}") unless root end @root = Pathname.new(root) @opts = opts #metadata.load #if opts[:load] #if options[:lookup] # @root = locate_root(local) || raise("can't locate project root -- #{local}") #end @source = root end
Locate the project’s root directory. See POM::root.
# File lib/pom/project.rb, line 19 def self.root(local=Dir.pwd) POM.root(local) end
About project notice.
# File lib/pom/project.rb, line 358 def about(*parts) # pre-format data released = package.date ? "(#{package.date.strftime('%Y-%m-%d')})" : nil if parts.empty? s = [] s << "#{profile.title} v#{package.version} #{released} (#{package.name}-#{package.version})" s << "" s << "#{profile.description || profile.summary}" s << "" s << "* home: #{profile.resources.homepage}" if profile.resources.homepage s << "* work: #{profile.resources.work}" if profile.resources.work s << "* talk: #{profile.resources.mail}" if profile.resources.mail s << "* talk: #{profile.resources.forum}" if profile.resources.forum s << "* repo: #{profile.resources.repository}" if profile.resources.repository s << "" s << "#{profile.copyright}" s.join("\n").gsub("\n\n\n", "\n\n") else parts.each do |field| case field.to_sym #when :settings # puts settings.to_yaml when :profile puts profile.to_yaml else puts profile.__send__(field) end end end end
Project release announcement built on README.
# File lib/pom/project.rb, line 390 def announcement(*parts) ann = [] parts.each do |part| case part when :message ann << "#{profile.title} #{self.version} has been released." when :description ann << "#{profile.description}" when :resources list = '' list << "* home: #{profile.resources.home}\n" if profile.resources.home list << "* work: #{profile.resources.work}\n" if profile.resources.work list << "* docs: #{profile.resources.docs}\n" if profile.resources.docs ann << list when :release ann << "= #{title} #{history.release}" when :version ann << "= #{history.release.header}" when :notes ann << "#{history.release.notes}" when :changes ann << "#{history.release.changes}" #when :line # ann << ("-" * 4) + "\n" when :readme release = history.release.to_s if file = Dir.glob(README, File::FNM_CASEFOLD).first readme = File.read(file).strip readme = readme.gsub("Please see HISTORY file.", '= ' + release) ann << readme end when String ann << part when File ann << part.read part.close end end ann.join("\n\n").unfold end
The .cache/ directory is used by build tools to store temporary files. For instance, the pom command uses it to store backups of metadata entries when overwriting old entries. .cache/ should be in your SCM’s ignore list.
Get pathname of given cache path. Or without path returns the pathname for the cache directory.
# File lib/pom/project.rb, line 230 def cache(path=nil) if path cache + path else @cache ||= root + '.cache' end end
# File lib/pom/project.rb, line 136 def codename metadata.codename end
# File lib/pom/project.rb, line 353 def compiles? !extensions.empty? end
The .config/ or config directory is a place for build tools to place their configration files.
Pathname of given config path. Or without path Returns the path to the config directory (either .config or config).
# File lib/pom/project.rb, line 244 def config(path=nil) if path config + path #root.glob_first('{.,}config' / path) else @config ||= root.first('{.,}config') || root + '.config' end end
The doc directory is the place to keep documentation. The directory is intended to be distributed with a package, but this is not often done these days since RubyGems generates RDocs on demand, and documentation is often found online.
Get pathname of given doc path. Or without path returns the pathname for the doc directory.
# File lib/pom/project.rb, line 196 def doc(path=nil) if path doc + path else @doc ||= root + 'doc' end end
Returns list of executable files in bin/.
# File lib/pom/project.rb, line 342 def executables root.glob('bin/*').select{ |bin| bin.executable? }.map{ |bin| File.basename(bin) } end
List of extension configuration scripts. These are used to compile the extensions.
# File lib/pom/project.rb, line 348 def extensions root.glob('ext/**/extconf.rb') end
Access to project history.
# File lib/pom/project.rb, line 165 def history @history ||= History.new(root) end
Import a Gem::Specification into a POM::Project. This is intended to make it farily easy to build a set of POM metadata files from pre-existing gemspec.
# File lib/pom/gemspec.rb, line 134 def import_gemspec(gemspec=nil) gemspec = gemspec || self.gemspec package.name = gemspec.name package.version = gemspec.version.to_s package.path = gemspec.require_paths #package.arch = gemspec.platform profile.title = gemspec.name.capitalize profile.summary = gemspec.summary profile.description = gemspec.description profile.authors = gemspec.authors profile.contact = gemspec.email profile.resources.homepage = gemspec.homepage #metadata.extensions = gemspec.extensions gemspec.dependencies.each do |d| next unless d.type == :runtime requires << "#{d.name} #{d.version_requirements}" end end
Get POM metadata from a README. This is intended to make it fairly easy to build a set of POM’s metadata files if you already have a README.
# File lib/pom/readme.rb, line 182 def import_readme(readme=nil) readme = readme || self.readme package.name = readme.name if readme.name profile.title = readme.title if readme.title profile.description = readme.description if readme.description profile.license = readme.license if readme.license profile.copyright = readme.copyright if readme.copyright profile.authors = readme.authors if readme.authors profile.resources.homepage = readme.homepage if readme.homepage profile.resources.wiki = readme.wiki if readme.wiki profile.resources.issues = readme.issues if readme.issues end
# File lib/pom/project.rb, line 131 def loadpath metadata.loadpath end
The log/ directory stores log output created by build tools. If you want to publish your logs as part of your website (which might be a very nice thing to do) symlink it into you site location.
Get pathname of given log path. Or without path returns the pathname for the log directory.
# File lib/pom/project.rb, line 181 def log(path=nil) if path log + path else @log ||= root + 'log' end end
Project manifest. For manifest file use manifest.file.
# File lib/pom/project.rb, line 160 def manifest @manifest ||= Manifest.new(root) end
Provides access to both profile and package information through a single interface. This will probably be removed from API.
# File lib/pom/project.rb, line 96 def metadata @metadata ||= Metadata.new(root, @opts) end
Project name.
# File lib/pom/project.rb, line 116 def name metadata.name end
Access latest release notes.
# File lib/pom/project.rb, line 170 def news @news ||= News.new(root, :history=>history) end
General information.
# File lib/pom/project.rb, line 106 def package metadata.package end
Package name is generally in the form of name-version, or name-version-platform if platform is specified.
# File lib/pom/project.rb, line 142 def package_name(options={}) if platform = options[:platform] "#{name}-#{version}-#{platform}" else "#{name}-#{version}" end end
Returns the pathname for the package directory. With path returns the pathname within the pacakge path.
# File lib/pom/project.rb, line 206 def pkg(path=nil) if path pkg + path else @pkg ||= root.first('{pkg,pack,package}{,s}') || root + 'pkg' end #@pkg ||=( # dir = root.glob_first('{pack,pkg}{,s}') || 'pack' # dir.mkdir_p unless dir.exist? # dir #) end
The plug/ directory serves the same purpose as the lib/ directory. It simply provides a place to put plugins separate from the main lib/ files.
Get pathname of given plugin path. Or without path returns the pathname for the plugin directory.
TODO: This assumes lib/ is in the load path, and is used to house plugin/. This is of course typical. However it is possible to alter the load path. So it may not always be the case. In the future, it must be decided if we should standardize around the lib/ convention (though you could still add others to the load path) or allow it to be complete free form. As I did for bin/, I prefer the former, but have not yet firmly decided.
# File lib/pom/project.rb, line 266 def plugin(path=nil) if path plugin + path else @plugin ||= root.first('lib/plugins') || root + 'lib/plugins' end end
General information.
# File lib/pom/project.rb, line 101 def profile metadata.profile end
# File lib/pom/readme.rb, line 175 def readme @readme ||= Readme.load(root) end
Current release information.
# File lib/pom/project.rb, line 111 def release metadata.release end
Require RubyGems library.
# File lib/pom/gemspec.rb, line 6 def require_rubygems begin require 'rubygems' #/specification' #::Gem::manage_gems rescue LoadError raise LoadError, "RubyGems is not installed." end end
Requirements Configuration.
# File lib/pom/project.rb, line 154 def requirements @require ||= Require.new(root) end
The script/ directory is like the task/ directory but usually holds executables that are made available to the end-installers.
Get pathname of given script path. Or without path returns the pathname for the script directory.
# File lib/pom/project.rb, line 283 def script(path=nil) if path script + path else @script ||= root + 'script' end end
The site/ directory (also web/ or website/) is where a project’s website is stored.
Get pathname of given site path. Or without path returns the pathname for the site directory.
# File lib/pom/project.rb, line 309 def site(path=nil) if path site + path else @site ||= root.first('{site,web,website}') || root+'site' end #@pkg ||=( # dir = root.glob_first('{pack,pkg}{,s}') || 'pack' # dir.mkdir_p unless dir.exist? # dir #) end
The task/ directory is where task scripts are stored used by build tools, such as Rake and Syckle.
Get pathname of given task path. Or without path returns the pathname for the task directory.
# File lib/pom/project.rb, line 296 def task(path=nil) if path task + path else @task ||= root.first('{task,tasks}') || root+'task' end end
Not strickly a project directory. THis provides a temporary system location outside the project directory.
Get pathname of given temporary path. Or without path returns the pathname to the temporary directory.
# File lib/pom/project.rb, line 330 def tmp(path=nil) if path tmp + path else @tmp ||= Pathname.new(Dir.tmpdir) #cache+'tmp' end end
Create a Gem::Specification from a POM::Project. Becuase POM metadata is extensive a fairly complete Gem::Specification can be created from it –sufficient for almost all needs.
TODO: However there are still a few features that need address, such as gem signatures.
# File lib/pom/gemspec.rb, line 22 def to_gemspec(options={}) require_rubygems if md = /(\w+).rubyforge.org/.match(profile.homepage) rubyforge_project = md[1] else rubyforge_project = metadata.name # b/c it has to be something according to Eric Hodel. end ::Gem::Specification.new do |spec| spec.name = self.name spec.version = self.version spec.require_paths = self.loadpath spec.summary = profile.summary spec.description = profile.description spec.authors = profile.authors spec.email = profile.email spec.homepage = profile.homepage # -- platform -- # TODO: how to handle multiple platforms? spec.platform = options[:platform] #|| verfile.platform #'ruby' ??? #if metadata.platform != 'ruby' # spec.require_paths.concat(spec.require_paths.collect{ |d| File.join(d, platform) }) #end # -- rubyforge project -- spec.rubyforge_project = rubyforge_project # -- compiled extensions -- spec.extensions = options[:extensions] || self.extensions # -- dependencies -- case options[:gemfile] #when String # gemfile = root.glob(options[:gemfile]).first # TODO: Alternate gemfile when nil, true gemfile = root.glob('Gemfile').first else gemfile = nil end if gemfile require 'bundler' spec.add_bundler_dependencies elsif requires.file requires.dependencies.each do |dep| if dep.development? spec.add_development_dependency( *[dep.name, dep.constraint].compact ) else next if dep.optional? spec.add_runtime_dependency( *[dep.name, dep.constraint].compact ) end end end # TODO: considerations? #spec.requirements = options[:requirements] || package.consider # -- executables -- # TODO: bin/ is a POM convention, is there are reason to do otherwise? spec.bindir = options[:bindir] || "bin" spec.executables = options[:executables] || self.executables # -- rdocs (argh!) -- readme = root.glob_relative('README{,.*}', File::FNM_CASEFOLD).first extra = options[:extra_rdoc_files] || [] rdocfiles = [] rdocfiles << readme.to_s if readme rdocfiles.concat(extra) rdocfiles.uniq! rdoc_options = [] #['--inline-source'] rdoc_options.concat ["--title", "#{metadata.title} API"] #if metadata.title rdoc_options.concat ["--main", readme.to_s] if readme spec.has_rdoc = true # always true spec.extra_rdoc_files = rdocfiles spec.rdoc_options = rdoc_options # -- distributed files -- if manifest.exist? filelist = manifest.select{ |f| File.file?(f) } spec.files = filelist else spec.files = root.glob_relative("**/*").map{ |f| f.to_s } # metadata.distribute ? end # -- test files -- # TODO: Improve. Make test_files configurable (?) spec.test_files = manifest.select do |f| File.basename(f) =~ /test/ && File.extname(f) == '.rb' end end end
Generated with the Darkfish Rdoc Generator 2.