Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 259 lines (201 sloc) 10.024 kb
44c55cd @rtomayko README formatting tweaks
authored
1 rpg - manages gem packages. quickly.
5bb3741 @rtomayko tone down the README + markdown
authored
2 ====================================
a925852 @rtomayko README
authored
3
44c55cd @rtomayko README formatting tweaks
authored
4 This is rpg, an experimental Ruby package management utility for unix based on
5 the Rubygems packaging format and repository protocol. rpg installs Ruby
6 packages distributed from rubygems.org to a shared library directory with full
7 support for dependency resolution, native extension compilation, and package
b24e9eb @rtomayko tidy up the Versus Rubygems README section
authored
8 upgrades. It's quite fast.
a925852 @rtomayko README
authored
9
451b558 @rtomayko more fucking around in the README. done now. for real this time.
authored
10 `rpg` can be thought of as a non-compatible alternative to the `gem` command
11 shipped with Rubygems. Most commonly used gem operations are available in `rpg`,
12 but in ways that are a bit different from the `gem` command -- both in interface
13 and implementation. See the *VERSUS RUBYGEMS* section below for details on these
5bb3741 @rtomayko tone down the README + markdown
authored
14 differences.
a925852 @rtomayko README
authored
15
37c0dec @rtomayko surgeory on the README/TODO
authored
16 rpg and Rubygems can co-exist on a system, though Rubygems is not required for
b24e9eb @rtomayko tidy up the Versus Rubygems README section
authored
17 rpg to operate. Packages installed with `rpg` override packages installed with
18 the `gem` command.
a925852 @rtomayko README
authored
19
854bbc1 @rtomayko README links to the rpg mailing list
authored
20 Please direct rpg related discussion to the rpg mailing list:
21 [ruby-rpg@googlegroups.com](http://groups.google.com/group/ruby-rpg).
22
44c55cd @rtomayko README formatting tweaks
authored
23 Status
37c0dec @rtomayko surgeory on the README/TODO
authored
24 ------
25
5bb3741 @rtomayko tone down the README + markdown
authored
26 Experimental. Using rpg with system rubys is not yet recommended. Suggested use
44c55cd @rtomayko README formatting tweaks
authored
27 is with rvm or custom, non-system ruby builds. See the `KNOWN-ISSUES` file for a
5bb3741 @rtomayko tone down the README + markdown
authored
28 list of potential gotchas and general annoyances.
a925852 @rtomayko README
authored
29
5bb3741 @rtomayko tone down the README + markdown
authored
30 IMPORTANT: In its default configuration, rpg installs library files under the
31 active Ruby interpreter's `vendor_ruby` or `site_ruby` directory. The `rpg
32 config` command outputs the current destination installation paths -- use it to
33 verify the active configuration before performing destructive operations.
a925852 @rtomayko README
authored
34
44c55cd @rtomayko README formatting tweaks
authored
35 Installing
37c0dec @rtomayko surgeory on the README/TODO
authored
36 ----------
a925852 @rtomayko README
authored
37
44c55cd @rtomayko README formatting tweaks
authored
38 rpg is installed with the conventional `./configure && make && make install`
39 process. See the `INSTALLING` file for information on obtaining the latest
40 release and variations on the basic installation.
a925852 @rtomayko README
authored
41
b24e9eb @rtomayko tidy up the Versus Rubygems README section
authored
42 See the `HACKING` file for information on setting up a temporary working
44c55cd @rtomayko README formatting tweaks
authored
43 environment for development, or if you just want to try out rpg in a sandbox
44 before installing.
a925852 @rtomayko README
authored
45
bcccad0 @rtomayko README section on basic program usage
authored
46 Basic Usage
47 -----------
48
49 For a list of commands and basic program usage:
50
51 $ rpg --help
52 Usage: rpg [-vx] [-c <path>] <command> [<args>...]
53 Manage gem packages, quickly.
54
55 The most commonly used rpg commands are:
56 config Show or edit rpg configuration
57 dependencies Show dependency information for a package or all packages
58 install Install a package from file or remote repository
59 list Show status of local packages vs. respository
60 steal Transplant packages from Rubygems into rpg environment
61 sync Sync the package index with repository
62 outdated List packages with a newer version
63 uninstall Uninstall packages from local system
64 upgrade Upgrade installed packages to latest version
65
66 Options
67 -c <path> Read rcfile at <path> instead of standard rpgrc locations
68 -v Enable verbose logging to stderr
69 -q Disable verbose logging to stderr
70 -x Enable shell tracing to stderr (extremely verbose)
71
72 See `rpg help <command>' for more information on a specific command.
73
74 Installing one or more packages and all package dependencies:
75
76 $ rpg install rails
77 sync: package index not found. retrieving now.
78 sync: complete. 11894 packages available.
79 prepare: calculating dependencies for rails ...
80 fetch: rails 2.3.5
81 fetch: activeresource 2.3.5
82 fetch: actionmailer 2.3.5
83 fetch: actionpack 2.3.5
84 fetch: activesupport 2.3.5
85 fetch: rake 0.8.7
86 fetch: activerecord 2.3.5
87 fetch: rack 1.0.1
88 prepare: 0 of 8 packages already installed and up to date
89 install: installing 8 packages
90 package-install: actionmailer 2.3.5
91 package-install: actionpack 2.3.5
92 package-install: activerecord 2.3.5
93 package-install: activeresource 2.3.5
94 package-install: activesupport 2.3.5
95 package-install: rack 1.0.1
96 package-install: rails 2.3.5
97 package-install: rake 0.8.7
98 install: installation complete
99
100 Listing currently installed packages and their versions:
101
102 $ rpg list
103 actionmailer 2.3.5
104 actionpack 2.3.5
105 activerecord 2.3.5
106 activeresource 2.3.5
107 activesupport 2.3.5
108 rack 1.0.1
109 rails 2.3.5
110 rake 0.8.7
111
112 Listing currently installed packages with information about available package
113 versions:
114
115 $ rpg list -l
116 actionmailer 2.3.5 2.3.5
117 actionpack 2.3.5 2.3.5
118 activerecord 2.3.5 2.3.5
119 activeresource 2.3.5 2.3.5
120 activesupport 2.3.5 2.3.5
121 * rack 1.0.1 1.1.0
122 rails 2.3.5 2.3.5
123 rake 0.8.7 0.8.7
124
125 Listing only outdated packages:
126
127 $ rpg outdated
128 rack 1.0.1 1.1.0
129
130 Uninstalling one or more packages:
131
132 $ rpg uninstall rails actionmailer
133
134 Listing package dependencies recursively:
135
136 $ rpg dependencies -r rails
137 actionmailer = 2.3.5
138 actionpack = 2.3.5
139 activerecord = 2.3.5
140 activeresource = 2.3.5
141 activesupport = 2.3.5
142 rack ~> 1.0.0
143 rake >= 0.8.3
144
145 Or, in a tree:
146
147 $ rpg dependencies -t rails
148 rake >= 0.8.3
149 activesupport = 2.3.5
150 activerecord = 2.3.5
151 |-- activesupport = 2.3.5
152 actionpack = 2.3.5
153 |-- activesupport = 2.3.5
154 |-- rack ~> 1.0.0
155 actionmailer = 2.3.5
156 |-- actionpack = 2.3.5
157 | |-- activesupport = 2.3.5
158 | |-- rack ~> 1.0.0
159 activeresource = 2.3.5
160 |-- activesupport = 2.3.5
161
162 To get a feel for rpg performance vs. the gem command when install packages with
163 complex dependency graphs:
164
165 $ time rpg install merb
166 $ time gem install merb
167
44c55cd @rtomayko README formatting tweaks
authored
168 Versus Rubygems
37c0dec @rtomayko surgeory on the README/TODO
authored
169 ---------------
a925852 @rtomayko README
authored
170
b24e9eb @rtomayko tidy up the Versus Rubygems README section
authored
171 Similarities with the `gem` command:
172
173 * `rpg` uses rubygems.org as its package repository and gem
a925852 @rtomayko README
authored
174 files as its package format. Installing from other sources is not yet
5bb3741 @rtomayko tone down the README + markdown
authored
175 supported, but is likely to be added in the near future.
a925852 @rtomayko README
authored
176
b24e9eb @rtomayko tidy up the Versus Rubygems README section
authored
177 * `rpg` supports dependency resolution using the information
37c0dec @rtomayko surgeory on the README/TODO
authored
178 included in a gem's specification metadata.
a925852 @rtomayko README
authored
179
b24e9eb @rtomayko tidy up the Versus Rubygems README section
authored
180 * `rpg` supports building and installing native / dynamic library
a925852 @rtomayko README
authored
181 extensions.
182
b24e9eb @rtomayko tidy up the Versus Rubygems README section
authored
183 * `rpg` has a rich set of commands for installing, upgrading,
a925852 @rtomayko README
authored
184 and uninstalling packages; listing installed, available, and outdated
185 packages; and utilities for unpacking gem files and inspecting gem
186 specifications.
187
b24e9eb @rtomayko tidy up the Versus Rubygems README section
authored
188 * "rpg" is made of exactly three characters.
189
190 Differences from the `gem` command:
a925852 @rtomayko README
authored
191
b24e9eb @rtomayko tidy up the Versus Rubygems README section
authored
192 * `rpg` organizes the files it installs by file type, not by package. For
193 instance, Ruby library files are placed directly under a single
194 `lib` directory (the currently active `site_ruby` directory by default),
195 executables under `/usr/local/bin` (configurable), manpages under
196 `/usr/local/share/man`, etc.
a925852 @rtomayko README
authored
197
b24e9eb @rtomayko tidy up the Versus Rubygems README section
authored
198 * `rpg` is not capable of installing multiple versions of the same package
199 into a single rpg environment -- the package's files would overwrite each
200 other. All version conflicts must be resolved at install time.
a925852 @rtomayko README
authored
201
f486e77 @richmeyers Added a note and todo entry about file conflicts in packages
richmeyers authored
202 * `rpg` is similarly unable to install more than one package owning the
203 same file under Ruby libdir. (Currently `rpg` will install such packages
204 anyway, with later installed packages overwriting files installed by
205 earlier installed packages.)
206
b24e9eb @rtomayko tidy up the Versus Rubygems README section
authored
207 * `rpg` has no runtime component (e.g., `require 'rubygems'`). Because all
208 library files are placed under a common `lib` directory, and because package
209 versions are sussed at install time, there's no need for a component to
210 select which packages are active at runtime.
44c55cd @rtomayko README formatting tweaks
authored
211
b24e9eb @rtomayko tidy up the Versus Rubygems README section
authored
212 * `rpg` installs packages in two stages: 1.) fetch package files
44c55cd @rtomayko README formatting tweaks
authored
213 and resolve dependencies, and 2.) install package contents. This allows
214 for staged/later installs and conflict detection before install.
215
b24e9eb @rtomayko tidy up the Versus Rubygems README section
authored
216 * `rpg`'s installed package database is filesystem based, (will be) documented,
217 and is built for extension.
a925852 @rtomayko README
authored
218
b24e9eb @rtomayko tidy up the Versus Rubygems README section
authored
219 * `rpg` is written primarily in POSIX shell and requires a unix environment.
a925852 @rtomayko README
authored
220
b24e9eb @rtomayko tidy up the Versus Rubygems README section
authored
221 * `rpg` does not provide commands for building gems or running gem servers.
a925852 @rtomayko README
authored
222
b24e9eb @rtomayko tidy up the Versus Rubygems README section
authored
223 * `rpg` outperforms the gem command in many ways. Most comparable operations
224 complete in at least one order of magnitude less time.
a925852 @rtomayko README
authored
225
44c55cd @rtomayko README formatting tweaks
authored
226 About
37c0dec @rtomayko surgeory on the README/TODO
authored
227 -----
228
b24e9eb @rtomayko tidy up the Versus Rubygems README section
authored
229 rpg's design is inspired by a variety of existing tools. The `gem` command's
230 basic UI, package format, and repository structure are heavily borrowed from
231 or used verbatim.
37c0dec @rtomayko surgeory on the README/TODO
authored
232
44c55cd @rtomayko README formatting tweaks
authored
233 Many of the ideas -- and maybe even some code -- were taken from
234 [Rip](http://defunkt.github.com/rip/). That's understating it, really. rpg
b24e9eb @rtomayko tidy up the Versus Rubygems README section
authored
235 started out just a couple of loose shell scripts to experiment with ideas for
236 integrating gem package and gem dependency support into rip. The plan was to
237 port them over to Ruby and into Rip if they panned out. Within a few days, I had
238 a more or less entire implementation of Rubygems's gem command in POSIX shell
239 staring back at me and it was *fast*. Some of rpg's features may make their way
240 into Rip (the Ruby portions that read release indexes and gemspecs should be
241 useful at least).
37c0dec @rtomayko surgeory on the README/TODO
authored
242
243 Debian's apt and dpkg, FreeBSD's ports system, and Redhat/Fedora's yum all
244 influenced rpg's design in various ways.
245
5bb3741 @rtomayko tone down the README + markdown
authored
246 Git's overall design influenced rpg significantly. Git's internal project
b24e9eb @rtomayko tidy up the Versus Rubygems README section
authored
247 organization is a template for writing moderate sized systems using many small
248 specialized programs. Its granular use of the filesystem as a database (the
249 `.git/refs` and `.git/objects` hierarchies, especially) informed much of rpg's
37c0dec @rtomayko surgeory on the README/TODO
authored
250 package database design.
a925852 @rtomayko README
authored
251
44c55cd @rtomayko README formatting tweaks
authored
252 Copying
37c0dec @rtomayko surgeory on the README/TODO
authored
253 -------
254
451b558 @rtomayko more fucking around in the README. done now. for real this time.
authored
255 Copyright (c) 2010 by [Ryan Tomayko](http://tomayko.com/about)
a925852 @rtomayko README
authored
256
37c0dec @rtomayko surgeory on the README/TODO
authored
257 This is Free Software distributed under the terms of the MIT license.
44c55cd @rtomayko README formatting tweaks
authored
258 See the `COPYING` file for license rights and limitations.
Something went wrong with that request. Please try again.