add_dependency vs add_runtime_dependency: unclear on which one to use #7799Description
Reference: rubygems/guides#370
Problem
When adding a non-development dependency to a gemspec, it can be unclear what to use between add_dependency and add_runtime_dependency.
Let me elaborate by doing a comparison across different places.
In the docs and generators
-
add_dependencyis more prominent in the Bundler guide on how to create a Ruby gem, and it is mentioned in the gemspec generated bybundle gem:... # Uncomment to register a new dependency of your gem # spec.add_dependency "example-gem", "~> 1.0" # For more information and examples about making a new gem, check out our # guide at: https://bundler.io/guides/creating_gem.html endIn both cases
add_runtime_dependencyis not mentioned. -
add_runtime_dependencyis more prominent in rubydoc and in the specification reference.add_dependencyis mentioned as an alias, feeling more like an aside.
In the wild
- A sourcegraph search shows 92.3k results for
add_dependency, and 33.6k results foradd_runtime_dependency, soadd_dependencyis used 73% of the time. - A github search shows 202k files using
add_dependency, and 87k files usingadd_runtime_dependency, soadd_dependencyis used 70% of the time. - In my collection of manually curated real world Ruby apps, with a small sample size of 63 repos,
add_dependencyis used in 35 gemspecs, andadd_runtime_dependencyis used in 19 gemspecs, so when there is a gemspecadd_dependencyis used 65% of the time.
In the code
-
In
Gem::Specification,add_dependencyis currently an alias foradd_runtime_dependency:alias_method :add_dependency, :add_runtime_dependency
-
After doing a bit of Git history archeology 🕵️ , it turns out that
add_dependencywas the original method for adding a dependency, going all the way back to 2003 and maybe more. The notion of development dependencies was introduced in 2008 whenadd_development_dependencyandadd_runtime_dependencywere created, andadd_dependencygot relegated to an alias. I don't know if this relegation or downgrade in status was conscious or just happened by chance and one had to be picked as the alias.
Interpretation
I don't know if there was a conscious push for either add_dependency or add_runtime_dependency, or if both just happened organically. It seems to me that the latter case is what happened, but maybe someone who is more well versed into rubygems can shed more light on the matter.
The current state of affairs seems to be that add_dependency is the more popular way in terms of usage, and the Bundler guide and bundler gem code generation suggestion only mention this way.
Possible solutions
@deivid-rodriguez mentioned some possible solutions here. Here is is a non-exhaustive list with my suggestions as well:
-
Edit the specification reference to show separate entries for aliases. Maybe by making them look as important as non-aliased methods like this:
This is similar to what the Rails API does for example here.
-
Or invert so that
add_dependencybecomes the main method, andadd_runtime_dependencythe alias, which would look like this:
-
Or use
add_runtime_dependencyin thebundle gemgenerated gemspec and maybe useadd_runtime_dependencyin the Bundler guide -
Maybe this is a non-issue and there is no main way to go, and it all depends on what context you're in.
add_development_dependencycould be considered a nice symmetrical counterpoint toadd_runtime_dependencywhen using both in the same gemspec.If using the Gemfile for development dependencies and gemspec for non-development dependencies, which is what currently happens when doing
bundle gem, then the way it is currently done (i.e. suggestingadd_dependencyin the generated gemspec) can make more sense, as in the gemspec there wouldn't be any development dependency to be a counterpoint to.If no way is more preferable than the other, then we can just close this issue. One would just use what feels right depending on the context or their personal preferences. Although I would argue that doing something like solution 1 could still be useful to feature
add_dependencyon a more equal footing asadd_runtime_dependency.