What is a Rails Engine

There are some special ruby gems that provides a rails engine. Purpose of many of those rails engines are providing ?JavaScript libraries to rails applications. jquery-rails gem is such an example, it provides jquery.js to rails applications through a mechanism called rails assets pipeline.

Identify a rails engine

These gems usually have a app/assets or vendor/assets or lib/assets directory. In all cases the js files are embedded in the gem.

Generate js files from source

If the js files are generated from another source form, then we need to also generate it from their source form. Sometimes it is already done in a separate package which we can use. So we remove the embedded copy and replace it with a symbolic link to the js library.

For example, ruby-uglifier embeds uglify.js file. So when we update, we have to make sure the uglify.js file provided by the libjs-uglify* package is matching with the version of the embedded file.

So uglifier version 2, will need libjs-uglify version 2. And since libjs-uglify version 4 is not available, we cannot update uglifier to version 4. libjs-uglify-js is available as uglify.js version 3. So at this point we can only update uglifier to version 3.

New and Old methods of linking

There are two ways to make package with embedded js files. Old way is how ruby-rails-assets-jquery is doing and new way (dh_ruby --gem-install) is how ruby-rails-assets-autosize is doing

See this commit or this commit to learn the new method of linking. Using /usr/share/dpkg/pkg-info.mk to find upstream version instead of dpkg-parsechangelogs is recommended.


ruby-uglifier, ruby-jquery-rails. Look for a .links file in debian.

Sometimes we may not create a separate package to generate the libjs- package, when it is required only for a single package, like ruby-rails-assets-perfect-scrollbar.

In that case, we just create the libjs-perfect-scrollbar binary package from embedded copy. Ideally it should be packaged separately. That is an exception

For ruby-rails-assets-autosize, app/assets/javascripts/autosize/autosize.js should be removed (not the .js in its parent directory)

That just includes the actual file

//= require autosize/autosize.js

This is special syntax used by sprockets, which is used with rails to manage the .js files

Only autosize/autosize.js is the actual file, other file is instruction for sprockets to find the actual file

Smoke test

Add a smoke test like ruby-rails-assets-perfect-scrollbar (this commit in ruby-backbone-on-rails is an example). To make sure rails/sprockets can still find the file after our intervention, ie, we have correctly linked.

bundle install --local command verifies the gem requirements mentioned in Gemfile is satisfied by the locally installed gems.

Note: rubygems-integration package expose the apt installed packages to gem command.

rake assets:precompile runs sprockets to find the js file specified in application.js