reflex-packager 0.1.2

data/lib/reflex/packager/config.rb

@@ -0,0 +1,183 @@
+require 'yaml'
+
+
+module Reflex
+
+
+  # Tools to package a Reflex application as a distributable bundle.
+  # Files under this directory must not require 'reflex' because it has
+  # side effects such as requiring native extensions.
+  #
+  module Packager
+
+
+    # Application project configuration loaded from 'reflex.yml'.
+    #
+    class Config
+
+      def self.defaults(profile, dir, hash)
+        name = hash[:name]&.to_s || File.basename(dir)
+        {
+          name:      name,
+          bundle_id: hash[:bundle_id] || default_bundle_id(profile, name),
+          version:   '0.1.0',
+          main:      'main.rb',
+          icon:      nil,
+          files:     nil,
+          pods: {
+            :cruby          => {tag: nil, branch: nil, git: nil, path: nil},
+            profile.pod_key => {tag: nil, branch: nil, git: nil, path: nil}
+          },
+          macos: MacOSConfig.defaults
+        }
+      end
+
+      # Load the config file in the project directory.
+      #
+      # @param [Profile] profile runtime profile to package for
+      # @param [String]  dir     project directory
+      # @param [String]  path    config file path to use instead of the default
+      #
+      # @return [Config] config object
+      #
+      def self.load(profile, dir, path = nil)
+        raise Error, "config file not found: '#{path}'" if path && !File.file?(path)
+        path ||= profile.config_files.map {File.join dir, _1}.find {File.file? _1}
+        new profile, dir, (path ? YAML.safe_load(File.read(path), aliases: true) : nil)
+      rescue Psych::SyntaxError => e
+        raise Error, "failed to parse '#{path}': #{e.message}"
+      end
+
+      def initialize(profile, dir, hash = nil, stderr: $stderr)
+        raise Error, "no such directory: '#{dir}'" unless File.directory? dir
+
+        @profile = profile
+        @dir     = File.expand_path dir
+        hash = symbolize_keys hash || {}
+        hash = validate_input hash, Config.defaults(profile, @dir, hash), stderr: stderr
+
+        @name      = hash[:name]     .to_s
+        @bundle_id = hash[:bundle_id].to_s
+        @version   = hash[:version]  .to_s
+        @main      = hash[:main]     .to_s
+        @icon      = hash[:icon]    &.to_s
+        @files     = hash[:files]&.then {Array(_1).map(&:to_s)}
+        @pods      = hash[:pods].transform_values &:compact
+        @macos     = MacOSConfig.new hash[:macos]
+        validate
+      end
+
+      attr_reader :profile, :dir, :name, :bundle_id, :version, :main, :icon,
+        :files, :macos, :pods
+
+      # Returns paths to be bundled into the application, relative to the
+      # project directory.
+      #
+      # @return [Array<String>] relative paths
+      #
+      def app_files()
+        excludes = EXCLUDES + @profile.config_files
+        [@main, *@files]
+          .flat_map {Dir.glob _1, base: @dir}
+          .reject {_1.start_with?('.') || excludes.include?(_1)}
+          .uniq
+          .sort
+      end
+
+      EXCLUDES = %w[build dist]
+
+      private
+
+      def self.default_bundle_id(profile, name)
+        id = name.downcase.gsub(/[^a-z0-9\-]+/, '')
+        if id.empty?
+          raise Error, "cannot derive a bundle_id from name '#{name}', " +
+            "set 'bundle_id' in #{profile.config_files.first}"
+        end
+        "#{profile.bundle_id_prefix}.#{id}"
+      end
+
+      def symbolize_keys(hash)
+        hash.map {|k, v|
+          [
+            k.to_sym,
+            v.is_a?(Hash) ? symbolize_keys(v) : v
+          ]
+        }.to_h
+      end
+
+      def validate_input(hash, defaults, parent: '', stderr: nil)
+        return defaults.dup if hash.nil?
+        raise Error, "not a Hash: '#{parent}'" unless hash.is_a? Hash
+        hash.each_key {stderr&.puts "unknown key '#{parent}/#{_1}'" unless defaults.key? _1}
+
+        defaults.each.with_object({}) do |(key, defval), result|
+          value       = hash[key]
+          result[key] =
+            if defval.is_a? Hash
+              validate_input value, defval, parent: "#{parent}/#{key}", stderr: stderr
+            else
+              raise Error, "unexpected Hash: '#{parent}/#{key}'" if value.is_a? Hash
+              value.nil? ? defval : value
+            end
+        end
+      end
+
+      def validate()
+        raise Error, "invalid bundle_id: '#{@bundle_id}'" if
+          @bundle_id !~ /\A[A-Za-z0-9\-]+(\.[A-Za-z0-9\-]+)+\z/
+
+        raise Error, "invalid version: '#{@version}'" if
+          @version !~ /\A\d+(\.\d+)*\z/
+
+        raise Error, "main script not found: '#{@main}'" if
+          !File.file?(File.join @dir, @main)
+
+        raise Error, "icon not found: '#{@icon}'" if
+          @icon && !File.file?(File.join @dir, @icon)
+      end
+
+    end# Config
+
+
+    # macOS specific configuration.
+    #
+    class MacOSConfig
+
+      def self.defaults()
+        {
+          deployment_target: '11.0',
+          archs:             'arm64',
+          codesign: {
+            identity: '-',
+            team_id:  nil
+          }
+        }
+      end
+
+      def initialize(hash)
+        @deployment_target = hash[:deployment_target]  .to_s
+        @archs             = Array(hash[:archs]).map  &:to_s
+        @codesign_identity = hash[:codesign][:identity].to_s
+        @codesign_team_id  = hash[:codesign][:team_id]&.to_s
+        validate
+      end
+
+      attr_reader :deployment_target, :archs, :codesign_identity, :codesign_team_id
+
+      def validate()
+        raise Error, "invalid archs: '#{@archs}'" if @archs.empty?
+      end
+
+    end# MacOSConfig
+
+
+    # Raised on invalid configuration or packaging failure.
+    #
+    class Error < StandardError; end
+
+
+  end# Packager
+
+
+end# Reflex

