Simplifying Macintosh for developers

Codesign guide: Changes for MacOS Sierra (10.12)

2016-09-27T09:04:00.004-07:00

If you are facing any problems on MacOS Sierra (10.12) related to codesigning, it might be one of the cases mentioned below. Check out the common problems and how to fix them to be fully compliant with MacOS Sierra-

Problem: Application launched from dmg is not working properly after downloading dmg from web.

Solution: Starting with MacOS Sierra, running a newly-downloaded app from a disk image, archive, or the Downloads directory will cause Gatekeeper to isolate that app at an unspecified read-only location in the filesystem. This will prevent the app from accessing code or content using relative paths.
Sign your disk images so that Gatekeeper can verify it when it is mounted for the first time.

----------------------------------------------------------------------------------------------------------------------

Problem: How can I sign a dmg file?

Solution: Disk images can be signed using the codesign tool on MacOS 10.11.5 and later. This allows the entire disk image to be validated by Gatekeeper the first time it is mounted.
Gatekeeper will validate the contents of the disk image as well.
Disk images should only be signed with your Developer ID Application identity.

----------------------------------------------------------------------------------------------------------------------

Problem: How can I verify the signature of my dmg file?

Solution: On MacOS Sierra and later, spctl can be used to assess a disk image's signature, like this:

$ spctl -a -t open --context context:primary-signature -v MyImage.dmg
/Users/me/Downloads/MyImage.dmg: accepted
source=Developer ID

----------------------------------------------------------------------------------------------------------------------

Problem: Can I sign ISO images?

Solution: No, there is no provision for signing these. Preferably, do not ship apps using ISO images.

----------------------------------------------------------------------------------------------------------------------

Problem: Is it possible to resign a dmg that is already signed?

Solution: A disk image signed on OS X 10.11.5 or 10.11.6 may not be able to be re-signed. In this situation, the operation will appear to succeed, but the signature will be invalid. If you encounter this condition, sign a new (unsigned) copy of the image on MacOS Sierra or later.

----------------------------------------------------------------------------------------------------------------------

Problem: Does Gatekeeper verify my app everytime it is launched?

Solution: On MacOS Sierra and later, Gatekeeper will check your app every time it's launched if it is run from the location where it was downloaded. If it is copied to some other directory (like /Applications), then the checks are not repeated again.

----------------------------------------------------------------------------------------------------------------------

References/Useful links:
https://developer.apple.com/library/prerelease/content/technotes/tn2206/_index.html
https://macinstallers.blogspot.in/2014/08/codesign-mavericks-yosemite-commands.html

Codesign on Mavericks/Yosemite: Some useful commands

2014-08-29T11:56:00.001-07:00

Recently, Apple announced that from 10.9.5 and 10.10 onwards, the apps signed in OSX Mountain Lion and below will not be able to pass the Gatekeeper. Those signatures (v1) will be considered deprecated and you must sign your apps in 10.9 or above to have latest signature (v2).
At this point of time, it is unclear if Apple is really going to block the apps with v1 signatures. We can’t be sure until we have a GM build for OSX Yosemite. Anyway, it is better to start signing on 10.9 straightaway so that our apps are compliant to the changes done by Apple.
Following are some commands that may be useful:
Verify if any app will be accepted by Gatekeeper on 10.9.5 (OSX Mavericks) /10.10 (OSX Yosemite) or above.

vikrams-macbook-pro:~ admin$ spctl -a -t exec -vv Foo.app
Foo.app: rejected
source=obsolete resource envelope

vikrams-macbook-pro:~ admin$ spctl -a -t exec -vv Foo.app
Foo.app: accepted
source=Developer ID
origin=Developer ID Application: My Company

Sign an app:

codesign  --sign  “Developer ID Application: My Company”  Foo.app

Resign an already signed app (Use –f flag):

codesign  --force --sign  “Developer ID Application: My Company”  Foo.app

Check the version of the signature. See the line starting with "Sealed Resources". There, version=2 indicates that this app has the new signature type as suggested by Apple:

vikrams-macbook-pro:~ admin$ codesign -dvvv Foo.app 
Executable=Foo.app/Contents/MacOS/Foo
Identifier=com.vikrams.testapp
Format=bundle with Mach-O thin (x86_64)
CodeDirectory v=20200 size=42914 flags=0x0(none) hashes=2138+3 location=embedded
Hash type=sha1 size=20
CDHash=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Signature size=7589
Authority=Developer ID Application: My Company
Authority=Developer ID Certification Authority
Authority=Apple Root CA
Timestamp=23-Aug-2014 4:32:13 pm
Info.plist entries=17
TeamIdentifier=31ACEW5CBX
Sealed Resources version=2 rules=12 files=137
Internal requirements count=1 size=192

You can find more options for "codesign" command at its man page.

PackageMaker and OSX Mavericks

2014-08-21T10:25:00.001-07:00

Recently, I tried to use PackageMaker.app on OSX Mavericks and the result was a crash. The version I was using was 3.0.5. During the launch, PackageMaker crashed with following crash log.

Process:         PackageMaker [338]
Path:            /Volumes/VOLUME/Developer/AuxiliaryTools/PackageMaker.app/Contents/MacOS/PackageMaker
Identifier:      com.apple.PackageMaker
Version:         ???
Build Info:      PackageMaker-196001000000000~606
Code Type:       X86 (Native)
Parent Process:  launchd [155]
Responsible:     PackageMaker [338]
User ID:         501

Date/Time:       2014-08-21 21:59:14.963 +0530
OS Version:      Mac OS X 10.9.4 (13E28)
Report Version:  11
Anonymous UUID:  B98E910E-EB57-50EB-B983-9297F16941A0

Sleep/Wake UUID: 3DE16912-3893-4886-B367-0331B7A52488

Crashed Thread:  0

Exception Type:  EXC_BREAKPOINT (SIGTRAP)
Exception Codes: 0x0000000000000002, 0x0000000000000000

Application Specific Information:
dyld: launch, loading dependent libraries

