Quite a few Drupal modules rely on outside libraries to work. Some are JavaScript based requiring outside plugins and others are based on outside libraries. When users install these modules they, also, have to download and install the outside library. This is a pain that drush make and the Libraries API in modules can help with.
A typical setup will have a drush make file with a project and associated libraries defined within in them. The author who puts together the profile or top level make file will need to know the library and where it needs to go.
A little known feature about drush make files is that all projects can have make files and drush recursively builds each one out. So, if a module has a make file and the module is included in another make file the modules make file will be executed as well.
A simple use could be a module that uses an outside JavaScript library. That module could define a ModuleName.make file telling drush to download the library. A good solution would be to tell the script to go to the libraries directory alongside the modules and themes directories. Then, the module could use the Libraries API to grab the libraries location.
An Example
In this example we have the Super Awesome module using the awesome JavaScript file. So, in superawesome.make, which sits alongside superawesome.module, we have something like:core = 6.x
; Libraries
libraries[awesome][download][type] = "get"
libraries[awesome][download][url] = "http://example.com/awesome.js.zip"
libraries[awesome][directory_name] = "awesome"
libraries[awesome][destination] = "libraries"
This will tell drush to download the awesome library and stick it in a directory called awesome within the libraries folder. The libraries folder could be in profiles/profileName, sites/all, or sites/someSiteName.com. Since the file has the zip extension drush will know how to unzip it as well.
Since the files could be placed in one of several places we can use the Libraries API. To get the path in our module we can use the following:
$path = libraries_get_path('awesome');
Some Things You Should Know
There are two issues to be aware of with this approach.- If a project (modules or theme) is included in a make file but already exists elsewhere (like a profile or site make file) you'll get an error. Drush make doesn't, currently, handle a project being defined more than once.
- If there are only libraries and no projects defined in a make file a warning will be thrown. Everything works as expected. There is just a one line warning for each make file without a project.