Struct fruitbasket::Trampoline

pub struct Trampoline { /* fields omitted */ }

API to move the executable into a Mac app bundle and relaunch (if necessary)

Trampoline is a builder pattern for creating a FruitApp application instance that is guaranteed to be running inside a Mac app bundle. See the module documentation for why this is often important.

If the currently running process is already in an app bundle, Trampoline does nothing and is equivalent to calling FruitApp::new.

The builder takes a variety of information that is required for creating a Mac app (notably: app name, executable name, unique identifier), as well as optional metadata to describe your app and its interactions to the OS, and optional file resources to bundle with it. It creates an app bundle, either in an install path of your choosing or in a temporary directory, launches the bundled app, and terminates the non-bundled binary.

Care should be taken to call this very early in your application, since any work done prior to this will be discarded when the app is relaunched. Your program should also gracefully support relaunching from a different directory. Take care not to perform any actions that would prevent relaunching, such as claiming locks, until after the trampoline.

Methods

impl Trampoline

pub fn new(name: &str, exe: &str, ident: &str) -> Trampoline

Creates a new Trampoline builder to build a Mac app bundle

This creates a new Trampoline builder, which takes the information required to construct a Mac .app bundle. If your application is already running in a bundle, the builder does not create a bundle and simply returns a newly constructed FruitApp object with the Mac application environment initialized. If your application is not in a bundle, a new bundle is created and launched, and your program's current process is killed.

Arguments

name - Name for your Mac application. This is what is displayed in the dock and the menu bar.

exe - Name for the executable file in your application. This is the name of the process that executes, and what appears in ps or Activity Monitor.

ident - Unique application identifier for your app. This should be in the reverse DNS format (ex: com.company.AppName), and must contain only alpha-numerics, -, and . characters. It can be used to register your app as a system-wide handler for documents and URIs, and is used when code signing your app for distribution.

Returns

A newly constructed Trampoline builder.

pub fn name(&mut self, name: &str) -> &mut Self

Set name of application. Same as provided to new().

pub fn exe(&mut self, exe: &str) -> &mut Self

Set name of executable. Same as provided to new().

pub fn ident(&mut self, ident: &str) -> &mut Self

Set app bundle ID. Same as provided to new().

pub fn icon(&mut self, icon: &str) -> &mut Self

Set bundle icon file.

This is the name of the icon file in the Resources directory. It should be just the file name, without a path. OS X uses this icon file for the icon displayed in the Dock when your application is running, and the icon that appears next to it in Finder and the Application list.

Icons are typically provided in a multi-icon set file in the .icns format.

It is optional, but strongly recommended for apps that will be distributed to end users.

pub fn version(&mut self, version: &str) -> &mut Self

Set the bundle version.

This sets the version number in the app bundle. It is optional, and defaults to "1.0.0" if not provided.

pub fn plist_key(&mut self, key: &str, value: &str) -> &mut Self

Set an arbitrary key/value pair in the Info.plist

Bundles support specifying a large variety of configuration options in their Property List files, many of which are only needed for specific use cases. This function lets you specify any arbitrary key/value pair that your application might need.

Note that some keys are provided with a default value if not specified, and a few keys are always configured by the Trampoline builder and cannot be overridden with this function.

Trampoline creates Info.plist files in the "old-style" OpenStep format. Be sure to format your values appropriately for this style. Read up on Old-Style ASCII Property Lists. You can also verify your formatting by creating a simple test.plist with your key/value pairs in it, surround the entire file in braces ({ and }), and then run plutil test.plist to validate the formatting.

See the Apple documentation on Info.plist keys for options.

Arguments

key - Property List key to set (ex: CFBundleURLTypes)

value - Value for the key, in JSON format. You must provide quote characters yourself for any values that require quoted strings. Format in "old-style" OpenStep plist format.

pub fn plist_keys(&mut self, pairs: &Vec<(&str, &str)>) -> &mut Self

Set multiple arbitrary key/value pairs in the Info.plist

See documentation of plist_key(). This function does the same, but allows specifying more than one key/value pair at a time.

pub fn plist_raw_string(&mut self, s: String) -> &mut Self

Add a 'raw', preformatted string to Info.plist

Pastes a raw, unedited string into the Info.plist file. This is dangerous, and should be used with care. Use this for adding nested structures, such as when registering URI schemes.

MUST be in the JSON plist format. If coming from XML format, you can use plutil -convert json -r Info.plist to convert.

Take care not to override any of the keys in FORBIDDEN_PLIST unless you really know what you are doing.

pub fn resource(&mut self, file: &str) -> &mut Self

Add file to Resources directory of app bundle

Specify full path to a file to copy into the Resources directory of the generated app bundle. Resources can be any sort of file, and are copied around with the app when it is moved. The app can easily access any file in its resources at runtime, even when running in sandboxed environments.

The most common bundled resources are icons.

Arguments

file - Full path to file to include

pub fn resources(&mut self, files: &Vec<&str>) -> &mut Self

Add multiple files to Resources directory of app bundle

See documentation of resource(). This function does the same, but allows specifying more than one resource at a time.

pub fn build(&mut self, dir: InstallDir) -> Result<FruitApp, FruitError>

Finishes building and launching the app bundle

This builds and executes the "trampoline", meaning it is a highly destructive action. A Mac app bundle will be created on disk if the program is not already executing from one, the new bundle will be launched as a new process, and the currently executing process will be terminated.

The behavior, when used as intended, is similar to fork() (except the child starts over from main() instead of continuing from the same instruction, and the parent dies). The parent dies immediately, the child relaunches, re-runs the Trampoline builder, but this time it returns an initialized FruitApp.

WARNING: the parent process is terminated with exit(0), which does not Drop your Rust allocations. This should always be called as early as possible in your program, before any allocations or locking.

Arguments

dir - Directory to create app bundle in (if one is created)

Returns

• Result<_, FruitError> if not running in a bundle and a new bundle could not be created.
• Result<_, FruitError> if running in a bundle but the Mac app environment could not be initialized.
• Terminates the process if not running in a Mac app bundle and a new bundle was successfully created.
• Result<FruitApp, _> if running in a Mac bundle (either when launched from one initially, or successfully re-launched by Trampoline) containing the initialized app environment,

pub fn is_bundled() -> bool

Returns whether the current process is running from a Mac app bundle

pub fn self_bundle(&self, dir: InstallDir) -> Result<(), FruitError>

Same as build, but does not construct a FruitApp if successful.

Useful if you'd like to use a GUI library, such as libui, and don't want fruitbasket to try to initialize anything for you. Bundling only.

Trait Implementations

impl Default for Trampoline

fn default() -> Trampoline

Returns the "default value" for a type.