So, I've been writing a bunch of ruby gems recently, and one thing I would find convenient is to include the current version (as specified in the gemspec) in the rdoc-generated documentation for my libraries, and in the OptionParser-generated --help sections used by my scripts (which I'm distributing via gem). Any way I can make it easy for my users to figure out which version of library/script they're currently using.
Is there any way I can access the version I specify in my gemspec from the ruby files in my lib/ or bin/ directories? That way, I don't have to update it multiple places at once - just in my gemspec.
Currently I generate my gemspecs by hand, I haven't jumped on the Rake train yet. If I can't do what I want directly with only what rubygems gives me, would rake or another tool allow me to do this?
There isn't a way, I don't think, because Rubygems is just an installation mechanism for Ruby libraries, which have no predefined notion of versioning.
However, possible workarounds could include using Gem.loaded_specs to find which gems have been loaded:
Gem.loaded_specs["mygemname"].version.to_s #=> "1.2.3"
You might want to take a look at newgem gem - as it both generates appropriate directory layout and also a gemspec file (compatible with GitHub).
Related
I am writing my first real gem. It depends on three gems, and those gems have roughly a dozen dependencies. I'd like this all to be self-contained so my gem will always use the dependencies from inside the gem, and will not require the other gems to be installed at the system level. Doable?
I played around with bundle install --path vendor --standalone. It did indeed store all the gems' source code into vendor, but I could then not get my 'requires' to work correctly and the code could not be found.
I suspect either that it's not possible to do this with a gem (only and app) or I was missing some piece of configuration to point my gem's code at the vendored dependencies. I played around with $LOADPATH but could not make it work.
Anyone know if this can be done and, if so, how to make it work? Pointers to info welcome.
I think you need to add those gems as a dependency to your .gemspec file. That way when your gem gets installed, its dependencies will also be installed.
More information can be found here
It is common to have a version.rb file, defining the version of the gem, like:
module Foo
VERSION = "0.0.1"
end
and in the .gemspec file, require the version.rb and use Foo::VERSION there.
What is the benefit of this convention?
--
Also, sometime when namespace is used, the generated verison file can be deeply in nested folders. Wouldn't it be easier to place a version.rb directly under lib/ and specifying the version there?
This is done this way to reduce churn (change rate) on .gemspec file. I imagine that dependency changes are much more important than version bumps (which are also more frequent). So version changes would add too much noise and hide important commits.
It depends on what gem builder you used. Having a separate file makes it easy to stomp and rebuild as you bump version numbers with rake tasks, for example. this is a lot easier than fiddling with a source file and trying not to damage anything.
Some packagers use a separate VERSION file.
In short, if your gem doesn't need to know the current version itself, then you don't need a version.rb. Even some of the well-known gems like rack don't use it.
Let's say you are building an executable gem that contains an option -v to see the current version, or you have to print current version to warn developers there are some deprecated changes, then to require a separated version file is much more convenient and efficient than parse the gemspec.
It's just a convention in Ruby community. The main reason of why version.rb is everywhere is that lots of gems are built by bundler gem.
I saw that if the gem is installed also the rdoc is generated and you can access the rdoc by
gem server #->localhost:8808
I am thinking of the most common ways how to describe a ruby-developer how to use the gem that was installed. Where i am coming from (java) the apidocs/howtos e.g. are already included in the jars.
I saw that there is a kind of README.rdoc file -convention(?) and thought maybe that's where the ruby-developer will start looking after downloading a gem?
It depends on the developer.
If the README is heavily marked up (e.g., lots of Markdown or RDoc) it's often most convenient to use gem server to access the Gem documentation from a local gem doc server.
Or follow the www link in the gem server listing, or read the file manually.
Additional documentation source is generally included in the doc directory, built using normal Ruby tools (rake and/or rdoc).
I'm not entirely sure what you're asking, though. First, Java libraries generally don't include the API docs or source, they're generally bundled separately, particularly if you're using Maven. Gems include the source, so RDoc can always be generated.
In Java, examples are only present if (a) the developer (IMO abuses) Javadocs by including the examples in the API docs, or (b) examples are included in the source and you have the source. It's rare there are "howtos" in a downloaded Java library, unless it was developed using Maven, you package the site, and the site includes usage pages beyond the normal API reports.
As the title states, I'm a beginner in Ruby.
My project uses 2 existing gems - which I want to modify.
I've forked the gems on GitHub and put them as modules in my repo and they show up as a subdirectory.
I've tried researching this, but I keep on getting lost - I'm thinking I'm missing some basic concepts/knowledge here.
My questions:
Am I going about this right/wrong?
Is it even possible to include the code of those (forked) gems in my actual project, or should I update them separately and just use them as actual gems with require (this seems very cumbersome)
If these gems are part of my project, how do I use them properly, I assume I don't need the require piece? If not, how do I access/use them?
Thanks!
BTW, using Ruby 1.9.2-p194 on Ubuntu with RubyMine as the IDE.
Probably wrong. Ruby is a very flexible language, and has what are called open classes. This means that you can open up and change classes at run-time. Doing this on an external library is called monkey patching. So instead of having to replicate all of the code you want to stay consistent, you can just modify the classes and override any methods you want.
A simple example:
class Fixnum
def is_multiple_of_three?
self % 3 == 0
end
end
However, if the changes you want are really significant, it could make sense to fork the gem.
I recommend the bundler gem. This will let you make a Gemfile which lists all of your dependencies. You can list a github repository as a source for the gem, like so:
gem 'gem_name_here', :git => 'git://github.com/username_here/gem_name_here.git'
and then run bundle install to install your dependencies.
If you install the gems with bundler, it acts just like any other gem you have installed.
There have been questions with answers on how to write rubygems, but what should you avoid in writing a rubygem? What can cause problems for people using your rubygem?
Gem Packaging: Best Practices gives a lot of advice, some of which include
Don't pollute the global load path. Ideally, only have foo.rb in your lib directory, and put all your other files in lib/foo.
Don't require files using __FILE__.
Don't rely on anything outside the load path. Folders may not have the same structure as in your original version. For example, don't use something like
VERSION = ::File.read(::File.join(::File.dirname(FILE), "..", "..", "VERSION")).strip
Don't manage $LOAD_PATH within lib.
Provide a VERSION constant.
Don't depend on rubygems. The person using your code may not be using rubygems, but some other packaging system (or no packaging system). Similarly, don't mention version dependencies in the code itself, or rescue Gem::LoadError.
Rubygems dependencies. Please... argues that you shouldn't list optional runtime dependencies, and should separate developer from runtime dependencies.
From my own experience: if nothing else, try building and installing your gem locally before releasing it into the wild. It avoids brown paper bag releases.