motion-sparkle 0.0.1

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    NmE2ODFmNmQxYjdmMTgwZjQ5M2JhNzI5NTFlNTE5MGU0MGRkNDI2Yw==
+  data.tar.gz: !binary |-
+    NDNiMzA3MWVlNTEzMDJlMTA3NTg1MWIwZjNmYjcxMjYwNTAxNWFlZg==
+SHA512:
+  metadata.gz: !binary |-
+    OGQ5YjMyZDBhMDUwN2I3NjIxZjZmNGI3NzVhZTllNGIzZmIyMGZlMjgxNGYx
+    NDE2ZmFjYTA3OGQxMTI0NmU4YzRhOTVhM2FlYzJkMzgxNmIxZWZkNTIzMTlm
+    NjA3NGZlMDlhOGRjOTgxMGIxMjRhOTY4OGZjNGZlYWUyYjdhODY=
+  data.tar.gz: !binary |-
+    YTgxZWI5MjQ5NGQzOWM0YjEyZDg5ZTQyNTQzYmY4MTQxMTdmNGVlODk0ZGUz
+    MzEyNTZmZWE3MjdjNmZhYzhlYzJiMzI1NTE4N2UzZGE1YTkyZjYyNTE4YzYw
+    OGQ4ZmVlMjNjNWJmMjhiNzA1NDkwYTdjYmQ1ZmM2ZTM3ODk4ZGU=

data/.gitignore

@@ -0,0 +1,19 @@
+*.gem
+*.rbc
+.bundle
+.config
+coverage
+InstalledFiles
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+Gemfile.lock
+
+# YARD artifacts
+.yardoc
+_yardoc
+doc/

data/Gemfile

