Glimmer Command

The glimmer command allows you to run, scaffold, package, and list Glimmer applications/gems more conveniently.

You can bring up usage instructions by running the glimmer command without arguments:

glimmer

On Mac and Linux, it additionally brings up a TUI (Text-based User Interface) for interactive navigation and execution of Glimmer tasks (courtesy of rake-tui).

(note that in ARM64 machines, the TUI does not seem to work at the moment, so simply use glimmer commands directly without the TUI until this is fixed)

On Windows, it simply lists the available Glimmer tasks at the end (courtsey of rake).

If you are new to Glimmer, you may read the Basic Usage section and skip the rest until you have gone through Girb (Glimmer irb) Command, Glimmer GUI DSL Syntax, and Samples.

Note: If you encounter an issue running the glimmer command, run bundle exec glimmer instead.

Basic Usage

You can run any Glimmer app with jruby directly, which is the most lightweight way of running Glimmer DSL for SWT applications. However, if you wrote an app that does not explicitly require 'glimmer-dsl-swt', then you may use the glimmer command for convenience instead since it automatically loads glimmer-dsl-swt.

glimmer application.rb

Runs a Glimmer application using JRuby, automatically preloading the glimmer ruby gem and SWT jar dependency.

Run Glimmer samples with:

glimmer samples

This brings up the Glimmer Meta-Sample (The Sample of Samples)

If you cloned this project locally instead of installing the gem, run bin/glimmer instead.

Example:

bin/glimmer samples

Advanced Usage

Below are the full usage instructions that come up when running glimmer without args.

Glimmer (JRuby Desktop Development GUI Framework) - JRuby Gem: glimmer-dsl-swt v4.18.7.4
      
Usage: glimmer [--bundler] [--pd] [--quiet] [--debug] [--log-level=VALUE] [[ENV_VAR=VALUE]...] [[-jruby-option]...] (application.rb or task[task_args]) [[application2.rb]...]

Runs Glimmer applications and tasks.

When applications are specified, they are run using JRuby,
automatically preloading the glimmer Ruby gem and SWT jar dependency.

Optionally, extra Glimmer options, JRuby options, and/or environment variables may be passed in.

Glimmer options:
- "--bundler=GROUP"   : Activates gems in Bundler default group in Gemfile
- "--pd=BOOLEAN"      : Requires puts_debuggerer to enable pd method
- "--quiet=BOOLEAN"   : Does not announce file path of Glimmer application being launched
- "--debug"           : Displays extra debugging information, passes "--debug" to JRuby, and enables debug logging
- "--log-level=VALUE" : Sets Glimmer's Ruby logger level ("ERROR" / "WARN" / "INFO" / "DEBUG"; default is none)

Tasks are run via rake. Some tasks take arguments in square brackets.

Available tasks are below (if you do not see any, please add `require 'glimmer/rake_task'` to Rakefile and rerun or run rake -T):

Select a Glimmer task to run: (Press ↑/↓ arrow to move, Enter to select and letters to filter)
  glimmer list:gems:customshape[query]                       # List Glimmer custom shape gems available at rubygems.org (query is optional) [alt: list:gems:cp]