Dyld Error Message:
  Library not loaded: /System/Library/PrivateFrameworks/DSObjCWrappers.framework/Versions/A/DSObjCWrappers
  Referenced from: /Volumes/VOLUME/Developer/AuxiliaryTools/PackageMaker.app/Contents/MacOS/PackageMaker
  Reason: image not found

Binary Images:
0x8fe9e000 - 0x8fed0417  dyld (239.4) <FF5ED937-CC28-3FEF-BCAF-750B1CDBAE36> /usr/lib/dyld
0x906b1000 - 0x9085dfff  com.apple.QuartzCore (1.8 - 332.3) <DA347693-5E26-3E47-A2B3-3824C52EB08B> /System/Library/Frameworks/QuartzCore.framework/Versions/A/QuartzCore
0x9085e000 - 0x9086cff7  libz.1.dylib (53) <858B4D9F-D87E-3D81-B07A-DF9632BD185F> /usr/lib/libz.1.dylib
0x93f71000 - 0x93fb1ff7  com.apple.bom (14.0 - 193.1) <FFF1C8E5-41FF-357B-8681-69B21DCED2E4> /System/Library/PrivateFrameworks/Bom.framework/Versions/A/Bom
0x9408e000 - 0x9417aff7  libxml2.2.dylib (26) <32040145-6FD6-3AD2-B98B-39F73BF9AC47> /usr/lib/libxml2.2.dylib
0x963cd000 - 0x963cdfff  com.apple.Cocoa (6.8 - 20) <407DC9E6-BBCE-3D34-9BBB-00C90584FFDF> /System/Library/Frameworks/Cocoa.framework/Versions/A/Cocoa

