apple_bundles

Struct MacOsApplicationBundleBuilder

Source
pub struct MacOsApplicationBundleBuilder { /* private fields */ }
Expand description

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§

Source§

impl MacOsApplicationBundleBuilder

Source

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.

Source

pub fn files(&self) -> &FileManifest

Obtain the raw FileManifest backing this builder.

Source

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.

Source

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.

Source

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.

Source

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).

Source

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.

Source

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.

Source

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.

Source

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.

Source

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/.

Source

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/

Source

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.

Source

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/.

Source

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/.

Source

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/.

Source

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§

Source§

impl Clone for MacOsApplicationBundleBuilder

Source§

fn clone(&self) -> MacOsApplicationBundleBuilder

Returns a copy of the value. Read more
1.0.0 · Source§

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

Performs copy-assignment from source. Read more
Source§

impl Debug for MacOsApplicationBundleBuilder

Source§

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

Formats the value using the given formatter. Read more

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dst: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dst. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = Infallible

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.