‣ glimmer list:gems:customshell[query]                       # List Glimmer custom shell gems available at rubygems.org (query is optional) [alt: list:gems:cs]
  glimmer list:gems:customwidget[query]                      # List Glimmer custom widget gems available at rubygems.org (query is optional) [alt: list:gems:cw]
  glimmer list:gems:dsl[query]                               # List Glimmer DSL gems available at rubygems.org (query is optional)
  glimmer package[type]                                      # Package app for distribution (generating config, jar, and native files) (type is optional)
  glimmer package:clean                                      # Clean by removing "dist" and "packages" directories
  glimmer package:config                                     # Generate JAR config file
  glimmer package:gem                                        # Generate gem under pkg directory
  glimmer package:gemspec                                    # Generate gemspec
  glimmer package:jar                                        # Generate JAR file
  glimmer package:lock_jars                                  # Lock JARs
  glimmer package:native[type]                               # Generate Native files
  glimmer run[app_path]                                      # Runs Glimmer app or custom shell gem in the current directory, unless app_path is specified, then runs it instead (app_path is optional)
  glimmer samples                                            # Brings up the Glimmer Meta-Sample app to allow browsing, running, and viewing code of Glimmer samples
  glimmer scaffold[app_name]                                 # Scaffold Glimmer application directory structure to build a new app
  glimmer scaffold:customshape[name,namespace]               # Scaffold Glimmer::UI::CustomShape subclass (part of a view) under app/views (namespace is optional) [alt: scaffold:cp]
  glimmer scaffold:customshell[name,namespace]               # Scaffold Glimmer::UI::CustomShell subclass (full window view) under app/views (namespace is optional) [alt: scaffold:cs]
  glimmer scaffold:customwidget[name,namespace]              # Scaffold Glimmer::UI::CustomWidget subclass (part of a view) under app/views (namespace is optional) [alt: scaffold:cw]
  glimmer scaffold:desktopify[app_name,website]              # Desktopify a web app
  glimmer scaffold:gem:customshape[name,namespace]           # Scaffold Glimmer::UI::CustomShape subclass (part of a view) under its own Ruby gem project (namespace is required) [alt: scaffold:gem:cp]
  glimmer scaffold:gem:customshell[name,namespace]           # Scaffold Glimmer::UI::CustomShell subclass (full window view) under its own Ruby gem + app project (namespace is required) [alt: scaffold:ge...
  glimmer scaffold:gem:customwidget[name,namespace]          # Scaffold Glimmer::UI::CustomWidget subclass (part of a view) under its own Ruby gem project (namespace is required) [alt: scaffold:gem:cw]

Example (Glimmer/JRuby option specified):

glimmer --debug samples/hello/hello_world.rb

Runs Glimmer application with JRuby debug option to enable JRuby debugging.

Example (Multiple apps):

glimmer samples/hello/hello_world.rb samples/hello/hello_tab.rb

Launches samples/hello/hello_world.rb and samples/hello_tab.rb at the same time, each in a separate JRuby thread.

Note: under Zsh (Z Shell), glimmer can only be used in its advanced \ mode (e.g. glimmer and then selecting a task) not the primitive rake task mode (e.g. glimmer scaffold[app])

Glimmer Samples

You can list available Glimmer samples by running:

glimmer samples

This brings up the Glimmer Meta-Sample (The Sample of Samples):

Scaffolding

Glimmer borrows from Rails the idea of Scaffolding, that is generating a structure for your app files that helps you get started just like true building scaffolding helps construction workers, civil engineers, and architects.

Glimmer scaffolding goes beyond just scaffolding the app files. It also packages it and launches it, getting you to a running and delivered state of an advanced "Hello, World!" Glimmer application right off the bat.

This should greatly facilitate building a new Glimmer app by helping you be productive and focus on app details while letting Glimmer scaffolding take care of initial app file structure concerns, such as adding:

Main application class that includes Glimmer (app/{app_name}.rb)
Main application view that houses main window content, menu, about dialog, and preferences dialog
View and Model directories (app/views and app/models)
Rakefile including Glimmer tasks (Rakefile)
Version (VERSION)
License (LICENSE.txt)
Icon (under package/{platform}/{App Name}.{icon_extension} for macosx .icns, windows .ico, and linux .png)
Bin file for starting application (bin/{app_name}.rb)

You need to have your Git user.name and github.user configured before scaffolding since Glimmer uses Juwelier, which relies on them in creating a Git repo for your Glimmer app.

App

Before you start, make sure you are in a JRuby environment with glimmer-dsl-swt gem installed as per "Direct Install" pre-requisites.

To scaffold a Glimmer app from scratch, run the following command:

glimmer scaffold[AppName]

