Struct MacOsApplicationBundleBuilder

pub struct MacOsApplicationBundleBuilder { /* private fields */ }

Primitive used to iteratively construct a macOS Application Bundle.

Under the hood, the builder maintains a list of files that will constitute the final, materialized bundle. There is a low-level add_file() API for adding a file at an explicit path within the bundle. This gives you full control over the content of the bundle.

There are also a number of high-level APIs for performing common tasks, such as defining required bundle metadata for the Contents/Info.plist file and adding files to specific locations. There are even APIs for performing lower-level manipulation of certain files, such as adding keys to the Content/Info.plist file.

Apple’s documentation on the bundle format is very comprehensive and can answer many questions. The most important takeaways are:

1. The Contents/Info.plist must contain some required keys defining the bundle. Call set_info_plist_required_keys() to ensure these are defined.
2. There must be an executable file in the Contents/MacOS directory. Add one via add_file_macos().

This type attempts to prevent some misuse (such as validating Info.plist content) but it cannot prevent all misconfigurations.

Examples

use apple_bundles::MacOsApplicationBundleBuilder;
use simple_file_manifest::FileEntry;

let mut builder = MacOsApplicationBundleBuilder::new("MyProgram")?;

// Populate some required keys in Contents/Info.plist.
builder.set_info_plist_required_keys("My Program", "com.example.my_program", "0.1", "mypg", "MyProgram")?;

// Add an executable file providing our main application.
builder.add_file_macos("MyProgram", FileEntry::new_from_data(b"#!/bin/sh\necho 'hello world'\n".to_vec(), true))?;

Implementations

impl MacOsApplicationBundleBuilder

pub fn new(bundle_name: impl ToString) -> Result<Self>

Create a new macOS Application Bundle builder.

The bundle will be populated with a skeleton Contents/Info.plist file defining the bundle name passed.

pub fn files(&self) -> &FileManifest

Obtain the raw FileManifest backing this builder.

pub fn bundle_name(&self) -> Result<String>

Obtain the name of the bundle.

This will parse the stored Contents/Info.plist and return the value of the CFBundleName key.

This will error if the stored Info.plist is malformed, is missing a key, or the key has the wrong type. Errors should only happen if the file was explicitly stored or the value of this key was explicitly defined to the wrong type.

pub fn info_plist(&self) -> Result<Option<Dictionary>>

Obtain the parsed content of the Contents/Info.plist file.

Returns Some(T) if a Contents/Info.plist is defined or None if not.

Returns Err if the file content could not be resolved or fails to parse as a plist dictionary.

pub fn add_file( &mut self, path: impl AsRef<Path>, entry: impl Into<FileEntry>, ) -> Result<(), FileManifestError>

Add a file to this application bundle.

The path specified will be added without any checking, replacing an existing file at that path, if present.

pub fn set_info_plist_from_dictionary( &mut self, value: Dictionary, ) -> Result<()>

Set the content of Contents/Info.plist using a plist::Dictionary.

This allows you to define the Info.plist file with some validation since it goes through a plist serialization API, which should produce a valid plist file (although the contents of the plist may be invalid for an application bundle).

pub fn get_info_plist_key(&self, key: &str) -> Result<Option<Value>>

Obtain the value of a key in the Contents/Info.plist file.

Returns Some(Value) if the key exists, None otherwise.

May error if the stored Contents/Info.plist file is malformed.

pub fn set_info_plist_key( &mut self, key: impl ToString, value: impl Into<Value>, ) -> Result<Option<Value>>

Set the value of a key in the Contents/Info.plist file.

This API can be used to iteratively build up the Info.plist file by setting keys in it.

If an existing key is replaced, Some(Value) will be returned.

pub fn set_info_plist_required_keys( &mut self, display_name: impl ToString, identifier: impl ToString, version: impl ToString, signature: impl ToString, executable: impl ToString, ) -> Result<()>

Defines required keys in the Contents/Info.plist file.

The following keys are set:

display_name sets CFBundleDisplayName, the bundle display name. identifier sets CFBundleIdentifier, the bundle identifier. version sets CFBundleVersion, the bundle version string. signature sets CFBundleSignature, the bundle creator OS type code. executable sets CFBundleExecutable, the name of the main executable file.

pub fn add_icon(&mut self, data: impl Into<FileEntry>) -> Result<()>

Add the icon for the bundle.

This will materialize the passed raw image data (can be multiple formats) into the Contents/Resources/<BundleName>.icns file.

pub fn add_file_macos( &mut self, path: impl AsRef<Path>, entry: impl Into<FileEntry>, ) -> Result<(), FileManifestError>

Add a file to the Contents/MacOS/ directory.

The passed path will be prefixed with Contents/MacOS/.

pub fn add_file_resources( &mut self, path: impl AsRef<Path>, entry: impl Into<FileEntry>, ) -> Result<(), FileManifestError>

Add a file to the Contents/Resources/ directory.

The passed path will be prefixed with Contents/Resources/

pub fn add_localized_resources_file( &mut self, locale: impl ToString, path: impl AsRef<Path>, entry: impl Into<FileEntry>, ) -> Result<(), FileManifestError>

Add a localized resources file.

This is a convenience wrapper to add_file_resources() which automatically places the file in the appropriate directory given the name of a locale.

pub fn add_file_frameworks( &mut self, path: impl AsRef<Path>, entry: impl Into<FileEntry>, ) -> Result<(), FileManifestError>

Add a file to the Contents/Frameworks/ directory.

The passed path will be prefixed with Contents/Frameworks/.

pub fn add_file_plugins( &mut self, path: impl AsRef<Path>, entry: impl Into<FileEntry>, ) -> Result<(), FileManifestError>

Add a file to the Contents/Plugins/ directory.

The passed path will be prefixed with Contents/Plugins/.

pub fn add_file_shared_support( &mut self, path: impl AsRef<Path>, entry: impl Into<FileEntry>, ) -> Result<(), FileManifestError>

Add a file to the Contents/SharedSupport/ directory.

The passed path will be prefixed with Contents/SharedSupport/.

pub fn materialize_bundle(&self, dest_dir: impl AsRef<Path>) -> Result<PathBuf>

Materialize this bundle to the specified directory.

All files comprising this bundle will be written to a directory named <bundle_name>.app in the directory specified. The path of this directory will be returned.

If the destination bundle directory exists, existing files will be overwritten. Files already in the destination not defined in this builder will not be touched.

Trait Implementations

impl Clone for MacOsApplicationBundleBuilder

fn clone(&self) -> MacOsApplicationBundleBuilder

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for MacOsApplicationBundleBuilder

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.