data/lib/reflex/packager/extension.rb

@@ -0,0 +1,32 @@
+module Reflex
+
+
+  module Packager
+
+
+    # @private
+    module Extension
+
+      module_function
+
+      def name(downcase = false)
+        super().split('::')[..-2].join.then {|s|
+          downcase ? s.gsub(/([a-z])([A-Z])/) {"#{$1}-#{$2}"}.downcase : s
+        }
+      end
+
+      def version()
+        File.read(root_dir 'VERSION')[/[\d\.]+/]
+      end
+
+      def root_dir(path = '')
+        File.expand_path "../../../#{path}", __dir__
+      end
+
+    end# Extension
+
+
+  end# Packager
+
+
+end# Reflex

data/lib/reflex/packager/macos.rb

@@ -0,0 +1,190 @@
+require 'reflex/packager/platform'
+
+
+module Reflex
+
+
+  module Packager
+
+
+    # Packages a Reflex application as a macOS application bundle.
+    #
+    class MacOS < Platform
+
+      GIT_CRUBY = 'https://github.com/xord/cruby'
+
+      TOOLS = {
+        xcodegen:   'install with: brew install xcodegen',
+        pod:        'install with: brew install cocoapods (or gem install cocoapods)',
+        xcodebuild: 'install Xcode and run: sudo xcode-select --switch /Applications/Xcode.app'
+      }
+
+      def generate()
+        copy_app_files
+        generate_icon if config.icon
+        write 'project.yml', render('project.yml.erb')
+        write 'Podfile',     render('Podfile.erb')
+        write 'src/main.mm', render('main.mm.erb')
+      end
+
+      def build()
+        check_tools TOOLS
+        check_dev_pods
+        run 'xcodegen', 'generate',                       chdir: build_dir
+        run 'pod', 'install', *('--verbose' if verbose?), chdir: build_dir,
+          env: {'os' => 'macos'}
+        run 'xcodebuild',
+          '-workspace',       "#{target}.xcworkspace",
+          '-scheme',          target,
+          '-configuration',   'Release',
+          '-destination',     'platform=macOS',
+          '-derivedDataPath', 'DerivedData',
+          'build',
+          chdir: build_dir
+        copy_app
+      end
+
+      # Returns the Xcode target name: the app name without characters
+      # unsafe for target/scheme/file names.
+      #
+      def target()
+        config.name.gsub(/[^A-Za-z0-9_\-]+/, '').then {_1.empty? ? 'App' : _1}
+      end
+
+      def build_dir()
+        File.join config.dir, 'build', platform_name
+      end
+
+      def dist_dir()
+        File.join config.dir, 'dist'
+      end
+
+      # Native extensions registered with CRuby (Init_<name> symbols).
+      #
+      def extensions()
+        profile.extensions
+      end
+
+      # Ruby library bundles added to the load path.
+      #
+      def libraries()
+        profile.libraries
+      end
+
+      # Returns {'CRuby' => {...}, '<pod>' => {...}} resolved from the config,
+      # the <POD>_PODS_PATH env var, or the defaults.
+      #
+      def pod_refs()
+        p = profile
+        {
+          'CRuby' => pod_ref(:cruby,    {git: GIT_CRUBY}),
+          p.pod   => pod_ref(p.pod_key, {git: p.git, tag: "v#{p.version}"})
+        }
+      end
+
+      # Returns local directories of pods referenced by path, which need
+      # special handling because CocoaPods does not place development
+      # pods under PODS_ROOT and does not run their prepare_command.
+      #
+      def dev_pod_paths()
+        pod_refs
+          .filter_map {|name, ref| [name, ref[:path]] if ref[:path]}
+          .to_h
+      end
+
+      # Returns sips command lines to resize the icon into an iconset.
+      #
+      def icon_commands(src, iconset_dir)
+        [16, 32, 128, 256, 512].flat_map {|size|
+          [[size, "icon_#{size}x#{size}.png"], [size * 2, "icon_#{size}x#{size}@2x.png"]]
+        }.map {|px, file|
+          ['sips', '-z', px.to_s, px.to_s, src, '--out', File.join(iconset_dir, file)]
+        }
+      end
+
+      private
+
+      def platform_name()
+        'macos'
+      end
+
+      def pod_ref(name, default)
+        ref = config.pods[name]
+        return ref unless ref.nil? || ref.empty?
+
+        root = ENV["#{profile.pod_key.to_s.upcase}_PODS_PATH"]
+        root ? {path: File.expand_path(name.to_s, root)} : default
+      end
+
+      def pod_line(name, ref)
+        args = ref.map {|key, value| "#{key}: '#{value}'"}.join ', '
+        "pod '#{name}', #{args}"
+      end
+
+      def copy_app_files()
+        dir = File.join build_dir, 'app'
+        FileUtils.rm_rf dir
+        FileUtils.mkdir_p dir
+        config.app_files.each do |file|
+          dest = File.join dir, file
+          FileUtils.mkdir_p File.dirname(dest)
+          FileUtils.cp_r File.join(config.dir, file), dest
+        end
+      end
+
+      def generate_icon()
+        iconset = File.join build_dir, 'AppIcon.iconset'
+        FileUtils.rm_rf iconset
+        FileUtils.mkdir_p iconset
+        icon_commands(File.join(config.dir, config.icon), iconset)
+          .each {|cmd| run(*cmd, chdir: build_dir)}
+        run 'iconutil', '-c', 'icns', 'AppIcon.iconset', '-o', 'AppIcon.icns',
+          chdir: build_dir
+      end
+
+      # Development pods skip prepare_command on pod install, so ensure
+      # that the manual setups have been done.
+      #
+      def check_dev_pods()
+        dev_pod_paths.each do |name, path|
+          raise Error, "pod directory not found: '#{path}'" unless File.directory? path
+          if name == 'CRuby'
+            unless File.directory? File.join(path, 'CRuby', 'include')
+              raise Error,
+                "'#{path}' has no CRuby binary, " +
+                "run: cd #{path} && rake download_or_build os=macos"
+            end
+          else # the umbrella pod (Reflex / RubySketch / ...)
+            unless File.directory? File.join(path, 'all')
+              raise Error,
+                "'#{path}' is not set up for CocoaPods, " +
+                "run: cd #{path} && rake -f pod.rake setup"
+            end
+          end
+        end
+      end
+
+      def copy_app()
+        app = File.join build_dir, 'DerivedData', 'Build', 'Products', 'Release', "#{target}.app"
+        raise Error, "application not found: '#{app}'" unless File.directory? app
+
+        dist = File.join dist_dir, "#{target}.app"
+        FileUtils.rm_rf dist
+        FileUtils.mkdir_p dist_dir
+        FileUtils.cp_r app, dist
+        puts "Created #{dist}"
+      end
+
+      def write(path, content)
+        path = File.join build_dir, path
+        FileUtils.mkdir_p File.dirname(path)
+        File.write path, content
+      end
+
+    end# MacOS
+
+
+  end# Packager
+
+
+end# Reflex

