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:
- The
Contents/Info.plist
must contain some required keys defining the bundle. Callset_info_plist_required_keys()
to ensure these are defined. - There must be an executable file in the
Contents/MacOS
directory. Add one viaadd_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
impl MacOsApplicationBundleBuilder
Sourcepub fn new(bundle_name: impl ToString) -> Result<Self>
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.
Sourcepub fn files(&self) -> &FileManifest
pub fn files(&self) -> &FileManifest
Obtain the raw FileManifest backing this builder.
Sourcepub fn bundle_name(&self) -> Result<String>
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.
Sourcepub fn info_plist(&self) -> Result<Option<Dictionary>>
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.
Sourcepub fn add_file(
&mut self,
path: impl AsRef<Path>,
entry: impl Into<FileEntry>,
) -> Result<(), FileManifestError>
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.
Sourcepub fn set_info_plist_from_dictionary(
&mut self,
value: Dictionary,
) -> Result<()>
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).
Sourcepub fn get_info_plist_key(&self, key: &str) -> Result<Option<Value>>
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.
Sourcepub fn set_info_plist_key(
&mut self,
key: impl ToString,
value: impl Into<Value>,
) -> Result<Option<Value>>
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.
Sourcepub 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<()>
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.
Sourcepub fn add_icon(&mut self, data: impl Into<FileEntry>) -> Result<()>
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.
Sourcepub fn add_file_macos(
&mut self,
path: impl AsRef<Path>,
entry: impl Into<FileEntry>,
) -> Result<(), FileManifestError>
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/
.
Sourcepub fn add_file_resources(
&mut self,
path: impl AsRef<Path>,
entry: impl Into<FileEntry>,
) -> Result<(), FileManifestError>
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/
Sourcepub fn add_localized_resources_file(
&mut self,
locale: impl ToString,
path: impl AsRef<Path>,
entry: impl Into<FileEntry>,
) -> Result<(), FileManifestError>
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.
Sourcepub fn add_file_frameworks(
&mut self,
path: impl AsRef<Path>,
entry: impl Into<FileEntry>,
) -> Result<(), FileManifestError>
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/
.
Sourcepub fn add_file_plugins(
&mut self,
path: impl AsRef<Path>,
entry: impl Into<FileEntry>,
) -> Result<(), FileManifestError>
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/
.
Add a file to the Contents/SharedSupport/
directory.
The passed path will be prefixed with Contents/SharedSupport/
.
Sourcepub fn materialize_bundle(&self, dest_dir: impl AsRef<Path>) -> Result<PathBuf>
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
impl Clone for MacOsApplicationBundleBuilder
Source§fn clone(&self) -> MacOsApplicationBundleBuilder
fn clone(&self) -> MacOsApplicationBundleBuilder
1.0.0 · Source§fn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
source
. Read more