Command line packager

Note: this is subject to change. - adding new options or changing the names or new yaml fields. This note is based on Shoes 3.3.1 r2353 (Feb 5, 2016)

Packaging from the command line

Packaging from the GUI involves lots of button clicks and testing and redoing. It's a bit of a pain if you want to automate your development. You can create a couple of small Ruby scripts that you run from the command line using the --ruby option (cshoes.exe --ruby scriptname.rb for the Windows brethren)

Shy files

You probably want to create a .shy unless your project is exactly one .rb file. A .shy is bit of magic binary numbers followed by some yaml followed by a tar ball. The yaml has fields. Here's and example of a script that creates a shy.

require 'shoes/packshoes'
shydesc = {}
shyfile = File.join("/","tmp", "shy", "ytm.shy")
shydesc['name'] = 'Yield to Maturity'
shydesc['version'] = '0.123'
shydesc['creator'] = 'the mighty OZ'
shydesc['launch'] = 'ytm.rb'
PackShoes.make_shy(shyfile, '/home/ccoupe/Projects/ytm', shydesc)

shyfile

This is the file to create. In the example, it's /tmp/shy/ytm.shy. Do not put it in the same directory or a subdirectory of that your shy-ing up. Don't do that unless you have infinite time and disk space. You don't have either.

shydesc

The name, version and creator values are pretty much ignored (that won't be true in future Shoes) so pick something that your users will understand if the see it displayed).

launch is the startup script in the directory that Shoes will run when the shy is executed on their system.

make_shy

The arguments should be apparent. The first is the absolute path of the .shy to create. The second argument is the directory/folder to package up into the .shy and the third argument is the desc hash.

Packaging

Now, I'm going to describe the script you write to drive packaging. After you created a .shy file if that's what your app needs. The 'test.rb' below just has one ruby script. Shoes only packs one file - a .rb or a .shy.

What's in the test.rb? Basically you require the packshoes.rb, fill out an platform specific opts hash and call one of the methods in PackShoes. There are many caveats, bewares and huh? . Please study lib/shoes/packshoes.rb in your Shoes. Below is an example and of course it's very specific to my demo app and build system.

require 'shoes/packshoes'
opts = {}
opts['app'] = '/home/ccoupe/Projects/ytmtest/ytm-repack.shy'
opts['advopts'] =  true
opts['expandshy'] = true
#opts['custominstaller'] = '/full/path/to/my/install_script.rb'
opts['installer-icon'] = '/home/ccoupe/Projects/shoes3/static/shoes-icon-federal
es.png'
opts['png'] = '/home/ccoupe/Projects/icons/ytm/ytm.png'
opts['ico'] = '/home/ccoupe/Projects/icons/ytm/ytm.ico'
opts['icns'] = '/home/ccoupe/Projects/icons/ytm/ytm.icns'
#opts['gempack'] = '/home/ccoupe/Projects/gems/gempacks/kevin.tar.gz'
opts['arch'] = 'x86_64' # win32 armhf x86_64 i686 or osx
opts['dnlhost'] = 'walkabout.mvmanila.com'  # no http://
opts['dnlpath'] = "/public/select/#{opts['arch']}.rb"
opts['shoesdist'] = "/home/ccoupe/.shoes/walkabout/package/shoes-3.3.1-gtk3-x86_
64.install"
opts['packtmp'] = '/home/ccoupe/.shoes'
opts['relname'] = 'walkabout'
PackShoes.repack_linux opts

Since we're using a hash, the order doesn't really matter but I'm going to start the discussion with minimal settings. Many of those above are not minimal

opts['app']

Is the full pathname to the script (or .shy) to package. Frankly you're going to want to use a shy to do anything useful for the end user. I've shown a script to could use to package a .shy above or you could do it from the Shoes Gui. Remember. you can package a shy as a Download If Needed (dnlif) or "Include Shoes" (repack).

opts['dnlhost'] and opts['dnlpath']

Is where to download the Shoes distribution from. This is passed into the stub that runs on the users system dnlpath is the cgi script to run at dnlhost. That will return a full shoes.exe (or osx tgz or linux.install) that will be installed if needed.

opts['shoesdist']

Is a the full path to the where Shoes previously downloaded the Shoes.exe you want to repack. In Windows, it will be in HOME\AppData\ probably AppData\shoes\walkabout\package (~/.shoes/walkabout for OSX and Linux) but you'll want to verify that for yourself. It's important to have your choice downloaded first if you do a repack. Easy to do with the packager GUI - just pack (anything) for the architecture you want and if you don't have in walkabout/package the GUI will download the latest.

opts['relname']

I'm not sure if this used or not. Won't hurt to include it.

opts['winargs']

This is optional and only applies to Shoes 3.2.23 or newer and only for Windows. opts['winargs']='--console' causes the packaged app to open a command window along with the Shoes app windows. Handy if your app uses Ruby puts and/or C printfs and you want the user to see them. The console window is closed when the Shoes app is terminated.

This will be deprecated soon because if you need this, you can call Shoes::shoe_console in your script and that is cross platform and not Windows specific.

which method in PackShoes?

dnlif_exe, repack_exe, dnlif_osx, repack_osx, dnlif_linux, repack_linux.

You can add a block to the repack_??? calls but other than printing the progress messages it not very useful.

arch

You do need to set this for whatever your packaging for. Particularly if it's dnlif. Values are 'win32' 'armhf' 'x86_64' 'i686' or 'osx'

packtmp

At this point in time, there is no default. Its a place or your computere to dissemble the downloaded, create shy things, and reassemble them. After packaging, this may or may not be deleted.

What about those other opts[values]?

Those are for folks that want more control. opts['advopts'] is your gateway. If it's set false or not given you still have some icons setting ability. See Custom-Install-Scripts

Icons

The default for icons in the download and install by your users are the silly Shoes icons. There is no way to change them in the GUI but if you want your icons in the exe or attached to your OSX.app you can do do by specifying

opts['ico'] = "/full/path/to/myapp.ico'  # Windows
opts['icns'] = "/full/path/to/myapp.icns" # OSX
opts['png'] = "/fuul/path/to/myapp.png"  # Linux

If you have gone to the trouble of creating you own icon, you might as well create and include all three and include them in your packaging script. See Creating-Icons

opts['advopts'] = true

Beware of magic ahead. This choice will package your .shy inside another installer shy. Your shy is the inner shy. When your app is installed on the users system, Shoes will will run a script in the outer outer shy. We supply a default script, but you can supply your own. That script should be a Shoe script. The following options will only work if you have opts['advopts'] = 'true'

opts['gempack']

One thing you can include in that outer shy is a gem pack which is a pre-built set of gems for the architecture of your choice. See Gempacks

opts['expandshy']

When set to 'true' your 'inner shy' will be expanded at install time and it will be copied to a user given location. (default script behavior)

opts['installer-icon']

Some times your app icon needs to be different from your installer icon. This png is displayed by the default 2nd level installer.

opts['custominstaller'] = '/path/to/myapp-installer.rb'

If you've looked at the default custom installer (static/stubs/app-install.tmpl), you're probably said "what a dogs mess for breakfast!, I don't need that cross platform crap for my app! It's thirteen ways to Sunday ugly!" Then you can provide your own script here. We don't mind. We won't even know.