Resolver bundles creation + bundles for a bunch of resolvers

4shared/4shared-resolver.js → 4shared/content/contents/code/4shared-resolver.js

@@ -1,6 +1,21 @@
-/*
- * (c) 2011 lasconic <[email protected]>
+/* === This file is part of Tomahawk Player - <http://tomahawk-player.org> ===
+ *
+ *   Copyright 2011, lasconic <[email protected]>
+ *
+ *   Tomahawk is free software: you can redistribute it and/or modify
+ *   it under the terms of the GNU General Public License as published by
+ *   the Free Software Foundation, either version 3 of the License, or
+ *   (at your option) any later version.
+ *
+ *   Tomahawk is distributed in the hope that it will be useful,
+ *   but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ *   GNU General Public License for more details.
+ *
+ *   You should have received a copy of the GNU General Public License
+ *   along with Tomahawk. If not, see <http://www.gnu.org/licenses/>.
  */
+
 var FSharedResolver = Tomahawk.extend(TomahawkResolver, {
     settings: {
         name: '4shared',

4shared/content/metadata.json

@@ -0,0 +1,18 @@
+{
+    "name": "4Shared",
+    "pluginName": "4shared",
+    "author": "lasconic",
+    "email": "[email protected]",
+    "version": "0.1.5",
+    "website": "http://gettomahawk.com",
+    "description": "Looks for tracks to play from www.4shared.com",
+    "type": "resolver/javascript",
+    "manifest": {
+        "main": "contents/code/4shared-resolver.js",
+        "scripts": [],
+        "icon": "contents/images/icon.png",
+        "resources": [
+            "contents/code/4shared-icon.png"
+        ]
+    }
+}

8tracks/8tracks.js → 8tracks/content/contents/code/8tracks.js

@@ -1,7 +1,22 @@
-/*
- * (c) 2011 Janez Troha (https://github.com/dz0ny)
- * (c) 2011 Leo Franchi <[email protected])
+/* === This file is part of Tomahawk Player - <http://tomahawk-player.org> ===
+ *
+ *   Copyright 2011, Janez Troha (https://github.com/dz0ny)
+ *   Copyright 2011, Leo Franchi <[email protected]>
+ *
+ *   Tomahawk is free software: you can redistribute it and/or modify
+ *   it under the terms of the GNU General Public License as published by
+ *   the Free Software Foundation, either version 3 of the License, or
+ *   (at your option) any later version.
+ *
+ *   Tomahawk is distributed in the hope that it will be useful,
+ *   but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ *   GNU General Public License for more details.
+ *
+ *   You should have received a copy of the GNU General Public License
+ *   along with Tomahawk. If not, see <http://www.gnu.org/licenses/>.
  */
+
 var EightTracksResolver = Tomahawk.extend(TomahawkResolver, {
     settings: {
         name: '8tracks Resolver',

8tracks/content/metadata.json

@@ -0,0 +1,16 @@
+{
+    "name": "8tracks",
+    "pluginName": "8tracks",
+    "author": "Janez and Leo",
+    "email": "[email protected]",
+    "version": "0.1",
+    "website": "http://gettomahawk.com",
+    "description": "Looks for tracks to play from 8tracks.com",
+    "type": "resolver/javascript",
+    "manifest": {
+        "main": "contents/code/8tracks.js",
+        "scripts": [],
+        "icon": "contents/images/icon.png",
+        "resources": []
+    }
+}

HACKING.md

@@ -0,0 +1,114 @@
+# Tomahawk Resolvers Developer Documentation
+
+## Developing resolvers
+
+The Tomahawk resolver API is currently still in flux. It is probably a good idea to use the existing resolvers as example.
+
+The API you should develop against is defined in [`tomahawk.js`](https://github.com/tomahawk-player/tomahawk/blob/master/data/js/tomahawk.js) and [`QtScriptResolverHelper`](https://github.com/tomahawk-player/tomahawk/blob/master/src/libtomahawk/resolvers/QtScriptResolver.h) in the Tomahawk main repo.
+
+If you have questions, look for us in #tomahawk on irc.freenode.net.
+
+### Licensing
+
+Tomahawk resolvers are considered derivative works of Tomahawk, specifically through the previously mentioned `tomahawk.js` and `QtScriptResolver.h` files. These files are released under a GNU General Public License, version 3 or later.
+
+Thus, developers who release a resolver are expected to
+* release the resolver code they produce under a license compatible with Tomahawk, and specifically with Tomahawk's resolver interface, and
+* add a copyright and licensing statement at the beginning of those resolver file(s) that interface with Tomahawk, with a wording that makes their licensing (and compatibility) clear.
+
+Exceptions to this requirement can be evaluated upon request by the Tomahawk team.
+
+## Packaging resolvers
+
+### Structure overview
+
+Starting with Tomahawk 0.7, all resolver directories must be structured as follows.
+
+Mandatory:
+```
+content/
+  + metadata.json
+```
+Suggested:
+```
+content/
+  + metadata.json
+  + contents/
+    + code/
+      + <resolver script>.js
+      + config.ui
+      + <everything else>
+    + images/
+      + icon.png
+```
+
+This structure is commonly referred to as a resolver bundle, i.e. a resolver script with all related files and metadata.
+
+A bundle can be packaged or unpackaged (i.e. as it is in this repo), thus resolvers can be installed manually in two ways:
+* from an unpackaged bundle,
+* from a package (or axe).
+
+### Installing a resolver bundle
+
+To install a resolver from an unpackaged bundle (the preferred way for testing and development), in Tomahawk's Settings dialog click on "Install from file" and select the resolver's main .js file.
+
+Keep in mind that with such a path, Tomahawk expects to find the file `metadata.json` in `../..` from the main script's path. If `metadata.json` is not found, it is likely that your resolver directory is not structured properly. The resolver's main script will still be loaded, but any additional scripts will not and the accounts list in the Settings dialog will not show any metadata for the resolver (e.g. author, version, etc.). This is a **bad thing**. The only reason why a resolver without `metadata.json` is still loaded is backward compatibility. Plain unbundled .js files as resolvers are deprecated. You should update your resolver to a proper bundle structure as soon as possible.
+
+A packaged resolver bundle is a file with file extension `axe`. It is a compressed archive with all the contents of a resolver directory. To install such a bundle (the preferred way for end users who wish to install a resolver manually), in Tomahawk's Settings dialog click on "Install from file" and select the package file (`<something>.axe`).
+
+**WARNING** for developers and testers: the installation process for an *unpackaged* bundle loads the resolver in-place. This means that any changed to the resolver script are applied immediately, simply by disabling and re-enabling the "installed" resolver with the account's checkbox in the accounts list. There is usually no need to remove and re-install the resolver. This also means that changes to the directory structure may make the resolver stop functioning. On the other hand, packaged bundles (axes) are decompressed and copied to a Tomahawk-managed directory (`<local user data dir>/manualresolvers`) during the installation process, so any change to the axe can only be applied by re-installing.
+
+### Packaging
+
+#### metadata.json
+
+Every resolver bundle directory must contain a metadata file. This file must be named `metadata.json`, and it must be located in the directory `content` relative to the top-level resolver bundle directory.
+
+For example, this is a `metadata.json` file for Subsonic:
+```
+{
+    "name": "Subsonic",
+    "pluginName": "subsonic",
+    "author": "mack_t and Teo",
+    "email": "[email protected]",
+    "version": "0.5",
+    "website": "http://gettomahawk.com",
+    "description": "Searches your Subsonic server for music to play",
+    "type": "resolver/javascript",
+    "manifest": {
+        "main": "contents/code/subsonic.js",
+        "scripts": [],
+        "icon": "contents/images/icon.png",
+        "resources": [
+            "contents/code/config.ui",
+            "contents/code/runnersid-icon.png",
+            "contents/code/subsonic-icon.png",
+            "contents/code/subsonic.png"
+        ]
+    }
+}
+```
+
+For most purposes all the fields are mandatory.
+
+**WARNING**: the manifest object **must** list all the files required by the resolver. Unlisted scripts will not be loaded, and any unlisted files will not be packaged.
+
+#### makeaxe.rb
+
+If your resolver directory conforms to the previously described structure and your `metadata.json` is complete, the harder part is done. The Tomahawk team provides you with a script to automate the packaging process: [`makeaxe.rb`](admin/makeaxe.rb). You will need [ruby](http://www.ruby-lang.org/en/) 1.9.2 or later and the [zip](https://rubygems.org/gems/zip) gem.
+
+To create a package from a resolver directory, simply run `makeaxe.rb` with the directory path passed as parameter.
+
+E.g. on Linux and Mac OS X, for Subsonic and from the repository root, you would do the following:
+```
+% ruby admin/makeaxe.rb subsonic
+% ls subsonic
+content/  subsonic-0.5.axe  subsonic-0.5.md5
+```
+In this case, `subsonic-0.5.axe` is the compressed bundle and `subsonic-0.5.md5` is the MD5 checksum file.
+
+Please note that `makeaxe.rb` does not simply compress the contents of the directory, it also checks the metadata file and adds additional data, including a packaging timestamp and the revision hash, if any.
+
+Optionally, if you pass the `--release` parameter to `makeaxe.rb` it will not include the commit hash in the axe, as would be expected in a release-worthy package.
+
+Happy packaging!

README.md

@@ -0,0 +1,13 @@
+# Tomahawk Resolvers
+
+Supported resolvers are distributed and updated automatically through Tomahawk's Settings dialog.
+To manually intstall a resolver: either 
+* clone this repo,
+* download the .zip, or 
+* download all the files within the individual resolver folder you are installing.
+
+After you have the files locally, open Tomahawk's preferences and from the "Services" tab click "Install from File" and select the .axe or .js file for the resolver you are installing.
+
+Since March 2013 Tomahawk resolvers have switched to a new directory structure for easy packaging. Ideally, you should download nightly .axe files, if available.
+
+For developer documentation, see [HACKING.md](HACKING.md).

admin/json2desktop.rb

@@ -0,0 +1,105 @@
+#!/usr/bin/env ruby
+# === This file is part of Tomahawk Player - <http://tomahawk-player.org> ===
+#
+#   Copyright 2013, Teo Mrnjavac <[email protected]>
+#
+#   Tomahawk is free software: you can redistribute it and/or modify
+#   it under the terms of the GNU General Public License as published by
+#   the Free Software Foundation, either version 3 of the License, or
+#   (at your option) any later version.
+#
+#   Tomahawk is distributed in the hope that it will be useful,
+#   but WITHOUT ANY WARRANTY; without even the implied warranty of
+#   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+#   GNU General Public License for more details.
+#
+#   You should have received a copy of the GNU General Public License
+#   along with Tomahawk. If not, see <http://www.gnu.org/licenses/>.
+
+
+#
+# This script converts a json metadata/manifest file into a desktop file for Synchrotron.
+#
+
+require 'json'
+
+if ARGV.length < 1
+    puts "This script converts a Tomahawk resolver's metadata/manifest JSON file"
+    puts "into a desktop file for Synchrotron."
+    puts "Usage: ruby json2desktop.rb path_to_metadata_file.json"
+    exit
+end
+
+inputPath = File.absolute_path( ARGV[0] )
+outputPath = File.join( File.dirname( inputPath ), "metadata.desktop" )
+
+if not File.exists?( inputPath ) or not File.readable?( inputPath )
+    puts "Cannot read input file."
+    exit
+end
+
+if File.exists?( outputPath ) and not File.writable?( outputPath )
+    puts "Cannot write to output file."
+    exit
+end
+
+inputFile = File.open( inputPath, 'r' )
+inputString = inputFile.read
+input = JSON.parse( inputString )
+inputFile.close unless inputFile == nil
+
+# check if outputPath exists, maybe save stuff and/or overwrite, yes?
+File.open( outputPath, 'w' ) do |f|
+    f.write "\
+############################################################################
+## Desktop file generated from JSON file '#{File.basename( inputPath )}' 
+##
+## Created: #{Time.now.utc.to_s}
+##      by: json2desktop.rb, https://github.com/tomahawk-player
+##
+##                         #### WARNING! ####
+##              All changes made to this file will be lost!
+############################################################################
+
+[Desktop Entry]\n"
+
+    unless input["name"].nil? || input["name"].empty?
+        f.write "Name=#{input["name"]}\n"
+    end
+
+    unless input["description"].nil? || input["description"].empty?
+        f.write "Comment=#{input["description"]}\n"
+    end
+
+    f.write "\nType=Service\nX-KDE-ServiceTypes=Tomahawk/Resolver\n"
+
+    unless input["manifest"].nil?
+        unless input["manifest"]["main"].nil? || input["manifest"]["main"].empty?
+            f.write "X-Synchrotron-MainScript=#{input["manifest"]["main"]}\n"
+        end
+    end
+
+    f.write "\n"
+
+    unless input["pluginName"].nil? || input["pluginName"].empty?
+        f.write "X-KDE-PluginInfo-Name=#{input["pluginName"]}\n"
+    end
+
+    f.write "X-KDE-PluginInfo-Category=Resolver\n"
+
+    unless input["author"].nil? || input["author"].empty?
+        f.write "X-KDE-PluginInfo-Author=#{input["author"]}\n"
+    end
+
+    unless input["email"].nil? || input["email"].empty?
+        f.write "X-KDE-PluginInfo-Email=#{input["email"]}\n"
+    end
+
+    unless input["version"].nil? || input["version"].empty?
+        f.write "X-KDE-PluginInfo-Version=#{input["version"]}\n"
+    end
+
+    unless input["website"].nil? || input["website"].empty?
+        f.write "X-KDE-PluginInfo-Website=#{input["website"]}\n"
+    end
+end