data/lib/reflex/packager/platform.rb

@@ -0,0 +1,73 @@
+require 'erb'
+require 'fileutils'
+
+
+module Reflex
+
+
+  module Packager
+
+
+    TEMPLATES_DIR = File.expand_path 'templates', __dir__
+
+    # Base class for platform specific packagers.
+    #
+    class Platform
+
+      def initialize(config, verbose: false)
+        @config, @verbose = config, verbose
+      end
+
+      attr_reader :config
+
+      def profile
+        config.profile
+      end
+
+      def verbose?()
+        @verbose
+      end
+
+      # Package the application as a distributable bundle.
+      #
+      # @param [Boolean] generate_only generate the project files but do
+      #   not build them
+      #
+      def package(generate_only: false)
+        generate
+        build unless generate_only
+      end
+
+      private
+
+      def render(template)
+        path = File.join TEMPLATES_DIR, platform_name, template
+        ERB.new(File.read(path), trim_mode: '-').result binding
+      end
+
+      def run(*cmd, chdir:, env: {})
+        puts "==> #{cmd.join ' '}"
+        return if system env, *cmd, chdir: chdir
+        raise Error, "command failed: #{cmd.join ' '}"
+      end
+
+      def check_tools(tools)
+        missing = tools.reject {|name, _| executable? name}
+        return if missing.empty?
+
+        list = missing.map {|name, hint| '  %-10s -- %s' % [name, hint]}
+        raise Error, "required tools not found:\n#{list.join "\n"}"
+      end
+
+      def executable?(name)
+        ENV['PATH'].to_s.split(File::PATH_SEPARATOR)
+          .any? {|dir| File.executable? File.join(dir, name.to_s)}
+      end
+
+    end# Platform
+
+
+  end# Packager
+
+
+end# Reflex

