hotcocoa 0.5.1 → 0.6.0pre

data/docs/Resources.markdown

@@ -0,0 +1,25 @@
+# Resources
+
+This page is an informal index to HotCocoa resources.
+
+## Articles
+
+* Isaac Kearse
+ + [Stopwatch - A HotCocoa Status Bar Timer](http://isaac.kearse.co.nz/2010/01/31/stopwatch/)
+ + [Packaging A HotCocoa Application](http://isaac.kearse.co.nz/2010/02/01/packaging-hotcocoa/)
+ + [SafariRSS - HotCocoa Safari RSS Handler](http://isaac.kearse.co.nz/2010/02/07/safarirss/)
+
+* Dan Sinclair
+ + [Heating up with HotCocoa Part I](http://everburning.com/news/heating-up-with-hotcocoa-part-i/)
+ + [Heating up with HotCocoa Part II](http://everburning.com/news/heating-up-with-hotcocoa-part-ii/)
+ + [Heating up with HotCocoa Part III](http://everburning.com/news/heating-up-with-hotcocoa-part-iii/)
+ + [Heating up with HotCocoa on GitHub](http://everburning.com/news/heating-up-with-hotcocoa-on-github/)
+ + [Download and XML parsing with HotCocoa](http://everburning.com/news/download-and-xml-parsing-with-hotcocoa/)
+ + [Toolbars with HotCocoa](http://everburning.com/news/toolbars-with-hotcocoa/)
+ + [HotCocoa and Core Data](http://everburning.com/news/hotcocoa-and-core-data/)
+
+* Gary Weaver
+ + [HotCocoa App to track Time on Tasks](http://stufftohelpyouout.blogspot.com/2010/02/hotcocoa-app-to-track-time-on-tasks.html)
+ + [Create a Custom Icon for Your HotCocoa App](http://stufftohelpyouout.blogspot.com/2010/02/create-custom-icon-of-your-hotcocoa-app.html)
+ + [Create a MacRuby HotCocoa App](http://stufftohelpyouout.blogspot.com/2010/02/create-macruby-hotcocoa-app.html)
+ + [HotCocoa/MacRuby Links](http://stufftohelpyouout.blogspot.com/2010/03/hotcocoamacruby-links.html)

data/docs/Tutorial.markdown

@@ -0,0 +1,3 @@
+# HotCocoa Tutorial
+
+This still needs to be ported from the wiki on Github.

data/lib/hotcocoa/application/builder.rb

@@ -0,0 +1,237 @@
+framework 'Foundation'
+
+require 'fileutils'
+require 'rbconfig'
+require 'hotcocoa/application/specification'
+
+module Application
+  ##
+  # This class is responsible for building application bundles, but could
+  # theoretically be used to build other bundles, such as frameworks, with
+  # only a few changes.
+  class Builder
+
+    ##
+    # Build an application from a specification, optionally for
+    # deployment.
+    #
+    # @param [Application::Specification] spec
+    # @param [Hash] opts
+    # @option opts [Symbol] :deploy (false)
+    def self.build spec, opts = {}
+      new(spec).build(opts)
+    end
+
+    # @return [Application::Specification]
+    attr_reader :spec
+
+    # @param [Application::Specification]
+    def initialize spec
+      @spec = case spec
+      when Specification
+        spec
+      when String
+        Specification.load spec
+      end
+    end
+
+    # @param [Hash]
+    # @option opts [Symbol] :deploy (false)
+    def build opts = {}
+      if spec.overwrite? || opts[:deploy] # Deploying always makes a fresh build
+        remove_bundle_root
+      end
+      build_bundle_structure
+      write_bundle_files
+      copy_sources
+      copy_resources
+      compile_data_models
+      copy_icon_file if spec.icon_exists?
+      deploy if opts[:deploy]
+    end
+
+    def run
+      `"./#{executable_file}"`
+    end
+
+    def remove_bundle_root
+      FileUtils.rm_rf bundle_root if File.exist?(bundle_root)
+    end
+
+
+    private
+
+    ##
+    # Build arguments list and call to `macruby_deploy`.
+    def deploy
+      puts `macruby_deploy --embed --gem hotcocoa #{deploy_options} #{bundle_root}`
+    end
+
+    def deploy_options
+      options = []
+      spec.gems.each { |g| options << "--gem #{g}" }
+      options << '--bs'        if spec.embed_bs?
+      options << '--compile'   if spec.compile?
+      options << '--no-stdlib' unless spec.stdlib # @todo use attribute properly
+      options.join(' ')
+    end
+
+    def build_bundle_structure
+      [bundle_root, contents_root, frameworks_root, macos_root, resources_root].each do |dir|
+        Dir.mkdir(dir) unless File.exist?(dir)
+      end
+    end
+
+    def write_bundle_files
+      write_pkg_info_file
+      write_info_plist_file
+      build_executable unless File.exist?(executable_file)
+      write_ruby_main
+    end
+
+    def copy_sources
+      spec.sources.each do |source|
+        destination = File.join(resources_root, source)
+        FileUtils.mkdir_p(File.dirname(destination)) unless File.exist?(File.dirname(destination))
+        FileUtils.cp_r source, destination
+      end
+    end
+
+    def copy_resources
+      spec.resources.each do |resource|
+        destination = File.join(resources_root, resource.split('/')[1..-1].join('/'))
+        FileUtils.mkdir_p(File.dirname(destination)) unless File.exist?(File.dirname(destination))
+
+        if resource =~ /\.xib$/
+          destination.gsub!(/.xib/, '.nib')
+          puts `ibtool --compile #{destination} #{resource}`
+        else
+          FileUtils.cp_r resource, destination
+        end
+      end
+    end
+
+    def compile_data_models
+      spec.data_models.each do |data|
+        `/Developer/usr/bin/momc #{data} #{resources_root}/#{File.basename(data, ".xcdatamodel")}.mom`
+      end
+    end
+
+    def copy_icon_file
+      FileUtils.cp spec.icon, icon_file
+    end
+
+    def write_pkg_info_file
+      File.open(pkg_info_file, 'wb') { |f| f.write "#{spec.type}#{spec.signature}" }
+    end
+
+    def write_info_plist_file
+      # http://developer.apple.com/library/mac/#documentation/General/Reference/InfoPlistKeyReference/Articles/AboutInformationPropertyListFiles.html%23//apple_ref/doc/uid/TP40009254-SW1
+      info = {
+        CFBundleName:                  spec.name,
+        CFBundleIdentifier:            spec.identifier,
+        CFBundleVersion:               spec.version,
+        CFBundlePackageType:           spec.type,
+        CFBundleSignature:             spec.signature,
+        CFBundleExecutable:            executable_file_name,
+        CFBundleDevelopmentRegion:     'English',
+        CFBundleInfoDictionaryVersion: '6.0',
+        NSPrincipalClass:              'NSApplication',
+        LSUIElement:                   spec.agent,
+        LSMinimumSystemVersion:        '10.6.7', # should match MacRuby
+      }
+      info[:CFBundleIconFile] = File.basename(spec.icon) if spec.icon_exists?
+
+      File.open(info_plist_file, 'w') { |f| f.write info.to_plist }
+    end
+
+    # @todo something better than puts `gcc`
+    def build_executable
+      File.open(objective_c_source_file, 'wb') do |f|
+        f.write %{
+            #import <MacRuby/MacRuby.h>
+
+            int main(int argc, char *argv[])
+            {
+                return macruby_main("rb_main.rb", argc, argv);
+            }
+        }
+      end
+      Dir.chdir(macos_root) do
+        puts `gcc main.m -o #{executable_file_name} -arch x86_64 -framework MacRuby -framework Foundation -fobjc-gc-only`
+      end
+      File.unlink(objective_c_source_file)
+    end
+
+    # Borrow rb_main from MacRuby Xcode templates
+    def write_ruby_main
+      File.open(main_ruby_source_file, 'wb') do |f|
+        f.write <<-EOF
+    # Borrowed from the MacRuby sources on April 18, 2011
+    framework 'Cocoa'
+
+    # Loading all the Ruby project files.
+    main = File.basename(__FILE__, File.extname(__FILE__))
+    dir_path = NSBundle.mainBundle.resourcePath.fileSystemRepresentation
+    dir_path += "/lib/"
+    Dir.glob(File.join(dir_path, '*.{rb,rbo}')).map { |x| File.basename(x, File.extname(x)) }.uniq.each do |path|
+    if path != main
+      require File.join(dir_path, path)
+    end
+    end
+
+    # Starting the Cocoa main loop.
+    NSApplicationMain(0, nil)
+        EOF
+      end
+    end
+
+    def bundle_root
+      "#{spec.name}.app"
+    end
+
+    def contents_root
+      File.join(bundle_root, 'Contents')
+    end
+
+    def frameworks_root
+      File.join(contents_root, 'Frameworks')
+    end
+
+    def macos_root
+      File.join(contents_root, 'MacOS')
+    end
+
+    def resources_root
+      File.join(contents_root, 'Resources')
+    end
+
+    def info_plist_file
+      File.join(contents_root, 'Info.plist')
+    end
+
+    def icon_file
+      File.join(resources_root, "#{spec.name}.icns")
+    end
+
+    def pkg_info_file
+      File.join(contents_root, 'PkgInfo')
+    end
+
+    def executable_file_name
+      spec.name.gsub(/\s+/, '')
+    end
+
+    def executable_file
+      File.join(macos_root, executable_file_name)
+    end
+
+    def objective_c_source_file
+      File.join(macos_root, 'main.m')
+    end
+
+    def main_ruby_source_file
+      File.join(resources_root, 'rb_main.rb')
+    end
+  end
+end

data/lib/hotcocoa/application/specification.rb

@@ -0,0 +1,373 @@
+# -*- coding: utf-8 -*-
+
+require 'rubygems'
+
+##
+# Application is a namespace for the classes that are used to specify
+# and build application bundles.
+module Application
+
+  ##
+  # Inspired by Gem::Specification that is used by Rubygems, this class
+  # represents the configuration for a Mac OS X application bundle.
+  #
+  # A specification object is used to build your [app bundle](http://developer.apple.com/library/mac/#documentation/CoreFoundation/Conceptual/CFBundles/Introduction/Introduction.html#//apple_ref/doc/uid/10000123i-CH1-SW1) and define the
+  # [Info.plist](http://developer.apple.com/library/mac/#documentation/MacOSX/Conceptual/BPRuntimeConfig/000-Introduction/introduction.html#//apple_ref/doc/uid/10000170-SW1)
+  # metadata for the application.
+  class Specification
+
+    ##
+    # Read an app spec from file and return what is evaluated.
+    #
+    # @return [Application::Specification]
+    def self.load file
+      eval File.read(file)
+    end
+
+    # @group App Metadata
+
+    ##
+    # Name of the app. Required.
+    #
+    # This name should be less than 16 characters long.
+    #
+    # @plist CFBundleName
+    # @return [String]
+    attr_accessor :name
+
+    ##
+    # The app's unique identifier, in reverse DNS form. Required.
+    #
+    # @example Identifier for Mail.app
+    #   'com.apple.mail'
+    #
+    # @plist CFBundleIdentifier
+    # @return [String]
+    attr_accessor :identifier
+
+    ##
+    # The version of the app, usually including the build number.
+    # Recommended.
+    #
+    # Defaults to `'1.0'`.
+    #
+    # @plist CFBundleVersion
+    # @return [String]
+    attr_accessor :version
+
+    ##
+    # The short version for the app. Optional.
+    #
+    # The short version for an app should be in the standard
+    # `"$MAJOR.$MINOR.$PATCHLEVEL"` format.
+    #
+    # @plist CFBundleShortVersionString
+    # @return [String]
+    attr_accessor :short_version
+
+    ##
+    # The copyright string. Recommended.
+    #
+    # @example
+    #   © 2011, Your Company
+    #
+    # @plist NSHumanReadableCopyright
+    attr_accessor :copyright
+
+    ##
+    # Path to the icon file. Recommended.
+    #
+    # @plist CFBundleIconFile
+    # @return [String]
+    attr_accessor :icon
+
+    ##
+    # Four letter code identifying the bundle type. Required.
+    #
+    # The default value is 'APPL', which specifies that the bundle
+    # is an application.
+    #
+    # @plist CFBundlePackageType
+    # @return [String]
+    attr_accessor :type
+
+    ##
+    # Four letter code that acts as a signature for the bundle. Optional.
+    #
+    # Defaults to '????', and most apps never set this value.
+    #
+    # @example TextEdit.app
+    #   'ttxt'
+    # @example Mail.app
+    #   'emal'
+    #
+    # @plist CFBundleSignature
+    # @return [String]
+    attr_accessor :signature
+
+    ##
+    # Whether the app is an daemon with UI or a regular app. Optional.
+    #
+    # You can use this flag to hide the dock icon for the app; the
+    # default value is false so that apps will have a dock icon by default.
+    #
+    # @return [Boolean]
+    attr_accessor :agent
+
+    # @todo CFBundleDocumentTypes
+    # @return [Array<Hash>]
+    # attr_accessor :doc_types
+
+    ##
+    # Any additional plist values that an application could have.
+    #
+    # Values here will override attributes set by other plist related
+    # attributes.
+    #
+    # Empty by default.
+    #
+    # @return [Hash]
+    # attr_accessor :plist
+
+    # @todo Support localization related plist keys natively
+    # @todo CFBundleDevelopmentRegion (Recommended)
+
+    # @group App Layout
+
+    ##
+    # List of resources that will be copied to the `Contents/Resources`
+    # directory inside the app bundle.
+    #
+    # @return [Array<String>]
+    attr_accessor :resources
+
+    ##
+    # List of source code files that will be copied to the app bundle.
+    #
+    # @return [Array<String>]
+    attr_accessor :sources
+
+    ##
+    # Path to any Core Data `.xcdatamodel` directories that need to be
+    # compiled and added to the app bundle.
+    #
+    # @return [Array<String>]
+    attr_accessor :data_models
+
+    # @group Deloyment Options
+
+    ##
+    # Whether to include the Ruby stdlib in the app when embedding
+    # MacRuby. Set this to a Boolean to include/exclude the entire
+    # standard library from being embedded.
+    #
+    # If you want to embed specific files from the standard library,
+    # you can do so by setting this attribute a list of the names of
+    # libraries you want.
+    #
+    # @example
+    #
+    #   # Nothing
+    #   spec.stdlib = false
+    #   # Everything
+    #   spec.stdlib = true
+    #   # Just 'base64', 'matrix', and 'set'
+    #   spec.stdlib = ['base64', 'matrix', 'set']
+    #
+    # This attribute corresponds to the `--[no]-stdlib` and `--stdlib`
+    # arguments for `macruby_deploy`.
+    #
+    # Defaults to true.
+    #
+    # @return [Boolean, Array<String>]
+    attr_accessor :stdlib
+
+    ##
+    # @note If you choose to compile, the original source files will
+    #       be removed.
+    #
+    # Whether or not to compile ruby source files when embedding.
+    #
+    # Defaults to `true`.
+    #
+    # @return [Boolean]
+    attr_accessor :compile
+    alias_method :compile?, :compile
+
+    ##
+    # @note HotCocoa will automatically be embedded during deployment
+    #       and is not added to this list.
+    #
+    # Array of gem names to embed in the app bundle during deployment.
+    #
+    # @return [Array<Gem::Requirement>]
+    attr_accessor :gems
+
+    ##
+    # Declares a runtime dependency on a gem, with any given version
+    # requirements. If the embedding is also set, then any dependent gems
+    # will also be embedded into the app bundle.
+    #
+    # This method was liberally borrowed from RubyGems project and has
+    # the same semantics here as it does for a gem specification.
+    #
+    # @example
+    #
+    #   spec.add_runtime_dependency 'hotcocoa', '~> 0.6'
+    #
+    def add_runtime_dependency dependency, *requirements
+      requirements = if requirements.empty? then
+                       Gem::Requirement.default
+                     else
+                       requirements.flatten
+                     end
+
+      unless dependency.respond_to?(:name) &&
+          dependency.respond_to?(:version_requirements)
+
+        dependency = Gem::Dependency.new(dependency, requirements, :runtime)
+      end
+
+      gems << dependency
+    end
+    alias_method :add_dependency, :add_runtime_dependency
+
+    ##
+    # Whether or not to embed BridgeSupport files when embedding the
+    # MacRuby framework during deployment.
+    #
+    # Defaults to false. Useful if you need to deploy the app to
+    # OS X 10.6.
+    #
+    # @return [Boolean]
+    attr_accessor :embed_bs
+    alias_method :embed_bs?, :embed_bs
+
+    ##
+    # @todo Is this actually useful or can we get rid of it?
+    #
+    # Whether or not to always make a clean build of the app.
+    #
+    # Defaults to false.
+    #
+    # @return [Boolean]
+    attr_accessor :overwrite
+    alias_method :overwrite?, :overwrite
+
+    # @endgroup
+
+    DEFAULT_ATTRIBUTES = {
+      # plist:       {}, # @todo Finish this before release
+      sources:     [],
+      resources:   [],
+      data_models: [],
+      gems:        [],
+      type:        'APPL',
+      signature:   '????',
+      version:     '1.0',
+      stdlib:      true,
+      agent:       false,
+      compile:     true,
+      overwrite:   false,
+      embed_bs:    false
+    }
+
+    def initialize
+      DEFAULT_ATTRIBUTES.each { |key, value| send "#{key}=", value }
+
+      unless block_given?
+        msg = 'You must pass a block at initialization to setup the specification'
+        raise Error, msg
+      end
+      yield self
+
+      # @todo go through plist and overwrite specific keys?
+
+      # @todo should we verify at initialization or defer until building?
+      verify!
+    end
+
+    def verify!
+      verify_name
+      verify_identifier
+      verify_version
+      verify_short_version
+      verify_copyright
+      verify_type
+      verify_signature
+      verify_agent
+    end
+
+    class Error < ArgumentError
+    end
+
+    ##
+    # Whether or not the icon exists for this spec.
+    def icon_exists?
+      @icon ? File.exist?(@icon) : false
+    end
+
+
+    private
+
+    def verify_name
+      raise Error, 'a name is required for an appspec' unless @name
+      @name = @name.to_s
+      raise Error, 'an app name cannot be an empty string' if @name.empty?
+      warn 'an app name should be less than 16 characters' if name.length >= 16
+    end
+
+    # @todo Should we try to make the regexp more strict?
+    def verify_identifier
+      raise Error, 'a bundle identifier is required for an appspec' unless @identifier
+      @identifier = @identifier.to_s
+      raise Error, 'a bundle identifier cannot be an empty string' if @identifier.empty?
+      unless @identifier.match /^[A-Za-z0-9\.-]+$/
+        raise Error, 'A bundle identifier may only use "-", ".", and alphanumeric characters.' +
+          "You had #{@identifier.inspect}"
+      end
+    end
+
+    def verify_version
+      @version = @version.to_s
+    end
+
+    # @todo Should @version be enforced if @short_version is set?
+    def verify_short_version
+      return unless @short_version
+      @short_version = @short_version.to_s
+    end
+
+    def verify_copyright
+      @copyright = @copyright.to_s if @copyright
+    end
+
+    # @todo Should a warning be given if not embedding the stdlib?
+    def verify_stdlib
+      # need to be careful here; the main components of hotcocoa do
+      # not depend on the stdlib right now, but if that changes then
+      # this needs to be a failsafe
+    end
+
+    def verify_type
+      @type = @type.to_s
+      unless @type.length == 4
+        raise Error, 'A bundle type must be exactly 4 characters'
+      end
+    end
+
+    def verify_signature
+      @signature = @signature.to_s
+      unless @signature.length == 4
+        raise Error, 'A bundle signature must be exactly 4 characters'
+      end
+    end
+
+    def verify_agent
+      # we need to force this to a boolean since it will be written
+      # to the bundles Info.plist
+      @agent = !!@agent
+    end
+
+  end
+end