@@ -116,11 +116,16 @@ To get the source, these commands will get you started:
116116
117117### Bring your own V8
118118
119- Because libv8 is the interface for the V8 engine used by
120- [ therubyracer] ( http://github.com/cowboyd/therubyracer ) , you may need
121- to use libv8, even if you have V8 installed already. If you wish to
122- use your own V8 installation, rather than have it built for you, use
123- the ` --with-system-v8 ` option.
119+ * This is a great way to ensure that the builds of all gems that depend on libv8
120+ fail. Please see the Gotchas section below and use the follwing instructions
121+ only if you know what you're doing. If you're resorting to this because the
122+ build of the gem is failing on your system or because there's no
123+ platform-specific gem for your platform, please open up an issue.*
124+
125+ Because libv8 is the interface for the V8 engine used by several gems, you may
126+ need to use libv8, even if you have V8 installed already. If you wish to use
127+ your own V8 installation, rather than have it built for you, use the
128+ ` --with-system-v8 ` option.
124129
125130Using RubyGems:
126131
@@ -133,12 +138,14 @@ Using Bundler (in your Gemfile):
133138#### Gotchas
134139
135140Please note that if you intend to run your own V8, you must install
136- both V8 * and its headers* (found in libv8-dev for Debian distros).
137-
138- Also keep in mind that v8's API does not tend to be stable and you
139- need to make sure that the version of therubyracer you intend to use
140- is compatible with the version of v8 present on your system. Otherwise
141- therubyracer's build will fail.
141+ both V8 * and its headers* (found in libv8-dev for Debian-based distros).
142+
143+ Also, keep in mind that v8's API does not tend to be stable and in case you're
144+ using your local version of V8 you * need* to ** make sure that the the gems that
145+ depend on libv8 are compatible with the API of the version of v8 present on your
146+ system** . Otherwise those gems' builds * will* fail. Ideally you want the same
147+ version of V8 as the one packaged in the installed version of the gem. See the
148+ Versioning section for more information.
142149
143150### Bring your own compiler
144151
0 commit comments