

Aims
----

The aim of the libraries module is to allow multiple Drupal
modules to share common third-party code, such as JavaScript libraries.

The aim of this Debian package is to make this paradigm convenient
within a Debian environment, in particular, where third-party JavaScript code
is available under /usr/share/javascript

Observations
------------

It isn't enough to just symlink JavaScript code from
/usr/share/javascript to /usr/share/drupal7/libraries

Each third party module needs a Drupal wrapper module to declare
what it does.

Here is an example of actual packages for DruCall, using the shared
SIPml5 javascript:

drupal7                - Drupal
drupal7-mod-libraries  - the libraries API
libjs-sipml5           - the JavaScript code under /usr/share/javascript
drupal7-mod-sipml5     - a wrapper that declares the SIPml5 JavaScript,
                         and satisfies the Debian and Drupal package
                         dependencies for sipml5
drupal7-mod-drucall    - the module using the third party library

A wrapper module like drupal7-mod-sipml5 is needed for each version
of Drupal.  However, only a single copy of the JavaScript itself,
(e.g. libjs-sipml5) is shared between all Drupal installations
(e.g. Drupal6, Drupal7) on the same system.

One oddity of the libraries module: it expects to be able to
determine the version of a JavaScript library by scanning the content
of the file or directory where it is installed.  If this can't be
easily done (e.g. because a version string is not embedded in a
particular .js file), then a quick hack is to create a file
called VERSION that contains the version.  See the package
drupal7-mod-sipml5 for an example of how this is done.

Drupal local directory issues (and solutions) on Debian
-------------------------------------------------------

On a Debian system, using the drupal7 package, the `official'
installation directory is /usr/share/drupal7

Many public documents refer to subdirectories of the main
installation directory, for example, sites/all/modules is
considered to be relative to the installation directory.

Many internal Drupal functions (such as drupal_add_js()) expect
their arguments to be relative to the Drupal installation directory.
The Drupal function base_path() returns /usr/share/drupal7 on Debian
and this value is prepended to the relative paths to construct absolute
paths.

The basic Drupal package (e.g. drupal7) relies on symlinks to locations
outside of /usr/share so that users can modify files related to Drupal
(modifying files under /usr/share is bad practice, these files are
maintained by the package management system):

/usr/share/drupal7/sites -> /etc/drupal/7/sites
  - this symlink is created automatically by the package
  - this allows per-site or server-wide config settings to be modified,
    by keeping them in the /etc tree

/usr/share/drupal7/modules/local -> /usr/local/share/drupal/7/modules
  - this link can be created manually (recommended by drupal7/README.Debian)
    to allow local installation of non-packaged modules under the
    /usr/local tree
  - the name `local' doesn't have any special meaning to Drupal.  Drupal
    simply scans /usr/share/drupal7/modules recursively looking for
    modules and descends into local as part of the sub-tree scan.
  - this same concept applies for /usr/share/drupal7/themes

/usr/share/drupal7/libraries is scanned by the libraries module.
Unlike the modules and themes directories, it is NOT scanned recursively
and amonst other things, this means a symlink such as
/usr/share/drupal7/libraries/local -> /usr/share/local/drupal/7/libraries
can not be created and would not work.

While it may appear trivial to patch the libraries module to do a recursive
sub-tree scan, it is not so easy: the contents of the libraries tree are
the third party JavaScript packages (or symlinks to their real locations
under /usr/share/javascript) and each of these packages has it's own ad-hoc
directory layout.  A recursive scan would not know which of these
directories are really top-level package directories.

Nonetheless, site managers should not be putting local JavaScript
(or wrappers, see below) directly into /usr/share/drupal7/libraries,
so the following convention can be used:

  mkdir -p /usr/share/local/drupal/7/libraries
  mkdir /etc/drupal/7/sites/all
  ln -s /usr/share/local/drupal/7/libraries /etc/drupal/7/sites/all

Drupal's libraries module will find that location when it searches the
relative path `sites/all/libraries'

Now, any locally managed JavaScript packages can be unpacked in
(or symlinked to) /usr/share/local/drupal/7/libraries

Non-packaged JavaScript and/or wrapper modules
----------------------------------------------

If JavaScript or other third party code is downloaded manually, it
can be placed under /usr/local/share/drupal/7/libraries/SOMETHING

Alternatively, JavaScript code can be downloaded to
/usr/local/share/javascript/SOMETHING and then
symlinked to /usr/local/share/drupal/7/libraries/SOMETHING

The corresponding third-party wrapper module for Drupal then
needs to be downloaded and installed to
/usr/local/share/drupal/7/modules just like any other manually
installed module.

Consider using dh-make-drupal to package Drupal modules that you
require
  http://gwolf.org/dh-make-drupal