data/lib/reflex/packager/profile.rb

@@ -0,0 +1,45 @@
+module Reflex
+
+
+  module Packager
+
+
+    # Describes the runtime a packaged app embeds: the umbrella pod that
+    # provides the native build, the extensions and libraries registered with
+    # CRuby, and the scaffold for the 'new' command.
+    #
+    # The packager itself is runtime-agnostic; each gem (reflex, rubysketch,
+    # ...) supplies its own profile and reuses this packager as the engine.
+    #
+    class Profile
+
+      # @param [String]        pod          umbrella pod name (e.g. 'Reflex')
+      # @param [String]        git          umbrella pod git repository
+      # @param [String]        version      umbrella pod version (for the tag)
+      # @param [Array<String>] libraries    ruby lib bundles to add to load path
+      # @param [Array<String>] extensions   native exts to register (Init_<name>)
+      # @param [Array<String>] config_files config file names, preferred first
+      # @param [String]        template     'new' main script template ({{name}})
+      #
+      def initialize(pod:, git:, version:, libraries:, extensions:, config_files:, template:)
+        @pod, @git, @version, @libraries, @extensions, @config_files, @template =
+          pod, git, version, libraries, extensions, config_files, template
+      end
+
+      attr_reader :pod, :git, :version, :libraries, :extensions, :config_files, :template
+
+      def pod_key()
+        pod.downcase.to_sym
+      end
+
+      def bundle_id_prefix()
+        "org.xord.#{pod_key}"
+      end
+
+    end# Profile
+
+
+  end# Packager
+
+
+end# Reflex

data/lib/reflex/packager/templates/macos/Podfile.erb

@@ -0,0 +1,30 @@
+# -*- mode: ruby -*-
+
+platform :macos, '<%= config.macos.deployment_target %>'
+
+target '<%= target %>' do
+<%- pod_refs.each do |name, ref| -%>
+  <%= pod_line name, ref %>
+<%- end -%>
+end
+
+post_install do |installer|
+  installer.pods_project.targets.each do |target|
+    target.build_configurations.each do |c|
+      c.build_settings['ARCHS']       = '<%= config.macos.archs.join ' ' %>'
+      c.build_settings['VALID_ARCHS'] = '<%= config.macos.archs.join ' ' %>'
+    end
+  end
+<%- unless dev_pod_paths.empty? -%>
+
+  # development pods are not placed under PODS_ROOT, so resolve
+  # '${PODS_ROOT}/<name>' to each local directory in the xcconfigs
+  Dir.glob('Pods/Target Support Files/**/*.xcconfig').each do |path|
+    s = File.read path
+<%- dev_pod_paths.each do |name, dir| -%>
+    s.gsub! '${PODS_ROOT}/<%= name %>', '<%= dir %>'
+<%- end -%>
+    File.write path, s
+  end
+<%- end -%>
+end

data/lib/reflex/packager/templates/macos/main.mm.erb

