Custom Install Scripts

This feature may appear in Shoes 3.3.1, depending on demand. What's shown and described does work but it needs a lot of testing and some real applications that could test it and propose improvements.

This feature is also called Secondary Packaging and is intended for Shoes script writers to manage how their Shoes script in installed in the end user's system. Without this feature, a packaged script is installed it will check if Shoes is already installed. If not, it will either download Shoes and install that (dnlif - Download If Needed) or install a copy of Shoes that was in the included with the script (Include Shoes, aka repack). Then Shoes is used to run the script/shy. That works but it is lacking in some flexibility.

For instance. If you have a shy that contains your scripts and data files and writes to those data file are lost when the script exits or crashes because the shy is not permanent storage. So you have to write code that determines that it is being installed and move things around before it can get running. That's something of pain to figure out in Shoes. What if you could write a install script that only runs once, when the shy is installed and it could move files around, create icons associations, set up menus and other things just like a real app installer would do. Stuff you don't want to deal with. So this feature does that. It provides a default secondary install script with some platform specific ways to those things. Of course you could modify the default secondary install script or write your own.

Lets say your app has an myicon.png you use to set_window_icon and a another Ruby file of helper methods or Shoe and and Sqllite3. Currently inside your myapp.exe it looks like this:

myapp.exe/
  -- Shoes.install.exe (dnlif or repack, 100kb or 12 MB)
  -- Shoes.rsrc (Walkabout icons) 
  -- myapp.shy/
    -- myapp.yaml -- you can't see this normally
    -- mymain.script
    -- helper.script
    -- myapp-icon.png
    -- mysql.db

OSX and Linux differ only in those resource files. Conceptually the same. With custom or secondary packaging is your shy is enclosed in another shy.

myapp.exe/
  -- Shoes.install.exe (dnlif or repack, 100kb or 12 MB)
  -- Shoes.rsrc (these are Walkabout icons)
  -- custom.shy/
    -- installer.yaml
    -- installer_script.rb
    -- installer.ico
    -- installer.icns
    -- installer.png
    -- myapp.shy/
      -- myapp.yaml 
      -- mymain.script
      -- helper.script
      -- myapp-icon.png
      -- mysql.db

Now at install time, Shoes unpacks custom.shy and runs installer_script.rb. It's job is to unpack myapp.shy, use those installer icons to setup menus, short cuts, OSX.app structure, move your mysql.db to some place permanent and otherwise create an app for the user. How does it know what to do?

Wait for it...

It's a Shoes.app running in Shoes! It can ask the user where to put things and you as developer can supply defaults. Preloaded databases and what ever Shoes can do.

Lets peek at the using these features using my example app: Ytm, aka Yield To Maturity which computes bond yields and saves them in a csv file. It would, but it's just a example app and some functions don't work, the calculations may be wrong. Yes, it should use Sqlite. It's only an example. Heres what's inside the ~/Projects/ytm directory

ytm.shy
-- foo.csv
-- foo/rb
-- quote.rb       helper script to get quotes 
-- README.txt
-- TODO.txt
-- ytm.png        The icon we should use for our windows
-- ytm.rb         The Shoes script. Our App.
-- ytmsec.csv     Our db. 
-- ytmsec.csv.sav Our db backup

Like I said before, we don't want that ytmsec.csv database to vanish and it needs to be in a place that normal users can write too. We want to ask the user where to put those files and we'll rejigger some sort of .lnk (windows), app (osx), or menu entry (linux) that will live in the user specified directory. Pay attention to the screen shot:

What the hell is are Gempacks

That Mandatory png is the icon the Installer will display. In case you want the installer icon to be different than the app's icon. Since the secondary installer is a Shoes app, that icon has to be a png. For every platform. If you are creating your own icons, this is not a big problem.

Custom install scripts are really hard to debug if they are cross platform. If the default is not to your liking, you can clone static/stubs/app-install.tmpl and create your own installer.

You also have attach an ico, icns, or png for the Architecture you're going to package for. You can add all three if you like. This WILL NOT convert one icon format to another. The default installer will complain when its run if it can't find the format it wants.

Here's the default custom installer for that ytm.shy on Linux (raspbian) - Notice the installer icon on the window is the older Federales icon because I'm too lazy to create an installer only png icon.

Some things to note.

• It's Linux. The app will get a menu installed in the Office category. If we're lucky.
• The install screen displays the strings given when ytm.shy was created

OSX is a bit different. There are no options unless you have a gempack.

Note: on OSX, for a custom/secondary installer, download if needed (dnlif) or include Shoes (repack) there will be a Shoes.app created in /Applications. This is different, more Windows-like than packaging Shoes for OSX without a second level installer. If the end user does have /Applications/Shoes.app then the secondary installer will use it or create it.

Windows has options. Of course. Let us consider:

Create a desktop shortcut for your app should make sense. It's just a .lnk file.

Delete Shoes from desktop. Users choice (according to the default secondary installer) - it's just .lnk. It wont remove Shoes from the Start menus (that would require registry magic - which you could invoke in your own custom install script - every thing you need is already in Shoes or Ruby libs if you want to poke the registry)

The checkbox for install gems appeared because that download was packaged with a Gempacks. That will happen for OSX and Linux too.

Here's the Ytm running

Some thoughts

If you choose to use secondary packaging then It's your job to manage your dependencies and user install experience. Study the default packaging script (you'll have it in static/stubs/app-install.tmpl) which you can copy to be your custom installer). Don't like my defaults? Do it your way. I encourage it. Put up your own background image for the installer. Make it pretty, your way. It's just a Shoes script. Your script. Will your app need changes if you use secondary installing. Probably.

I strongly recommend you get familiar with lib/shoes/packshoes and use the Command-line-packager because it is very easy to make mistakes with the Packager GUI. The command line version is much faster and your choice of files is documented.