If you also faced a similar issue, please download the new version of PackageMaker application from Apple download center. It comes bundled inside the package named "Auxiliary Tools for Xcode". Make sure you are downloading the Auxiliary Tools dmg that came out in late July 2012. It has PackageMaker 3.0.6 which works fine on Mavericks and hopefully on Yosemite as well (though I didn't try on Yosemite).
Hope that solved your problem.

Removing dock icon using Cocoa

2014-03-09T10:07:00.000-07:00

Sometimes there is a need of removing a dock icon programmatically. In such cases, there are third party utilities like dockutil, available to do the task. However, there was a problem in OSX Mavericks (Mac 10.9) where dockutil failed to remove the icon from the dock. [Update: The issue in dockutil is fixed in their latest version]
If any of you faced a similar issue, you can use the Cocoa APIs to remove the dock icon right from your code. See the sample code below-

-(void) removeDockIcon: (NSString*) dockIconName
{ 
 NSUserDefaults *userDefaults = [NSUserDefaults standardUserDefaults];

 NSDictionary* dockDict = [userDefaults persistentDomainForName:@"com.apple.dock"];

 NSMutableArray* apps = [dockDict valueForKey:@"persistent-apps"];
 if (apps != nil)
 { 
  NSArray* appsCopy = [apps copy];
  bool modified = NO;
  for(NSDictionary *anApp in appsCopy)
  {
   NSDictionary* fileDict = [anApp valueForKey:@"tile-data"];
   if(fileDict != nil)
   {
    NSString *appName = [fileDict valueForKey:@"file-label"];

    if([dockIconLabel isEqualToString:appName])
    {
     [apps removeObject:anApp];
     modified = YES;
     break;
    }
   }
  }
  if(modified)
  {
   //If the dictionary was modified, save the new settings.
   [userDefaults setPersistentDomain:dockDict forName:@"com.apple.dock"];
   //Reset the standardUserDefaults so that the modified data gets synchronized
   //and next time when this function is invoked, we get the up-to-date dock icon details.
   [NSUserDefaults resetStandardUserDefaults];
  }
 }
}

NOTE: It is a sample code written when I didn't have access to my Mac. Please do the necessary cleanup and fix syntax errors if any.
UPDATE: dockutil now has the fix for this issue. https://github.com/kcrawford/dockutil

Take awesome screenshots on Mac

2014-01-10T20:27:00.001-08:00

Well, do you know Mac offers some really easy ways of capturing full or parts of its screen. Just with the click of some buttons, you can get the screenshot of a window, the full screen or just some part of the screen.

Pictures of the screen (screenshots) are saved as files on the desktop, but if you prefer to put a screenshot in the Clipboard, hold down the Control key while you press the other keys. You can then paste the picture into a document.

Action	Shortcut
Take a picture of the whole screen	Command (⌘)-Shift-3
Take a picture of part of the screen	Command (⌘)-Shift-4, and then drag the crosshair pointer to select the area. Continue to press the mouse button, release the keys, and then press Shift, Option, or the Space bar while you drag to resize the selection area. When you are ready to take a picture, release the mouse button. To cancel, press Escape before you release the mouse button.
Take a picture of a window or the menu bar	Command (⌘)-Shift-4, press the Space bar, move the camera pointer over the area to highlight it, and then click. To cancel, press Escape before you click.
Take a picture of a menu, including the title	Click the menu to display the menu commands, press Command (⌘)-Shift-4, and drag the crosshair pointer over the area. To cancel, press Escape before you click.
Take a picture of the menu without its title	Click the menu to display the menu commands, press Command (⌘)-Shift-4, press the Space Bar, move the camera pointer over the menu to highlight it, and then click. To cancel, press Escape before you click.

Inside Distribution.dist file

2013-01-29T07:58:00.000-08:00

Inside Packagemaker Distribution.dist file

So now, you must be familiar with component and distribution packages. This post will cover everything about the ‘Distribution’ file contained inside every distribution package. This file has all the information about the behavior of the package (both visually and in terms of workflow). You can mention the background, License, Read Me files along with Installation-Check and Volume-Check. You can find the list of all the attributes which you can use inside Distribution file at DistributionDefinitionReference.

Below is an example of a valid distribution file: (Comments are provided inline)

-----------------------------------------------------------------------------------------------------------------------------------------------

<?xml version="1.0" ?>
<installer-script authoringTool="" authoringToolBuild="" authoringToolVersion="" minSpecVersion="1.000000">
<title>My Distribution Package</title>
<options allow-external-scripts="no" customize="allow"/>
<domains enable_localSystem="true"/>
<installation-check script="CustomInstallationCheck();"/>

<script>

function CheckIfLeopardOrHigher()
{

retVal = true;
SnowLeopardOrHigher = system.compareVersions(my.target.systemVersion.ProductVersion, '10.6');
system.log("10.6 or higher:" + SnowLeopardOrHigher);
if(SnowLeopardOrHigher < 0)
{
retVal = false;
}
return retVal;
}

function CustomInstallationCheck()
{

if(!(system.compareVersions(system.version.ProductVersion, '10.5') >= 0))
{

my.result.title = system.localizedString('ERROR_SYSTEM_VERSION_TITLE');
my.result.message = system.localizedString('ERROR_SYSTEM_VERSION_MSG');
my.result.type = 'Fatal';
return false;
}

if(!(system.sysctl('hw.cputype') == '7'))
{

my.result.title = system.localizedString('ERROR_HW_MACHINE_TITLE');
my.result.message = system.localizedString('ERROR_HW_MACHINE_MSG');
my.result.type = 'Fatal';
return false;
}
return true;
}
</script>

<background alignment="center" file="background" scaling="tofit"/>
<readme   file="ReadMe"/>

<choices-outline>
<line   choice="choice1"/>
<line   choice="choice2"/>
<line   choice="choice3"/>
</choices-outline>

<choice   id="choice1" start_visible="false" title="Component 1">
<pkg-ref id="com.vikrams.comp1" />
</choice>

<choice id="choice2" start_visible="false" title="Component 2">
<pkg-ref id="com.vikrams.comp2" />
</choice>

<choice   id="choice3" description="APPLICATION_DESCRIPTION_MSG" start_enabled="false" title="Component 3" visible="!CheckIfLeopardOrHigher()">

<pkg-ref   id="com.vikrams.comp3" />
</choice>

<pkg-ref auth="Root" id="com.vikrams.comp1" installKBytes="102400" version="1.0.0">#Component1.pkg</pkg-ref>

<pkg-ref auth="Root" id="com.vikrams.comp2" installKBytes="234000" version="1.0.0">#Component2.pkg</pkg-ref>

<pkg-ref   auth="Root" id="com.vikrams.comp3" installKBytes="540564" version="1.0.0">#Component3.pkg</pkg-ref>

</installer-script>

-----------------------------------------------------------------------------------------------------------------------------------------------

XML Attributes of Packagemaker Distribution.dist file

2013-01-28T07:57:00.001-08:00

XML Attributes of Packagemaker Distribution.dist file

A distribution definition file defines the installation experience for the installer package that contains it. This document describes the XML schema used for distribution definition files. An installer package can contain only one distribution definition file, which must be named distribution.dist.

allowed-os-versions

Defines OS version requirements. These consist of one or more version ranges, specified as os-version elements. The version of the operating systemon the target volume must fall into one of these ranges to allow installation.

Attributes

None

Availability

None

Content

This element can contain the following element:

“os-version”: The supported OS versions.

app

Identifies an application that must be closed before the package is installed.

Attributes

Attribute Name	Type	Description
id	String	Required. The bundle identifier of the application.

Content

None.

auxinfo

Reserved

background

Defines a background image for the Installer.

Attributes

Requirements: You must provide either the mime-type or uti attribute. If you provide both, they must be consistent.

Attribute Name	Type	Description
alignment	String	Optional. The alignment used to render the background image. Values: center (default), left, right, top, bottom, topleft, topright, bottomleft, and bottomright. Only used by the Installer.
file	String	Required. The filename of an image in the distribution package—for example, background.png or ./background.png.
mime-type	String	The standard MIME type of the image.
scaling	String	Optional. The scaling used to render the background image. Values: tofit (default), none, and proportional.
uti	String	The UTI type of the image. This attribute is provided because some file types don’t have a MIME type.

Content

None.

bundle

Defines a single bundle. The meaning of this element differs considerably depending on its parent element; see the parent element’s documentation for details.

Attributes

Attribute Name	Type	Description
CFBundleShortVersion-String	String	Optional. The short version string of the bundle, as defined in its Info.plist file.
CFBundleVersion	String	Optional. The bundle’s version, as defined in its Info.plist file.
id	String	Required. The identifier of the bundle—that is, the value of CFBundleIdentifier in the bundle’s Info.plist file.
path	String	Required. The path atwhich the bundle is installed, relative to where the package is installed. For example, Applications/Sample.app.
search	Boolean	Optional. Indicates whether to search for the bundle by its identifier if it is not found at the given path. Values: false (default), true.
BuildVersion	-	Reserved
SourceVersion	-	Reserved

Content

None

bundle-version

Defines the version of the bundles delivered by the parent element. You do not typically specify this element; productbuild inserts it from the actual package data when the product archive is created.

Attributes

None.

Availability

Available in Mac OS X v10.6.6 and later.

Content

This element can contain the following elements:

"bundle": The package-relative path and version strings of the bundles installed.

choice

Defines an installation choice of a distribution package.

Attributes

Attribute Name	Type	Description
customLocation	Absolute file path	Optional. Specifies the default installation location, within the installation volume, for this choice. Implies that the user can choose a different installation location. If unspecified, the user cannot choose the installation location for this choice.
customLocationAllow-AlternateVolumes	Boolean	Optional if customLocation is specified; otherwise, not allowed. Specifies whether the user can choose the installation volume. Values: false (default) indicates that the user can choose a different location than what is given by customLocation but cannot change the volume; true indicates that the user can choose the installation volume and the location on that volume. A value of true is only valid for packages that use the Installer.
description	String,localization key	Required for packages that use the Installer; otherwise, optional. Specifies the description of the installation choice. Localizable.
description-mime-type	String	Optional. The MIME type of the text data in the description attribute. Values: text/plain (default), text/rtf, or text/html.
enabled	Boolean JavaScript expression	Optional. Specifies whether the user can select or deselect this option in the Installer customization pane. If false, or a JavaScript expression that evaluates to false, the choice is dimmed so the user cannot select or deselect it. Re-evaluated as the user interacts with the choice tree, so a choice can be enabled or disabled based on the state of other choices. Default value is true.
id	String	Required. Unique identifier of the installation choice, used to bind this element to the line element that determines its position in the installation-choice hierarchy. Mustmatch the choice attribute of exactly one line element.
selected	Boolean JavaScript expression	Optional. Specifies whether this option is selected or deselected for installation. If false, or a JavaScript expression that evaluates to false, the choice will not be installed. In general, you should not declare this attribute on a choice that is visible and enabled, because it can interfere with the user’s selections. Default value is true.
start_enabled	Boolean	Optional. Specifies whether this option is initially enabled in the Installer customization pane. Values: true (default), or false.
start_selected	Boolean	Optional. Specifies whether this option is initially selected or deselected for installation. Values: true (default), or false.
start_visible	Boolean	Optional. Specifies whether this option is initially visible in the Installer customization pane. Values: true (default), or false.
title	String,localization key	Required. Specifies the title of the installation choice. Localizable.
visible	Boolean JavaScript expression	Optional. Specifies whether this option is visible in the Installer customization pane. If false, or a JavaScript expression that evaluates to false, the choice is hidden from the user. Default value is true. Avoid making choices appear and disappear while the user is interacting with the installation process. This provides a poor user experience.
bundle	-	Reserved
customLocationIs-SelfContained	-	Reserved
tooltip	-	Reserved
versStr	-	Reserved

Content

This element can contain the following element:

"pkg-ref": The choice’s packages. You should only associate packages with a choice that has no subchoices (as defined by the hierarchy of line elements)

choices-outline

Defines the installation-choice hierarchy of a distribution package.

Attributes

Attribute Name	Type	Description
ui	-	Reserved.

Content

This element can contain the following element:

"line"

: The top-level installation choices.

conclusion

Specifies text that is displayed by Installer at the end of the installation process.

Attributes

Requirements You must provide either the mime-type or uti attribute. If you provide both, they must be consistent.

Attribute Name	Type	Description
file	String	Required. The filename of the conclusion file in the distribution package—for example, conclusion.rtf.
mime-type	String	The MIME-type specifier for the data contained in the file.
uti	String	The UTI-type specifier for the data contained in the file.
language	-	Reserved

Content

None.

domains

Indicates what domains the package may be installed into. If this element is not present, enable_anywhere is true, enable_currentUserHome is false, and enable_localSystem is true.

Attributes

Attribute Name	Type	Description
enable_anywhere	Boolean JavaScript expression	Required. If true, or a JavaScript expression that evaluates to true, the product can be installed at the root of any volume, including nonsystem volumes. Otherwise, it cannot be installed at the root of a volume.
enable_currentUserHome	Boolean JavaScript expression	Required. If true, or a JavaScript expression that evaluates to true, the product can be installed into the current user’s home directory. Otherwise, it cannot be installed in the current user’s home directory. A home directory installation is done as the current user (not as root), and it cannot write outside of the home directory. You should enable this only if the product can be installed in the user’s home directory and be completely functional from that location.
enable_localSystem	Boolean JavaScript expression	Required. If true, or a JavaScript expression that evaluates to true, the product can be installed into the root directory. This attribute should usually be true unless the product can be installed only to the user’s home directory.

Content

None.

installation-check

Specifies whether the installation host meets the distribution’s system requirements. The installation check passes if the script returns true, any RAM requirements are met, and any graphics requirements are met.

Attributes

Attribute Name	Type	Description
script	Boolean JavaScript expression	Optional. Specifies whether the requirements are met. If true (default), or a Boolean JavaScript expression that evaluates to true, the installation proceeds, subject to the other checks. If the script evaluates to false, it must also set my.result.type and my.result.message to indicate the severity of the problem and provide a message to display. If my.result.type is Warning, the installation may be allowed to proceed after informing the user.

Content

This element can contain the following elements:

"ram": The required RAM.
"required-graphics": The GPU requirements.

installer-gui-script

The root element of the distribution definition. All other elements in the distribution definition file are children of this element.

Attributes

Attribute Name	Type	Description
minSpecVersion	Integer	Required. The schema version of a distribution file. Use 1 for the version used prior to Mac OS X v10.6.6, or 2 after that.
maxSpecVersion	-	Reserved.
verifiedSpecVersion	-	Reserved.

Content

This element can contain the following elements:

license

Specifies text that is displayed by Installer during the installation process.

Attributes

Requirements You must provide either the mime-type or uti attribute. If you provide both, they must be consistent.

Attribute Name	Type	Description
file	String	Required. The filename of the welcome file in the distribution package—for example, welcome.rtf.
mime-type	String	The MIME-type specifier for the data contained in the file.
uti	String	The UTI-type specifier for the data contained in the file.
auto	-	Reserved
auto	-	Reserved
sla	-	Reserved

Content

None.

line

Defines where a choice fits into the installation-choice hierarchy of a distribution package.

Attributes

Attribute Name	Type	Description
choice	String	Required. Identifies the installation choice associated with this node of the installation-choice hierarchy of a distribution package. The valuemust match the ID of a choice element. See “choice”. Do not reference the same ID from more than one line element, not even from different installation-choice hierarchies; if you do so, the behavior is undefined.

Content

This element can contain the following element:

"line": The subchoices of this choice.

localization

Reserved.

locator

Defines a search rule for finding software that is already installed on the system.

Attributes

None.

Content

This element can contain the following element:

"search": The search rule.

must-close

Identifies applications that must be closed before the package is installed. Applications are considered only if the package that contains this element has been selected for installation.

Attributes

None.

Content

This element can contain the following element:

"app": The applications.

options

Specifies the installation properties of a package within the distribution.

Attributes

Attribute Name	Type	Description
allow-external-scripts	Boolean	Optional. Specifies whether the run and runOnce JavaScript functions can be executed. Values: false (default) or true. For information about these functions, see “System” in Installer JavaScript Reference .
customize	String	Optional. Specifies whether the user can customize the installation by selecting or deselecting installation choices. Values: allow (default) gives the user an opportunity to customize the installation, always presents the customization view automatically. never does not provide access to the customization view.
hostArchitectures	String	Optional. A comma-separated list of supported architecture codes. Valid codes are i386, x86_64, and ppc. Note that i386 matches both 32-bit and 64-bit systems, but x86_64 matches only 64-bit systems.
mpkg	String	Optional. Identifies a package (pkg-ref element) whose installation operations must be performed as part of the installation of this distribution. Deprecated.
require-scripts	Boolean	Optional. Indicates whether the distribution uses JavaScript code. Values: true (default) or false. If this value is false, all attributes whose value may be a JavaScript expression must be set to either true or false. Available in Mac OS X v10.6.6 and later.
rootVolumeOnly	Boolean	Optional. Specifies whether the user can choose an installation volume other than the boot volume. Values: true or false. Deprecated. Use domains instead.
type	-	Reserved
visibleOnlyForPredicate	-	Reserved

Content

None.

os-version

Defines a range of supported OS versions. This element is designed for you to use a specific OS version number for the min attribute, and a major OS version number for the before attribute. The expectation is that you will know an exact minimum version but not an exact major version. This keeps you from having to guess the last minor revision before the next major revision, as you would have to do if the before attribute were inclusive.

Attributes

Attribute Name	Type	Description
before	String	Optional. The maximum allowed version (exclusive). If the OS version is greater than or equal to this version, installation will be disallowed (unless the OS falls in the range of another os-version element). If no value is given, there is no upper bound on the range—any version newer than the minimum is allowed.
min	String	Required. The minimum allowed version (inclusive). If the OS is less than this version, installation will be disallowed (unless the OS falls in the range of another os-version element).

Content

None.

pkg-ref

References a component package that can be installed.

Attributes

Attribute Name	Type	Description
active	Boolean Javascript expression	Optional. Indicates whether the package is installed. Values: true (default), false. If false, or a JavaScript expression that evaluates to false, the package is not installed, even if its associated choice was selected. This provides an additional way to activate and deactivate packages. It overrides the setting on the parent element.
auth	String	Defines the authorization level needed to install this package. Values: none or root. Deprecated. The installation domain determines the necessary authorization level.
id	String	Required. Uniquely identifies a component packagewithin a distribution package—for example, com.apple.Text- Edit.pkg. The value of this attribute is usually the same as the component package’s identifier, but it is not required to be the same. If there are multiple pkg-ref elements with the same ID, their attributes will be collapsed together as if they were specified with a single element. In particular, a pkg-ref element with only an ID can be used inside of a choice element to bind that choice to a pkg-ref that is more fully defined elsewhere in the distribution file.
installKBytes	Integer	Optional. Specifies the size of the package’s payload in kilobytes. You typically omit this attribute because productbuild sets it from the actual package when the product archive is created.
onConclusion	String	Optional. Specifies the action to take after the installation has finished. Values, fromlowest to highest: None (default), RequireLogout, RequireRestart, or RequireShutdown. The Installer takes the highest value from all enabled packages and requires the associated action
onConclusionScript	String	Optional. A JavaScript expression that evaluates to one of the string values expected for onConclusion. If this attribute is present, any onConclusion attribute is ignored. Available in Mac OS X v10.7 and later.
version	String	Required. Specifies the version of the package’s payload. You typically omit this attribute because productbuild will set it from the actual package when the product archive is created.
archiveKBytes	-	Reserved
packageIdentifier	-	Reserved

Content

Required. A URL specifying the location of the installation package to which this element refers. Typically, you specify a simple filename and productbuild adjusts the URL as needed when the product archive is created. If you define multiple pkg-ref elements with the same ID, exactly one of them should have text content. This element can contain the following elements:

"must-close": (zero or one) :The application(s) to be closed before installing this package.
"bundle-version":(zero or one): The bundle version.
"relocate": (zero or more): The information to support relocatable bundles.

To provide a must-close element, add a separate pkg-ref element with the same ID to contain the must-close element. For example:
&ltpkg-ref id="abc"&gtx.pkg&lt/pkg-ref&gt
&ltpkg-ref id="abc"&gt
&ltmust-close&gt
&ltapp id="com.example.MyApp"/&gt
&lt/must-close&gt
&lt/pkg-ref&gt

ram

Specifies the minimum amount of RAM that the system must have.

Attributes

Attribute Name	Type	Description
min-gb	String	Required. The minimum required RAM in gigabytes. (Consistent with how sizes are displayed in Mac OS X v10.6 and later, a gigabyte is defined as 109 bytes, not 230 bytes.)

Availability

Available in Mac OS X v10.6.6 and later.

Content

None.

readme

Specifies text that is displayed by Installer during the installation process.

Attributes

Requirements You must provide either the mime-type or uti attribute. If you provide both, they must be consistent.

Attribute Name	Type	Description
file	String	Required. The filename of the readme file in the distribution package. For example, readme.rtf.
mime-type	String	The MIME-type specifier for the data contained in the file.
uti	String	The UTI-type specifier for the data contained in the file.
language	-	Reserved.

Content

None.

relocate

Describes a relocatable bundle. Relocatable bundles allow the user to install an upgrade in the same path as the current version. The path is located by the search element whose ID is specified by the search-id attribute. The bundle is specified by the child bundle element. For example, application bundles are typically relocatable.

Attributes

Attribute Name	Type	Description
search-id	String	Required. Specifies the ID of the search element whose results are applied to the bundle that is this element’s child element. If the search returns false, the relocate does nothing. If the search returns an array of results, the first result is used.

Content

This element can contain the following element:

"bundle"(exactly one): The bundle (within the package) that will be installed at the path. The only required attribute for this bundle element is its ID.

required-bundles

Specifies bundles that must be already installed on the system. If the child bundle element has a version specified, this is interpreted as the minimum supported version for that bundle. It may also have its search attribute set to true, indicating that the bundle should be located by its identifier if it doesn’t exist at the specified path.

Attributes

Attribute Name	Type	Description
all	Boolean	Optional. Values: true (default) to require all of the specified bundles, or false to require at least one of them.
description	String, localization key	Optional. A description of the required bundles, displayed to the user if the requirement is not met.

Content

This element can contain the following element:

"bundle": The required bundles.

required-cl-device

Specifies requirements that must be met by at least one OpenCL device.

Attributes

None.

Availability

Available in Mac OS X v10.7 and later.

Content

The predicate, as a string. For details about the predicate format, see the productbuild(1) man page. To prevent characters in the predicate from being interpreted by the XML parser, mark it as CDATA content.

required-gl-renderer

Specifies requirements that must be met by at least one OpenGL hardware renderer.

Attributes

None.

Availability

Available in Mac OS X v10.6.8 and later.

Content

The predicate, as a string. For details about the predicate format, see Specifying required OpenGL capabilities for the Mac App Store and the productbuild man page. To prevent characters in the predicate from being interpreted by the XML parser, mark it as CDATA content.

required-graphics

Specifies GPU requirements.

Attributes

Attribute Name	Type	Description
description	String,localization key	Optional. A description of the graphics requirement. Localizable. If no description is specified, a generic message is used. It is generally best to use the generic message unless the requirements are very straightforward.
single-device	Boolean	Optional. Values: false (default) to allow the OpenCL and OpenGL requirements to bemet by different devices, or true to require a single device to simultaneously meet both requirements.

Content

This element can contain the following elements:

"required-cl-device": The OpenCL requirements.
"required-gl-renderer": The OpenGL requirements.

script

Defines a set of JavaScript functions.

Attributes

Attribute Name	Type	Description
language	-	Reserved.

Content

JavaScript code, typically the definition of functions called from attributes of other elements. To prevent characters in the script from being interpreted by the XML parser, mark it as CDATA content:
&ltscript&gt
&lt![CDATA[
// ... JavaScript ...
]]&gt
&lt/script&gt

If you choose not to mark your script as CDATA content, you must take great care to properly escape all characters that have special meaning in XML markup.

search

Defines a search rule for finding installed software. The result should be used by another search rule or bound to a bundle via a relocate element.

Attributes

Attribute Name	Type	Description
id	String	Required. Uniquely identifies the search; used in the search-id attribute of other elements to reference this search.
script	String	Required if type is script; otherwise, not allowed. A JavaScript expression that evaluates to false, a path as a string, or an array of paths. If it returns an array of paths, the first one is the preferred path. This expression can be a function call, but the called function must be defined in the child script element.
search-id	String	Optional if type is component; otherwise, not allowed. The ID of another search. The other search is performed, and its results further filtered by removing those results that don’t match the version strings given by the child bundle element. This allows the other search to be qualified for certain values of CFBundleShortVersionStrings or CFBundleVersions.
search-path	String	Optional if type is component; otherwise, not allowed. A path to a bundle. If there is a bundle at this path that matches the version string of this element’s child bundle element, then the path is used as the search result.
type	String	Required. Indicates the type of the search. Valid values are: component Search for a bundle on disk that matches the identifier and version strings given by the child bundle element. By default, the Installer uses Launches Services to perform the search, and it searches only the volume that the user selected as the installation target. The search-id and search-path attributes modify this behavior. script Search by evaluating the JavaScript code contained in the script attribute.

Content

This element must contain exactly one of the following elements:

"bundle": The bundle for a component search.
"script": The script for a script search.

strings

Reserved.

tag

Reserved.

title

Defines the title of the product.

Attributes

None.

Content

The title or a localization key used to look up the title.

volume-check

Specifies whether a particular volume meets the distribution’s volume requirements. All of the tests in the script attribute and the child elements must pass.

Attributes

Attribute Name	Type	Description
script	Boolean Javascript espression	Required. Specifies whether the requirements for installing on a particular volume are met. If the script evaluates to false, itmust also set my.result.type and my.result.message to indicate the severity of the problem and provide a message to display. The property my.target.mountpoint contains themount point of the volume being checked.

Content

This element can contain the following elements:

"allowed-os-versions":(zero or one): The versions of the OS to accept on the target volume.
"required-bundles":(zero or one): The bundles that must already be present.

welcome

Specifies text that is displayed by Installer at the beginning of the installation process.

Attributes

Requirements You must provide either the mime-type or uti attribute. If you provide both, they must be consistent.

Attribute Name	Type	Description
file	String	Required. The filename of the welcome file in the distribution package—for example, welcome.rtf.
mime-type	String	The MIME-type specifier for the data contained in the file.
uti	String	The UTI-type specifier for the data contained in the file.
language	-	Reserved

Content

None.

-------------------------------------------------------------------------------------------------------------
Disclaimer: This reference is a copy of Distribution Definition Reference published by Apple.

Scripting in Installer Packages

2012-07-07T05:56:00.000-07:00

In my previous post, I discussed about creating packages to deploy your application bundles. However, installation of some applications is more complex and requires many actions other than copying the payload. For example, you want to check if a particular application is already installed on the system before installing your application. For all these tasks, you can use the preinstall, postinstall and Distribution scripts which are included in the package and run by the installer during the installation. After the Installer application finishes checking installation requirements, it performs an install through distinct operations, known as install operations. You can define all but one of these operations, which copy payloads to their installation destinations. You should not use install operations to fix install problems, such as incorrect ownership and access permissions. You should use install operations only when other managed-install features, such as installation requirements, are not adequate for the chore you need to perform as part of installing a package.

Install operations allow you to configure the destination environment before the payload is copied to the file system and to perform additional processing afterward. Install operation executables must be named according to the install operation you want to define. The files can be binary files or text files containing shell scripts. All install operations are optional.

You can use following arguments and environment variables which are available to install operation executables.

$1: Full path to the installation package the Installer application is processing. For example: /Volumes/Users/Vikrams/Desktop/TestPkg.pkg

$2: Full path to the installation destination. For example: /Applications

$3: Installation volume (or mount point) to receive the payload. For example: /Volumes/Tools

$4: The root directory for the system: /

$SCRIPT_NAME: Filename of the operation executable. For example: preflight

$PACKAGE_PATH: Full path to the installation package. Same as $1.

$INSTALLER_TEMP: Scratch directory used by Installer to place its temporary work files. Install operations may use this area for their temporary work, too, but must not overwrite any Installer files. The Installer application erases this directory at the end of the install. For example: /private/tmp/.vikrams.pkg.234.install

Your script must return 0 on success and any other number to denote failure. The name of the scripts must be “preinstall” and “postinstall”. You can see some sample scripts below-

--------------------------------------------------------------
#!/bin/sh
#This is a sample preinstall or postinstall script.
#Your logic goes here.
if [ your_logic_returns_false ]
then
exit -1
fi
exit 0
--------------------------------------------------------------
Lines starting with # are comments. First line #!/bin/sh is called “Shebang” and denotes that it is a shell script. Any return value other than 0 denotes failure. If you return anything other than 0, your installation will stop with a failure message.

Scripting Quickies

Let’s discuss about some common and some complex scenarios where a lot of people can get stuck:

I have some resources which need to be accessible from the preinstall and postinstall scripts.

In older style packages (bundles), since the path inside the package was accessible, we kept the resources in the resources directory and had access to them using PACKAGE_PATH/Contents/Resources/ path. In case of flat packages, the installer extracts the scripts directory to some temporary directory while running. So, we can keep any resource with the scripts while packaging and when the installer is run, these resources will be present in the same directory from where the scripts are run. In this way, we can access any resource from preinstall and postinstall scripts.

How can I perform installation requirements check?

Bundle packages supported installation check using InstallationCheck script. However, flat packages no longer support InstallationCheck script. In flat packages, this installation check phase has moved to the Distribution file. You can write Javascript functions and assign them to be called during installation-check phase. Your distribution file should contain<installation-check script=”your_function()” /> and if your function returns false, the installation will not proceed.

Can I perform installation requirements check for component packages?

No, you must use a Distribution package if you intend to perform InstallationCheck or VolumeCheck.

Apart from preinstall and postinstall scripts, a lot of functionality goes in the Distribution script. I will cover all the aspects of a typical Distribution file in the next post.

Creating Packages for Mac

2012-06-07T10:00:00.000-07:00

So, our great application is now ready for deployment after all the hard work that has gone in development and testing. But how are we going to distribute our applications to all the users in the world? Well, you need not worry, you can package your application and these packages can be deployed on any Mac systems.

Creating packages is an easy and standard way to distribute your applications for Mac. Along with ease, you get a lot of options through which you can carry out a full-fledged installation including requirements check, pre-install and post-install actions. So, even if you need a complex environment for your application to run like changing permission or whatever, packages can still do it for you.

Let’s move on to how to create packages. Again, you have got many options: Do it using GUI mode of PackageMaker or use its command-line mode or use the productbuild command to create the packages. It’s all up to you what you end up using. However, all of the above mentioned methods have their pros and cons. We will go through them one by one:

PackageMaker GUI mode:

Well, it’s a no-brainer. If you follow the on-screen messages, you will know what options to use for what purpose and you will end up with a decent package ready for distribution. In case you need more detailed steps:

Launch the PackageMaker application.
It will ask you which version of OS you are targeting and an identifier for your package. Select the minimum version which you have to support. If you select 10.4, bundle packages will be created since 10.4 does not support flat packages.
You can use the options provided in the 3 tabs:

Configuration: Allows you to set general properties of components like title, identifier, whether you require restart after installation, etc.
Requirements: Allows you to set the requirements which must be met before your package can be installed on the system. See the screenshot below.
Actions: Allows you to add your own scripts- preinstall and postinstall which will be run before and after your payload is dumped in the system.

Drag and drop the components to be installed to the left-side pane. You can add different sub-components as choices. Choices provide a lot of flexibility to your package. For example, if you have some optional sub-packages, the user will be able to choose whether to install that package or not.
You can select properties of individual components as well. If you want to allow relocation of your .app files or to allow downgrade of packages, select the corresponding checkbox.

Relocation allows you to replace the .app file in-place if the application is already installed on your system.
Downgrade allows you to install older versions on top of newer versions.

And then you have got options to modify the background image of the installer and add the required resource files like License, Read Me, etc.
You can add localization and provide localized resources as well if required.

And that’s it. Build the package and you have your Mac Installer ready for distribution.

PackageMaker command-line mode:

You can also achieve most of the functionality provided by GUI mode from the command-line mode of PackageMaker. If you have to create packages very frequently or for large number of products, then it’s a good idea to automate that process. You can use the command-line mode of packagemaker for all you automated package creation. See manual page for Packagemaker for details on various options available.

However, there are several issues in command-line version of Packagemaker. I have given solution to some of the common problems you may face.

Problems and Solutions:

I have bundle packages. Will they work on MacOS 10.8 (Mountain Lion)?

Mountain Lion introduces “Gatekeeper” which allows only signed apps to run on the system. We CAN NOT sign bundle packages and hence if the Gatekeeper is turned ON, bundle packages will not install on 10.8 if they have been download via web. However, if these packages have not been downloaded via web or the Gatekeeper is turned OFF, then bundle packages will install as expected.

Why is the Finder not showing the version of the flat packages?

Finder gets the version information of an archive from the info.plist file present inside the archive. So, in old-style bundle packages, we were able to see the version of the package in the Finder. However, flat packages behave as files. They do not behave like an archive. So, Finder will not be able to show the version.

I am not able to sign my packages using packagemaker. Why?

It is possibly a bug with packagemaker. Packages signed using packagemaker don’t work. You can use “productsign” command-line tool to sign your packages. See manual page for productsign for more information.

I am creating a distribution package from command-line. I am providing localized license files to --resources flag but when I run the package, I don’t get the License page during installation. Why?

Again, it is possibly a bug with packagemaker. It does not include the license file information in the Distribution file of the created package. Open your package using Flat Package Editor and check if the Distribution file has the attribute <license file=“License.rtf”/>.
You can fix this issue in your package even without rebuilding the package.Follow the instructions below:o   Expand the package using pkgutil command.
pkgutil   --expand   ABC.pkg   ABC_expanded.pkg
o   Open the ABC_expanded.pkg using Show Package Contents.
o   Open the Distribution file and add this line at same hierarchy level as <title> </title>
<license file="License.rtf"/>
o   Save and close the file. Make sure the resources directory is present and contains the necessary resources (License files in this case).
o   Flatten the package using pkgutil.
pkgutil   --flatten   ABC_expanded.pkg   FinalPkg.pkg
o   Run the FinalPkg.pkg and it should show the License files.
Alternatively, check “productbuild” command. If you use this command, you can specify your own Distribution.dist file while creating the package. Check manual page for productbuild for more information.

How can I check if my installer is signed?

Use pkgutil --check-signature pkg-path

Productbuild command:

You can also build packages using productbuild. This command provides you many different options to create a package than those in packagemaker. However, you can only create flat packages using this. It has three different modes:

· You can create a product archive for your application bundles.

o productbuild [--product definition-plist] {--component component-path [install-path]} product-output-path

· Create a product archive using a distribution file.

o productbuild [options] --distribution dist-path [--package-path search-path] product-output-path

· Synthesize a distribution for one or more component packages.

o productbuild --synthesize [--product definition-plist] {--package pkg-path} distribution-output-path

For more details about this command, see manual page for productbuild.

So, this was a little explanation about packaging in Mac. There are a lot of details which have not been covered here. However, I will try to post more articles about this. For now, Adiós!

Packagemaker 3: An Introduction

2012-03-06T09:49:00.002-08:00

Packagemaker 3 - An Introduction

Packagemaker is Apple's official packaging tool which is used for packaging the applications before distributing them. It is part of XCode developer software suite. Earlier, it was installed as part of XCode installation, however, with the release of XCode 4.3, it is a part of separate package (Auxiliary Tools for XCode) which has to be downloaded separately. You need an Apple Id to download these tools.

At the time of writing, the latest Packagemaker version is 3.0.5. This version offers great improvements over the previous versions in terms of GUI mode of creating the installers. Talking about the GUI mode, most of the things are self-explanatory, so it is pretty easy to end up with a decent, working installer. However, if you are planning to use the command line mode for creating the installers, it is highly likely that you are going to have some trouble as the documentation is just not good enough.

Before moving on, lets have a look at the supported package formats-

There are two types of packages- Bundles and Flat Packages.

Bundle vs Flat Package

Bundle contains data in a hierarchical manner. You can do RightClick --> Show Package Contents and browse through all the items present inside as if they were part of some folder structure and modify it. For some, it was good to be able to see what is inside the package, tweak it according to their will and requirements and then use it. However, for others, it was a security issue because users had the ability to modify the contents of the packages.
So Apple came up with concept of Flat packages. These packages behave as files instead of folders. With these, you cannot browse through the contents easily though it is possible if you are curious enough to peek inside the package.
If your application distribution target is MacOS 10.5 and above, PM3 will create flat packages. For MacOS 10.4 and below, PM3 also supports Backwards-Compatibility mode that creates older packages(Bundles).

Here, we will be talking more about the flat packages, though we will be pointing out the significant differences from the Bundles if any.

Want to peek inside a flat package?

There are some tools available for opening/modifying flat packages as well. If you want to see inside the package, open it using Flat Package Editor.

This tool allows you to see the basic structure of the package which in most cases will be one of the following-

Component Package

Distribution Package(Left) and Component Package(Right)

After getting the above information, some of you won't be satisfied as it just shows the high level structure and doesn't allow to see what is inside the Payload or Scripts.
So, what next!.
Is it not possible to see the contents of the flat package?
Well! Everything is possible in this world if you are curious enough to know and do it.
Let's take a look at a command-line tool - pkgutil.

We can use this utility to perform a number of operations in our packages. I will be mentioning only some of the operations here. You can get more detailed information at the man pages of pkgutil.

For those of you who were dying to see the contents of the flat package, we can expand the flat package using pkgutil.

pkgutil --expand FlatPackage.pkg NewPackage.pkg

Now, newly created package is older-style package which we can browse through by doing RightClick --> Show Package Contents. After going inside, double click the Payload file to extract the contents! So finally you got what you were looking for. Here you can modify files at your will.
But will the package work after we modify the files?
Yes! As far as we don't change the basic structure of the package.

Suppose we modified some script inside the Scripts directory to bypass some settings that were not allowing installation in my machine. Now we have to flatten the package again. Use

pkgutil --flatten OlderStylePkg.pkg NewFlatPackage.pkg

And you get your modified package back in flat format ready for installation.

Types of Flat Packages:

So in the images above, you see two different types of packages. One contains only compressed files inside while the other one contains packages inside as well.
So what's the difference between the two?
The one with only compressed files inside is Component Package. Their primary purpose is to dump the payload in the system where they are installed and of course perform the preinstall and postinstall actions.
Well, you must be wondering that this is exactly what a package is supposed to do when installed. So what is it that they can not do during the installation?
They can't show any License, ReadMe, etc to the user. They cannot perform InstallationCheck as well.
If we want to show all these things to the user before installation, we use Distribution Package for this purpose. Distribution Packages contain the component packages to be installed, a Distribution file that has the information about the location and name of license files, background images and javascript functions for InstallationCheck actions. It also contains the ususal Resources directory that contains required localization directories which then contain the localized resources (License, background image, etc).

When you will build the package using GUI mode, you will notice that whenever you try to add license, background, etc or InstallationCheck actions to your package, the type of your package changes to Distribution.

Conclusion:
This was a little introduction about the Packagemaker 3, package format and types and about some useful tools to interact with those packages.
With PM3, building a package using its GUI is fairly simple, however, for people who need to create packages everyday and use some sort of automation for creating packages, its command line mode can be of great help. I will be talking about command line mode for building packages in my next post.
Adios!

Links to External Resources:

Apple's User Guide:

https://developer.apple.com/library/mac/#documentation/DeveloperTools/Conceptual/PackageMakerUserGuide/Introduction/Introduction.html

More about Flat Package format:

http://s.sudre.free.fr/Stuff/Ivanhoe/FLAT.html

Many good articles at:

http://www.mactech.com/search/google?cx=014498448673098268608%3Atxq2lx97m8a&cof=FORID%3A11&query=packagemaker&sa.x=0&sa.y=0&sa=Search&ie=utf-8&safe=high&form_build_id=form-afede056da65b0af051f2b2cba08c3d4&form_id=google_cse_searchbox_form