@@ -0,0 +1,43 @@
+// -*- mode: objc -*-
+#import <Cocoa/Cocoa.h>
+#import <CRuby.h>
+
+
+extern "C"
+{
+<%- extensions.each do |ext| -%>
+	void Init_<%= ext %> ();
+<%- end -%>
+}
+
+
+int
+main (int argc, const char* argv[])
+{
+	@autoreleasepool
+	{
+		NSString* appDir =
+			[NSBundle.mainBundle.resourcePath stringByAppendingPathComponent:@"app"];
+
+		// the application loads images by paths relative to the script
+		[NSFileManager.defaultManager changeCurrentDirectoryPath:appDir];
+
+<%- extensions.each do |ext| -%>
+		[CRuby addExtension:@"<%= ext %>" init:^{Init_<%= ext %>();}];
+<%- end -%>
+
+		for (NSString* lib in @[<%= libraries.map {|l| "@\"#{l}\""}.join ', ' %>])
+			[CRuby addLibrary:lib bundle:NSBundle.mainBundle];
+
+		NSString* main = [appDir stringByAppendingPathComponent:@"<%= config.main %>"];
+
+		// add the script directory to the load path so that apps split
+		// into multiple files can require each other
+		[CRuby evaluate:[NSString stringWithFormat:@"$LOAD_PATH.unshift '%@'", appDir]];
+
+		// the script calls Reflex.start, which runs [NSApp run] and blocks
+		// here until the application quits
+		[CRuby start:main];
+	}
+	return 0;
+}

data/lib/reflex/packager/templates/macos/project.yml.erb

@@ -0,0 +1,40 @@
+name: <%= target %>
+
+options:
+  deploymentTarget:
+    macOS: "<%= config.macos.deployment_target %>"
+
+settings:
+  base:
+    PRODUCT_BUNDLE_IDENTIFIER: <%= config.bundle_id %>
+    MARKETING_VERSION: "<%= config.version %>"
+    ARCHS: <%= config.macos.archs.join ' ' %>
+    ONLY_ACTIVE_ARCH: NO
+    CODE_SIGN_IDENTITY: <%= config.macos.codesign_identity.inspect %>
+<%- if config.macos.codesign_team_id -%>
+    DEVELOPMENT_TEAM: <%= config.macos.codesign_team_id %>
+<%- end -%>
+
+targets:
+  <%= target %>:
+    type: application
+    platform: macOS
+    sources:
+      - path: src
+      - path: app
+        type: folder
+        buildPhase: resources
+<%- if config.icon -%>
+      - path: AppIcon.icns
+        buildPhase: resources
+<%- end -%>
+    info:
+      path: src/Info.plist
+      properties:
+        CFBundleName: <%= config.name.inspect %>
+        CFBundleDisplayName: <%= config.name.inspect %>
+        CFBundleShortVersionString: "<%= config.version %>"
+        NSHighResolutionCapable: true
+<%- if config.icon -%>
+        CFBundleIconFile: AppIcon
+<%- end -%>

data/lib/reflex/packager.rb

@@ -0,0 +1,12 @@
+require 'reflex/packager/extension'
+
+require 'reflex/packager/profile'
+require 'reflex/packager/config'
+require 'reflex/packager/platform'
+require 'reflex/packager/macos'
+require 'reflex/packager/cli'
+
+
+module Reflex::Packager
+  PLATFORMS = {macos: MacOS}
+end

data/reflex-packager.gemspec

@@ -0,0 +1,37 @@
+# -*- mode: ruby -*-
+
+
+require_relative 'lib/reflex/packager/extension'
+
+
+Gem::Specification.new do |s|
+  glob = -> *patterns do
+    patterns.map {|pat| Dir.glob(pat).to_a}.flatten
+  end
+
+  ext   = Reflex::Packager::Extension
+  name  = ext.name true
+  rdocs = glob.call *%w[README]
+
+  s.name        = name
+  s.version     = ext.version
+  s.license     = 'MIT'
+  s.summary     = 'Package Reflex applications as native app bundles.'
+  s.description = 'CLI tool to package Reflex applications as native macOS application bundles.'
+  s.authors     = %w[xordog]
+  s.email       = 'xordog@gmail.com'
+  s.homepage    = "https://github.com/xord/reflex-packager"
+
+  s.platform              = Gem::Platform::RUBY
+  s.required_ruby_version = '>= 3.0.0'
+
+  s.add_dependency 'xot',       '~> 0.3.15'
+  s.add_dependency 'rucy',      '~> 0.3.15'
+  s.add_dependency 'rays',      '~> 0.3.16'
+  s.add_dependency 'reflexion', '~> 0.5.0'
+
+  s.files            = `git ls-files`.split $/
+  s.executables      = s.files.grep(%r{^bin/}) {|f| File.basename f}
+  s.test_files       = s.files.grep %r{^(test|spec|features)/}
+  s.extra_rdoc_files = rdocs.to_a
+end