@@ -0,0 +1,6 @@
+source 'https://rubygems.org'
+
+gemspec
+
+gem 'bacon'
+gem 'rake'

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2013 Alexandre L. Solleiro <alex@webcracy.org>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,206 @@
+# Using motion-sparkle to add Sparkle to your Rubymotion project
+
+*NB: Sparkle only works for OS X projects*
+
+## Overview
+
+[Sparkle](http://sparkle.andymatuschak.org/) is a free auto-updater library for Cocoa apps. It powers countless Mac application's "Check for updates" feature, as it takes care of all the process automatically, is very easy to integrate and is secure.
+
+In a nutshell, when users click "Check for updates..." in an app, Sparkle checks for updates against an XML file that you post somewhere on the web. That XML file contains information about your new release, such as the version number, the URL of the package and its digital signature. If there's a newer version available than the one that is currently running, it'll ask for permission to retrieve the package and replace the current app with the new release.
+
+While it's easy to use Sparkle with RubyMotion without motion-sparkle, using it makes it even easier. The gem takes care of the Sparkle framework integration, simplifies its configuration and then automates the preparation of a release, creating the ZIP file, XML and release notes for you.
+
+After building your app for release and running `rake sparkle:package`, all you need to do is upload 3 files to an URL you specified in the Rakefile and your users will be able to get the new release.
+
+## Installation
+
+In your project's Gemfile, add:
+
+`gem motion-sparkle`
+
+and then run `$ bundle install`
+
+## Settings configuration
+
+Configure Sparkle in your `Rakefile` using motion-sparkle's DSL:
+
+    # Rakefile
+  
+    app.sparkle do
+      # Required setting
+      release :base_url, 'http://example.com/releases/current' # `current` is a folder, don't use a trailing slash
+
+      # Recommended setting
+      # This will set both your `app.version` and `app.short_version` to the same value
+      # It's fine not to use it, just remember to set both as Sparkle needs them
+      release :version, '1.0'
+      
+      # Optional settings and their default values
+      release :feed_filename, 'releases.xml'
+      release :notes_filename, 'release_notes.html'
+      release :package_filename, "#{app.name}.zip"
+      release :public_key, 'dsa_pub.pem'
+    
+    end
+
+To complete the configuration, run
+
+    $ rake sparkle:setup
+
+
+If everything is OK, you should be informed that it's time to generate or configure your certificates.
+
+## Certificate configuration
+
+For security, Sparkle allows you to sign your releases with a private certificate before distribution. In a few words: when the user tries to install an update, Sparkle will check the package using the signature provided in the XML file and the public certificate contained in the running application.
+
+motion-sparkle makes it very easy to handle this. In fact, after the first setup, it becomes completely transparent to you and is all handled when you run `rake sparkle:package`.
+
+You have two options: have Sparkle generate the certificates for you, or follow the instructions.
+
+### Generate new certificates
+
+    $ rake sparkle:setup_certificates
+
+
+### Use your existing certificates
+
+By default, your certificates need to be placed in the following directories:
+
+
+    ./resources/dsa_pub.pem         # public certificate
+    ./sparkle/config/dsa_priv.pem   # private certificate
+
+
+### Notes about the public certificate 
+
+The public certificate is placed at the root of the default `resources/` folder by default, as it needs to bundled with your app. If you chose to rename it, remember to set its correct value in the `Rakefile`, using `release :public_key, 'new_name.pem'`.
+
+### Notes about the private certificate 
+
+The private certificate cannot be renamed nor placed elsewhere. If you have an existing certificate, please name it `dsa_priv.pem` and place inside the `sparkle/config/` folder
+
+### Warning regarding your private certificate
+
+Be careful when handling the private certificate: you should never lose it nor share it. If you do, you'd lose the ability to sign your packages and users wouldn't be able to update your app. If someone takes it, they could sign the packages in your name and have your users install who knows what.
+
+Tips: 
+* add it go your .gitignore or equivalent 
+* make a backup of it
+
+### Run `rake:setup` at any moment to make sure your config is OK
+
+When all is good, move forward. If you need help, you can always open an issue on Github.
+
+## Adding "Check for updates..." to the menu
+
+Sparkle makes it incredibly easy to add a "Check for updates" feature to your app. 
+
+The `SUUpdater` class has a shared updater instance that you can use as a `target` for the different actions Sparkle provides. To launch the typical Sparkle flow, you need only to call the `checkForUpdates:` action. 
+
+So, running `SUUpdater.new.checkForUpdates` will launch the "Check for updates" flow.
+
+Here's an example based on the Rubymotion default OS X app example, "Hello". 
+
+This will add the classic "Check for updates..." entry on the menu; when the user clicks it, the nice default of experience of Sparkle will begin.
+
+In `menu.rb`, right below the line that adds the "Preferences" item:
+
+    sparkle = addItemWithTitle("Check for updates...", action: nil, keyEquivalent: '')
+    sparkle.setTarget SUUpdater.new
+    sparkle.setAction 'checkForUpdates:'
+
+Once you build your application, you should be able to see a "Check for updates..." item in the Application menu. It should work but would still produce an error at this point. Keep going to make it all work.
+
+Check out Sparkle's documentation for more details and further ways to customize the experience.
+
+## First publication
+
+Before you build, make sure you've set your `:base_url` to a destination where you can upload/download your files. Note that packaging with motion-sparkle only works with the `:release` target at the moment, so make sure your build with be compatible with `rake build:release`.
+
+Run the setup command
+
+    $ rake sparkle:setup
+
+If you're ready to go, you should probably add 
+
+    $ rake sparkle:package
+
+This should create 3 files inside the `sparkle/release/` folder: a ZIP file of your app, an XML file and an HTML file with the release notes.
+
+If you've set your `:base_url` correctly, go ahead and upload thoses files to the location you've specified. Run your app and click "Check for updates..." in the menu -- this time, it should say that it's running the latest version available.
+
+## Releasing updates
+
+Once users are running a Sparkle-powered version, all you have to do is put updated versions of those files at the same location.
+
+To do so, follow the same steps every time:
+
+### 1. Bump the version
+
+    # In your Rakefile
+  
+    sparkle.app do
+      release :version, '1.1' # bump the versions
+    end
+
+### 2. Build your app for release
+
+`$ rake build:release`
+
+### 3. Update your Release Notes
+
+Release notes are generated using an HTML file for content and an ERB file for layout. Sparkle uses Webkit to show them to your users at the time of update.
+
+You can either change these files inside the `sparkle/config/` folder, or simply edit the resulting html file in `sparkle/release/` after you've packaged the release.
+
+### 4. Package the release
+
+Run the `sparkle:package` task and you'll be one step away from distribution.
+
+    $ rake sparkle:package
+
+### 5. Upload
+
+Upload the 3 files and your new version is up. When users click "Check for updates...", the app should now display your release notes and ask the user to update. And when they do, the app will update and relaunch itself cleanly. 
+
+Sparkle for the win.
+
+## Help, Limitations, Troubleshooting and Testing
+
+If you need further help, please open an Issue on Github.
+
+Limitations:
+
+  *   Only tested with Ruby 1.9.3-p448
+  *   Only works with ZIP files
+  *   Only works with :release build target
+  *   The Sparkle framework is horrendously copied multiple times
+
+To further troubleshoot your case, you clone/fork the repo and go through the tests and the code.
+
+To test, you can just run `$ bundle install` at the source of the repo to install the development dependencies and the run `$ rake` to execute the tests.
+
+Test coverage currently only extends to configuration and certificate generation checking.
+
+## Contributing
+
+Wanted features:
+
+  - [ ]  Copy the Sparkle.framework in a more sensible way, ideally through Cocoapods (it's currently copied multiple times because rubygems won't handle symlinks)
+  - [ ]  Configurable build targets (only :release supported currently)
+  - [ ]  Have more than ZIP as a packaging option, with DMG a priority (see choctop gem)
+  - [ ]  Automatic upload to S3 and via rsync/scp/sftp/ftp (see choctop gem)
+  - [ ]  Textile / Markdown for release note templates
+  - [ ]  Ruby 1.8.7, Ruby 1.9.2, Ruby 2.0 compatibility
+  - [ ]  Better test coverage
+
+## Credits
+
+Author: Alexandre L. Solleiro
+
+* Follow me on Twitter - http://twitter.com/als, 
+* Fork my code on Github - http://github.com/webcracy, 
+* More info on my website - http://webcracy.org
+
+Thanks: Authors and contributors of HipByte/motion-cocoapods, drnic/choctop gems and of course andymatuschak/Sparkle. Their code has made this easier.

data/Rakefile

@@ -0,0 +1,20 @@
+desc "Build the gem"
+task :gem do
+  sh "bundle exec gem build motion-sparkle.gemspec"
+  sh "mkdir -p pkg"
+  sh "mv *.gem pkg/"
+end
+task :build => :gem
+
+desc "Clear gem builds"
+task :clean do
+  FileUtils.rm_rf 'pkg'
+  FileUtils.rm_rf 'tmp'
+end
+task :clear => :clean
+
+desc "Run all the specs"
+task :spec do
+  sh "bundle exec bacon -q #{FileList['spec/*_spec.rb'].join(' ')}"
+end
+task :default => :spec

data/lib/motion-sparkle.rb

@@ -0,0 +1,11 @@
+unless defined?(Motion::Project::Config)
+  raise "This file must be required within a RubyMotion project Rakefile."
+end
+require 'motion/project/sparkle'
+require 'motion/project/setup'
+require 'motion/project/package'
+require 'motion/project/templates'
+require 'motion/project/appcast'
+require 'motion/project/project'
+require 'motion/project/rake_tasks'
+require 'motion/project/version'

data/lib/motion/project/appcast.rb

@@ -0,0 +1,106 @@
+module Motion::Project
+  class Sparkle
+
+    def create_release_notes
+      if File.exist?(release_notes_template_path)
+        File.open("#{release_notes_path}", "w") do |f|
+          template = File.read(release_notes_template_path)
+          f << ERB.new(template).result(binding)
+        end
+        App.info 'Create', "./#{release_notes_path}"
+      else
+        App.fail "Release notes template not found as expected at ./#{release_notes_template_path}"
+      end
+    end
+
+    def create_appcast
+      appcast_file = File.open("#{sparkle_release_path}/#{appcast.feed_filename}", 'w') do |f|
+        xml_string = ''
+        doc = REXML::Formatters::Pretty.new
+        doc.write(appcast_xml, xml_string)
+        f << "<?xml version=\"1.0\" encoding=\"utf-8\"?>\n"
+        f << xml_string 
+        f << "\n"
+      end
+      if appcast_file
+        App.info "Create", "./#{sparkle_release_path}/#{appcast.feed_filename}"
+      else
+        App.info "Fail", "./#{sparkle_release_path}/#{appcast.feed_filename} not created"
+      end
+    end
+
+    def appcast_xml
+      base_url = appcast.base_url
+      rss = REXML::Element.new 'rss'
+      rss.attributes['xmlns:atom'] = "http://www.w3.org/2005/Atom"
+      rss.attributes['xmlns:sparkle'] = "http://www.andymatuschak.org/xml-namespaces/sparkle"
+      rss.attributes['xmlns:version'] = "2.0"
+      rss.attributes['xmlns:dc'] = "http://purl.org/dc/elements/1.1/"
+      channel = rss.add_element 'channel'
+      channel.add_element('title').text = @config.name
+      channel.add_element('description').text = "#{@config.name} updates"
+      channel.add_element('link').text = @config.info_plist["SUFeedURL"]
+      channel.add_element('language').text = 'en'
+      channel.add_element('pubDate').text = Time.now.strftime("%a, %d %b %Y %H:%M:%S %z")
+      atom_link = channel.add_element('atom:link')
+      atom_link.attributes['href'] = @config.info_plist["SUFeedURL"]
+      atom_link.attributes['rel'] = 'self'
+      atom_link.attributes['type'] = "application/rss+xml"
+      item = channel.add_element 'item'
+      item.add_element('title').text = "#{@config.name} #{@config.version}"
+      item.add_element('pubDate').text = Time.now.strftime("%a, %d %b %Y %H:%M:%S %z")
+      guid = item.add_element('guid')
+      guid.text = "#{@config.name}-#{@config.version}"
+      guid.attributes['isPermaLink'] = false
+      item.add_element('sparkle:releaseNotesLink').text = "#{base_url}/#{appcast.notes_filename}"
+      enclosure = item.add_element('enclosure')
+      enclosure.attributes['url'] = "#{base_url}/#{@package_file}"
+      enclosure.attributes['length'] = "#{@package_size}"
+      enclosure.attributes['type'] = "application/octet-stream"
+      enclosure.attributes['sparkle:version'] = @config.version
+      enclosure.attributes['sparkle:dsaSignature'] = @package_signature
+      rss
+    end
+
+    def release_notes_template_path
+      sparkle_config_path + "release_notes.template.erb"
+    end
+
+    def release_notes_content_path
+      sparkle_config_path + "release_notes.content.html"
+    end
+
+    def release_notes_path
+      sparkle_release_path + appcast.notes_filename.to_s
+    end
+
+    def release_notes_content
+      if File.exist?(release_notes_content_path)
+        File.read(release_notes_content_path)
+      else
+        App.fail "Missing #{release_notes_content_path}"
+      end
+    end
+
+    def release_notes_html
+      release_notes_content
+    end
+
+
+    class Appcast
+      attr_accessor :base_url, :feed_filename, :notes_filename, :package_filename
+
+      def initialize
+        @feed_filename = 'releases.xml'
+        @notes_filename = 'release_notes.html'
+        @package_filename = nil
+        @base_url = nil
+      end
+
+      def full_feed_url
+        "#{base_url}/#{feed_filename}"
+      end
+    end
+
+  end
+end

data/lib/motion/project/appcast/release_notes.content.html

@@ -0,0 +1,22 @@
+<h1>Your app - version x.yz</h1>
+
+<h2>The greatest update ever</h2>
+
+<dl>
+  <dt>An interface to drool for</dt>
+  <dd>I won't say too much (wouldn't want to spoil the surprise)</dd>
+  <dt>Record-breaking performance</dt>
+  <dd>
+    <p>
+      We keep doing it every time and you start to be less impressed, but we're still very proud of ourselves! We could write about our performance for hours, and make you read it for days!
+    </p>
+    <p>
+      <strong>What for?</strong>
+      <br>
+      This does serve a purpose, however, and it is to show you how a longer text would look like. It'll help you figure out your style.
+    </p>
+    <p>
+      Just do the same for your app now :)
+    </p>
+  </dd>
+</dl>

data/lib/motion/project/appcast/release_notes.template.erb

@@ -0,0 +1,19 @@
+<html>
+  <head>
+    <title>Release Notes for <%= @config.name %></title>
+    <style>
+      * { font-family: "Helvetica Neue", "Helvetica", "Arial", "Sans";}
+      h1 { background-color: #ABABFF; padding: 10px;}
+      h1 span { font-size: 75%; font-weight: normal; float: right;}
+      dt { font-size: 105%; font-weight: bold; margin: 5px 0;}
+      dd { margin: 0; padding: 5px 0 0 5px; }
+      dd p {margin: 2px 0; padding: 0;}
+    </style>
+  </head>
+  
+  <body>
+    
+    <%= release_notes_html %>
+
+  </body>
+</html>