This will generate an advanced "Hello, World!" app, package it as a Mac DMG/PKG/APP, Windows APP, or Linux GEM, and launch it all in one fell swoop.

Suppose you run:

glimmer scaffold[greeter]

You should see output like the following:

$ glimmer scaffold[greeter]
  create  .gitignore
  create  Rakefile
  create  Gemfile
  create  LICENSE.txt
  create  README.markdown
  create  .document
  create  lib
  create  lib/snowboard_utah.rb
  create  .rspec
Juwelier has prepared your gem in ./snowboard_utah
Created greeter/.gitignore
Created greeter/.ruby-version
Created greeter/.ruby-gemset
Created greeter/VERSION
Created greeter/LICENSE.txt
Created greeter/Gemfile
Created greeter/Rakefile
Created greeter/app/greeter.rb
Created greeter/app/greeter/view/app_view.rb
Created greeter/package/windows/Snowboard Utah.ico
Created greeter/package/macosx/Snowboard Utah.icns
Created greeter/package/linux/Snowboard Utah.png
Created greeter/app/greeter/launch.rb
Created greeter/bin/greeter
...

Eventually, it will launch an advanced "Hello, World!" app window having the title of your application ("Greeter").

(note: javapackager might claim at the end "Error: Bundler "DMG Installer" (dmg) failed to produce a bundle.", but it's a false negative since it works fully anyways)

It also comes with a boilerplate Preferences dialog.

Here is the Windows version of the scaffolded "Greeter" app:

And, here is the Windows version of the boilerplate Preferences dialog.

In order to run the app after making changes, you can run the glimmer run. It automatically detects the generated run script under the bin directory and uses it as an argument.

glimmer run

Alternatively, to manually run the app, you may type:

jruby bin/greeter

or:

bin/greeter

or:

glimmer bin/greeter

or:

glimmer run[bin/greeter]

Desktopify

Desktopify basically turns a website into a desktop application by wrapping the website within a Browser Widget.

The desktopify app is similar to the standard scaffolded app. It can be extended and the browser may even be instrumented.

The app even remembers your cookies if you log into the website, close the app, and reopen again.

Note that on Linux, the default SWT browser, which runs on webkit, does not support HTML5 Video out of the box. If you need video support on Linux, you may try the JxBrowser SWT widget instead, which embeds Chromium instead.

Before you start, make sure you are in a JRuby environment with Glimmer gem installed as per "Direct Install" pre-requisites.

To scaffold a Glimmer desktopify app from scratch, run the following command:

glimmer scaffold:desktopify[app_name,website]

This will generate a Glimmer app, package it as a Mac DMG/PKG/APP, Windows APP, or Linux GEM, and launch it all in one fell swoop.

Suppose you run:

glimmer scaffold:desktopify[snowboard_utah,https://www.brightonresort.com]

You should see output like the following:

$ glimmer scaffold:desktopify[snowboard_utah,https://www.brightonresort.com]
  create  .gitignore
  create  Rakefile
  create  Gemfile
  create  LICENSE.txt
  create  README.markdown
  create  .document
  create  lib
  create  lib/snowboard_utah.rb
  create  .rspec
Juwelier has prepared your gem in ./snowboard_utah
Created snowboard_utah/.gitignore
Created snowboard_utah/.ruby-version
Created snowboard_utah/.ruby-gemset
Created snowboard_utah/VERSION
Created snowboard_utah/LICENSE.txt
Created snowboard_utah/Gemfile
Created snowboard_utah/Rakefile
Created snowboard_utah/app/snowboard_utah.rb
Created snowboard_utah/app/snowboard_utah/view/app_view.rb
Created snowboard_utah/package/windows/Snowboard Utah.ico
Created snowboard_utah/package/macosx/Snowboard Utah.icns
Created snowboard_utah/package/linux/Snowboard Utah.png
Created snowboard_utah/app/snowboard_utah/launch.rb
Created snowboard_utah/bin/snowboard_utah
...

Eventually, it will launch a desktopified version of "https://www.brightonresort.com" having the title of ("Snowboard Utah").

(note: javapackager might claim at the end "Error: Bundler "DMG Installer" (dmg) failed to produce a bundle.", but it's a false negative since it works fully anyways)

Desktopified App on Mac

It also comes with a boilerplate About dialog.

Desktopified App on Windows

Desktopified App on Linux

In order to run the app after making changes, you can run the glimmer run. It automatically detects the generated run script under the bin directory and uses it as an argument.

glimmer run

Custom Shell

To scaffold a Glimmer custom shell (full window view) for an existing Glimmer app, run the following command:

glimmer scaffold:customshell[name]

Or the following alternative abbreviation:

glimmer scaffold:cs[name]

Custom Widget

To scaffold a Glimmer custom widget (part of a view) for an existing Glimmer app, run the following command:

glimmer scaffold:customwidget[name]

Or the following alternative abbreviation:

glimmer scaffold:cw[name]

Custom Shape

To scaffold a Glimmer custom shape (a composite or customized shape) for an existing Glimmer app, run the following command:

glimmer scaffold:customshape[name]

Or the following alternative abbreviation:

glimmer scaffold:cp[name]

Custom Shell Gem

Custom shell gems are self-contained Glimmer apps as well as reusable custom shells. They have everything scaffolded Glimmer apps come with in addition to gem content like a Juwelier Rakefile that can build gemspec and release gems. Unlike scaffolded Glimmer apps, custom shell gem content lives under the lib directory (not app). They can be packaged as both a native executable (e.g. Mac DMG/PKG/APP) and a Ruby gem. Of course, you can just build a Ruby gem and disregard native executable packaging if you do not need it.

To scaffold a Glimmer custom shell gem (full window view distributed as a Ruby gem), run the following command:

glimmer scaffold:gem:customshell[name,namespace]

Or the following alternative abbreviation:

glimmer scaffold:gem:cs[name,namespace]

It is important to specify a namespace to avoid having your gem clash with existing gems.

The Ruby gem name will follow the convention "glimmer-cs-customwidgetname-namespace" (the 'cs' is for Custom Shell).

Only official Glimmer gems created by the Glimmer project committers will have no namespace (e.g. glimmer-cs-gladiator Ruby gem)

Since custom shell gems are both an app and a gem, they provide two ways to run:

Run the glimmer command and pass it the generated script under the bin directory that matches the gem name (e.g. run glimmer bin/glimmer-cs-calculator)
Run the executable shell script that ships with the gem directly (does not need the glimmer command). It intentionally has a shorter name for convenience since it is meant to be used on the command line (not in a package), so you can leave out the glimmer-cs- prefix (e.g. run bin/calculator directly). This is also used as the main way of running custom shell gems on Linux.

Examples:

glimmer-cs-gladiator: Gladiator (Glimmer Editor)
glimmer-cs-calculator: Glimmer Calculator

Custom Widget Gem

To scaffold a Glimmer custom widget gem (part of a view distributed as a Ruby gem), run the following command:

glimmer scaffold:gem:customwidget[name,namespace]

Or the following alternative abbreviation:

glimmer scaffold:gem:cw[name,namespace]

It is important to specify a namespace to avoid having your gem clash with existing gems.

The Ruby gem name will follow the convention "glimmer-cw-customwidgetname-namespace" (the 'cw' is for Custom Widget; name words are not separated)

Only official Glimmer gems created by the Glimmer project committers will have no namespace (e.g. glimmer-cw-video Ruby gem)

Examples:

glimmer-cw-video: Video Widget
glimmer-cw-nebula: The Nebula Project 50+ enterprise-grade high quality custom widgets for SWT
glimmer-cw-cdatetime-nebula: Nebula CDateTime Widget (piecemeal)

Custom Shape Gem

To scaffold a Glimmer custom shape gem (part of a view distributed as a Ruby gem), run the following command:

glimmer scaffold:gem:customshape[name,namespace]

Or the following alternative abbreviation:

glimmer scaffold:gem:cp[name,namespace]

It is important to specify a namespace to avoid having your gem clash with existing gems.

The Ruby gem name will follow the convention "glimmer-cp-customshapename-namespace" (the 'cp' is for Custom Shape; name words are not separated)

Only official Glimmer gems created by the Glimmer project committers will have no namespace (e.g. glimmer-cp-bevel Ruby gem)

Examples:

glimmer-cp-bevel: Bevel

Gem Listing

The glimmer command comes with tasks for listing Glimmer related gems to make it easy to find Glimmer Custom Shells, Custom Widgets, and DSLs published by others in the Glimmer community on rubygems.org.

Listing Custom Shell Gems

The following command lists available Glimmer Custom Shell Gems (prefixed with "glimmer-cs-" by scaffolding convention) created by the the Glimmer community and published on rubygems.org:

glimmer list:gems:customshell[query]

Or the following alternative abbreviation:

glimmer list:gems:cs[query]

Example:

glimmer list:gems:cs

Output:


  Glimmer Custom Shell Gems at rubygems.org:
                                                                                                                 
     Name               Gem            Version     Author                        Description
                                                                                                                 
  Calculator   glimmer-cs-calculator   1.0.2     Andy Maleh   Calculator - Glimmer Custom Shell
  Gladiator    glimmer-cs-gladiator    0.2.4     Andy Maleh   Gladiator (Glimmer Editor) - Glimmer Custom Shell
  Timer        glimmer-cs-timer        1.0.0     Andy Maleh   Timer - Glimmer Custom Shell

Listing Custom Widget Gems

The following command lists available Glimmer Custom Widget Gems (prefixed with "glimmer-cw-" by scaffolding convention) created by the the Glimmer community and published on rubygems.org:

glimmer list:gems:customwidget[query]

Or the following alternative abbreviation:

glimmer list:gems:cw[query]

Example:

Check if there is a custom video widget for Glimmer.

glimmer list:gems:cw[video]

Output:


  Glimmer Custom Widget Gems matching [video] at rubygems.org:
                                                                                   
  Name          Gem          Version     Author              Description
                                                                                   
  Video   glimmer-cw-video   1.0.0     Andy Maleh   Glimmer Custom Widget - Video

Example:

Check all custom widgets for Glimmer.

glimmer list:gems:cw

Output:


  Glimmer Custom Widget Gems at rubygems.org:
                                                                                                                                
         Name                      Gem                Version      Author                       Description
                                                                                                                                
  Browser (Chromium)   glimmer-cw-browser-chromium   1.0.0       Andy Maleh   Chromium Browser - Glimmer Custom Widget
  Cdatetime (Nebula)   glimmer-cw-cdatetime-nebula   1.5.0.0.1   Andy Maleh   Nebula CDateTime Widget - Glimmer Custom Widget
  Video                glimmer-cw-video              1.0.0       Andy Maleh   Glimmer Custom Widget - Video

Listing Custom Shape Gems

The following command lists available Glimmer Custom Shape Gems (prefixed with "glimmer-cp-" by scaffolding convention) created by the the Glimmer community and published on rubygems.org:

glimmer list:gems:customshape[query]

Or the following alternative abbreviation:

glimmer list:gems:cp[query]

Example:

glimmer list:gems:customshape

Output:


  Glimmer Custom Shape Gems at rubygems.org:
                                                                                                     
     Name                Gem             Version     Author                 Description
                                                                                                     
  Bevel         glimmer-cp-bevel         0.1.1     Andy Maleh   Bevel - Glimmer Custom Shape
  Stickfigure   glimmer-cp-stickfigure   0.1.1     Andy Maleh   Stick Figure - Glimmer Custom Shape

Listing DSL Gems

The following command lists available Glimmer DSL Gems (prefixed with "glimmer-dsl-" by convention) created by the the Glimmer community and published on rubygems.org:

glimmer list:gems:dsl[query]

Example:

glimmer list:gems:dsl

Output:


  Glimmer DSL Gems at rubygems.org:
                                                                         
  Name         Gem          Version    Author          Description
                                                                         
  Css    glimmer-dsl-css    1.1.0     AndyMaleh    Glimmer DSL for CSS
  Opal   glimmer-dsl-opal   0.10.2     AndyMaleh    Glimmer DSL for Opal
  Swt    glimmer-dsl-swt    4.18.4.4  AndyMaleh    Glimmer DSL for SWT
  Tk     glimmer-dsl-tk     0.0.6     AndyMaleh    Glimmer DSL for Tk
  Xml    glimmer-dsl-xml    1.1.0     AndyMaleh    Glimmer DSL for XML

Packaging

Glimmer supports packaging applications as native files on Mac and Windows.

Glimmer packaging tasks are detailed under Packaging & Distribution.

On Linux, the Glimmer App and Custom Shell Gem scaffolding options provide a Gem Packaged Shell Script (e.g. calculator command becomes available after installing the glimmer-cs-calculator gem)

You may run glimmer package:gem to generate gem or just rely on the included Juwelier rake release task to release the gem.

Raw JRuby Command

If there is a need to run Glimmer directly via the jruby command, you may run the following on Windows/Linux:

jruby -r glimmer-dsl-swt -S application.rb

Or, the following on Mac:

jruby -J-XstartOnFirstThread -r glimmer-dsl-swt -S application.rb

Unless you ran glimmer-setup, which adds JRUBY_OPTS environment variable that includes the -J-XstartOnFirstThread option automatically so you would not have to specify manually.

If you want to use a specific custom version of SWT, run the following on Windows/Linux:

jruby -J-classpath "path_to/swt.jar" -r glimmer-dsl-swt -S application.rb

Or, the following on Mac:

jruby -J-XstartOnFirstThread -J-classpath "path_to/swt.jar" -r glimmer-dsl-swt -S application.rb

The -J-classpath option specifies the swt.jar file path, which can be a manually downloaded version of SWT, or otherwise the one included in the gem. You can lookup the one included in the gem by running jgem which glimmer to find the gem path and then look through the vendor directory.

The -r option preloads (requires) the glimmer library in Ruby.

The -S option specifies a script to run.

Mac Support

The Mac is well supported with the glimmer command. The advice below is not needed if you are using it.

However, if there is a reason to use the raw jruby command directly instead of the glimmer command, you need to pass an extra option (-J-XstartOnFirstThread) to JRuby on the Mac (Glimmer automatically passes it for you when using the glimmer command).

Example:

jruby -J-XstartOnFirstThread -J-classpath "path_to/swt.jar" -r glimmer-dsl-swt -S application.rb

License

MIT

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

GLIMMER_COMMAND.md

GLIMMER_COMMAND.md

Glimmer Command

Basic Usage

Advanced Usage

Glimmer Samples

Scaffolding

App

Desktopify

Custom Shell

Custom Widget

Custom Shape

Custom Shell Gem

Custom Widget Gem

Custom Shape Gem

Gem Listing

Listing Custom Shell Gems

Listing Custom Widget Gems

Listing Custom Shape Gems

Listing DSL Gems

Packaging

Raw JRuby Command

Mac Support

License

Files

GLIMMER_COMMAND.md

Latest commit

History

GLIMMER_COMMAND.md

File metadata and controls

Glimmer Command

Basic Usage

Advanced Usage

Glimmer Samples

Scaffolding

App

Desktopify

Custom Shell

Custom Widget

Custom Shape

Custom Shell Gem

Custom Widget Gem

Custom Shape Gem

Gem Listing

Listing Custom Shell Gems

Listing Custom Widget Gems

Listing Custom Shape Gems

Listing DSL Gems

Packaging

Raw JRuby Command

Mac Support

License