From 242d592d415a2775ac1852561bd8f0c65162d189 Mon Sep 17 00:00:00 2001 From: Andrew Hyatt Date: Tue, 22 Nov 2016 08:49:53 -0800 Subject: [PATCH] Add and install manpage --- CMakeLists.txt | 1 + installer.8 | 367 +++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 368 insertions(+) create mode 100644 installer.8 diff --git a/CMakeLists.txt b/CMakeLists.txt index d878bea..a51572d 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -62,3 +62,4 @@ set(BINARY_PACKAGING_MODE ON) InstallSymlink(installer libexec/darling/usr/bin/uninstaller) InstallSymlink(installer libexec/darling/usr/bin/pkgutil) +install(FILES installer.8 DESTINATION libexec/darling/usr/share/man/man8) diff --git a/installer.8 b/installer.8 new file mode 100644 index 0000000..79b9490 --- /dev/null +++ b/installer.8 @@ -0,0 +1,367 @@ +.\" Copyright (c) 2001-2007 Apple Inc. All Rights Reserved. +.\" The contents of this file constitute Original Code as defined in and are +.\" subject to the Apple Public Source License Version 1.2 (the 'License'). +.\" You may not use this file except in compliance with the +.\" License. Please obtain a copy of the License at +.\" http://www.apple.com/publicsource and read it before using this file. +.\" +.\" This Original Code and all software distributed under the License are +.\" distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER +.\" EXPRESS OR IMPLIED, AND APPLE +.\" HEREBY DISCLAIMS ALL SUCH WARRANTIES, INCLUDING WITHOUT LIMITATION, ANY +.\" WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, +.\" QUIET ENJOYMENT OR NON-INFRINGEMENT. Please see the License for the +.\" specific language governing rights and limitations under the License." +.\" +.Dd April 19, 2007 +.Dt INSTALLER 8 +.Os "Mac OS X" +.Sh NAME +.Nm installer +.Nd system software and package installer tool. +.\" SYNOPSIS +.Sh SYNOPSIS +.Nm +.Op Fl dominfo +.Op Fl volinfo +.Op Fl pkginfo +.Op Fl showChoicesXML +.Op Fl showChoicesAfterApplyingChangesXML Ar +.Op Fl applyChoiceChangesXML Ar +.Op Fl query Ar +.Op Fl allow +.Op Fl dumplog +.Op Fl help +.Op Fl verbose | verboseR +.Op Fl vers +.Op Fl config +.Op Fl plist +.Op Fl file Ar +.Op Fl lang Ar +.Op Fl listiso +.Fl package Ar +.Fl target Ar device +.\" DESCRIPTION +.Sh DESCRIPTION +The +.Nm +command is used to install Mac OS X installer packages to a specified domain +or volume. +The +.Nm +command installs a single package per invocation, which is specified with the +.Fl package +parameter ( +.Fl pkg +is accepted as a synonym). +It may be either a single package or a metapackage. +In the case of the metapackage, the packages which are part of the default +install will be installed unless disqualified by a package's check tool(s). +.Pp +The target volume is specified with the +.Fl target +parameter ( +.Fl tgt +is accepted as a synonym). +It must already be mounted when the +.Nm +command is invoked. +.Pp +For system software installs, the target volume must be a different volume than the one currently running the booted system. +See +.Ar systemsetup +(only available on Mac OS X Server) to set the boot volume. +.Pp +The +.Nm +command requires root privileges to run. +If a package requires authentication (set in a package's .info file) the +.Nm +must be either run as root or with the +.Xr sudo 8 +command (but see further discussion under the +.Fl store +option). +.Pp +The +.Nm +is not responsible for rebooting the machine after installing. +Use +.Xr reboot 8 +or +.Xr shutdown 8 +-r now to reboot the system. +.Pp +The +.Nm +displays two forms of output. +The default terse output is intended for parsing by scripting languages for +automating (or scripting) installs and verbose output providing additional +information and descriptive error messages. +.Pp +A list of flags and their descriptions: +.Bl -tag -width indent +.It Fl dominfo +Displays a list of domains into which the software package can be installed. +For example: +.Ar LocalSystem +or +.Ar CurrentUserHomeDirectory . +The domains listed are those which are available and enabled when the command +is run. +.It Fl volinfo +Displays a list of volumes onto which the software package can be installed. +The volumes listed are the mounted volumes available when the command is run. +.It Fl pkginfo +Displays a list of packages that can be installed onto the target volume. +If a metapackage is given as the package source, all of its subpackages are +listed. +.It Fl query Ar flag +Queries a package for information about the metadata. +See +.Ar -help +for supported flags. +.It Fl allowUntrusted +Allow install of a package signed by an untrusted (or expired) certificate. +.It Fl dumplog +Detailed log information is always sent to syslog using the LOG_INSTALL +facility (and will wind up in /var/log/install.log). +.Fl dumplog +additionally writes this log to standard error output. +.It Fl help +Displays the help screen describing the list of parameters. +.It Fl verbose +Displays more descriptive information than the default output. +Use this parameter in conjunction with +.Ar -pkginfo +and +.Ar -volinfo +information requests to see more readable output. +The default output is formatted for scripting. +.It Fl verboseR +Displays same information as +.Ar -verbose +except the output is formatted for easy parsing. +.It Fl vers +Displays the version of this command. +.It Fl config +Formats the command line installation arguments for later use. +The output is sent to stdout, but can be redirected to a file to create a +configuration file. +When specifying this option, an installation is not actually performed. +This configuration file can be supplied as the argument to the +.Ar -file +parameter instead of typing a long series of installation arguments. +The config file can be used to perform multiple identical installs. +You can create a config file as follows: +.Pp +.Nm +-pkg ~/Documents/Foo.pkg -target / +.Fl config +> /tmp/configfile.plist +.It Fl plist +Formats the +.Nm +output into an XML file, which is sent by default to stdout. +Use this parameter for +.Ar -dominfo, +.Ar -volinfo, +and +.Ar -pkginfo +. +.It Fl file Ar pathToFile +Specifies the path to the XML file containing parameter information in the +key/value dictionary. +This file can be used instead of the command line parameters, and supersedes +any parameters on the command line. +When you type this parameter, you type the path to the XML file. Use with config file generated by +.Ar -config +. +For example: +.Pp +.Nm +.Fl file +/tmp/configfile.plist +.It Fl lang Ar ISOLanguageCode +Default language of installed system (ISO format). +This is only necessary when performing a system (OS) install, otherwise is it +ignored. +There is no verification done to make sure that the language being set +actually exists on the machine, however the ISO language code is verified to +ensure that it is valid. +.It Fl listiso +Display the list of valid ISO language codes the +.Nm +recognizes. +.It Fl showChoiceChangesXML +Prints to stdout the install choices for the package (specified with +.Fl pkg ) +in an XML format. This allows choice attributes to be modified and applied at install-time using +.Fl applyChoiceChangesXML . +See +.Sx CHOICE CHANGES FILE +for details of this XML format. +.It Fl applyChoiceChangesXML Ar pathToXMLFile +Applies the install choice changes specified in +.Ar pathToXMLFile +to the default choices in the package before installation. This allows the command-line installer +to customize choice what gets installed. See +.Sx CHOICE CHANGES FILE +for details of this XML format. Any problems encountered while applying the choice changes will be +reported to the LOG_INSTALL facility (i.e. to /var/log/install.log), and also to stdout if +.Fl dumplog +is used. +.It Fl showChoicesAfterApplyingChangesXML Ar pathToXMLFile +Applies the install choice changes specified in +.Ar pathToXMLFile +to the default choices in the package, and then dumps the resulting choice state to stdout. +The input and output XML format is as described in +.Sx CHOICE CHANGES FILE . +Since changing one choice in a package can implicitly change other choices, this option allows +you to confirm that a particular choiceChanges file will have the intended effect. You must specify a +.Fl target +when using this option, since the evaluated choices can also change with the state of the target disk. +.It Fl showChoicesXML +Prints to stdout the install choices for the package (specified with +.Fl pkg ) +in a hierarchical XML format. This is +.Sy not +the same format as used with +.Fl applyChoiceChangesXML . +This option is provided for System Image Utility only. +.It Fl store +Install the product archive specified by +.Fl package , +in the same way that it would be installed through the Mac App Store. In this mode, no +other options are supported. (You can specify +.Fl target , +but the only allowable value is the root volume mount point, /). For best Mac App Store fidelity, run +.Nm +as an admin user (not using sudo); you will prompted for your admin user's password before the install begins. +.Pp +This mode is provided for testing a product archive before submission to the Mac App Store. See +.Xr productbuild 1 +for how to create a product archive. +.El +.Pp +.\" DEVICES +.Sh DEVICES +A device parameter for the target is any one of the following: +.Pp +1) Any of the values returned by +.Ar -dominfo +.br +2) The device node entry. +Any entry of the form of /dev/disk*. +ex: /dev/disk2 +.br +3) The disk identifier. +Any entry of the form of disk*. +ex: disk1s9 +.br +4) The volume mount point. +Any entry of the form of /Volumes/Mountpoint. +ex: /Volumes/Untitled +.br +5) The volume UUID. +ex: 376C4046-083E-334F-AF08-62FAFBC4E352 +.\" CHOICE CHANGES FILE +.Sh CHOICE CHANGES FILE +A +.Dq choiceChanges +file allows individual installer choices to be selected or deselected. A template choiceChanges +file for a given package can be generated with the +.Cm -showChoiceChangesXML +option, and is interpreted as follows. +.Pp +The choiceChanges file is a property list containing an array of dictionaries. Each dictionary +has the following three keys: +.Bl -column ".Sy choiceIdentifier" A012345678901234567890123456789012345678901234567890123456789 +.It Sy Key Ta Sy Description +.It Sy choiceIdentifier Ta "Identifier for the choice to be modified (string)" +.It Sy choiceAttribute Ta "One of the attribute names described below (string)" +.It Sy attributeSetting Ta "A setting that depends on the choiceAttribute, described below (number or string)" +.El +.Pp +The +.Sy choiceAttribute +and +.Sy attributeSetting +values are as follows: +.Bl -column ".Sy choiceIdentifier" A012345678901234567890123456789012345678901234567890123456789 +.It Sy choiceAttribute Ta Sy attributeSetting Description +.It Sy selected Ta "(number) 1 to select the choice, 0 to deselect it" +.It Sy enabled Ta "(number) 1 to enable the choice, 0 to disable it" +.It Sy visible Ta "(number) 1 to show the choice, 0 to hide it" +.It Sy customLocation Ta "(string) path at which to install the choice (see below)" +.El +.Pp +Note that there can be multiple dictionaries for the same +.Sy choiceIdentifier , +since there can be multiple attributes set for a single choice. +.Pp +The +.Sy customLocation +attribute can be set for a choice only if that choice explicitly allows a user-defined path. That is, +if the choice would have a Location popup when viewed in the Customize pane of the Installer application, +it can be set via +.Sy customLocation . +(Otherwise, installation paths cannot be arbitrarily modified, since the package author must account +for custom install locations for the installation to work properly.) +.\" EXAMPLES +.Sh EXAMPLES +.Nm +-dominfo -pkg InstallMe.pkg +.Pp +.Nm +-volinfo -pkg InstallMe.pkg +.Pp +.Nm +-pkginfo -pkg DeveloperTools.mpkg +.Pp +.Nm +-pkg OSInstall.mpkg -target +LocalSystem +.Pp +.Nm +-pkg OSInstall.mpkg -target / -lang en +.Pp +.Nm +-pkg DeveloperTools.mpkg -target / +.Pp +.Nm +-pkg InstallMe.pkg -target "/Volumes/Macintosh HD2" +.Pp +.Nm +-pkg InstallMe.pkg -file /tmp/InstallConfigFile +.Pp +.Nm +-pkg InstallMe.pkg -target /dev/disk0s5 +.Pp +.\" ENVIRONMENT +.Sh ENVIRONMENT +.Bl -tag -width "COMMAND_LINE_INSTALL" +.It Ev COMMAND_LINE_INSTALL +Set when performing an installation using the +.Nm +command. +.El +.\" FILES +.Sh FILES +.Bl -tag -width "/usr/sbin/installer" -compact +.It Pa /usr/sbin/installer +Software package installer tool +.El +.\" SEE ALSO +.Sh SEE ALSO +.Xr syslog.conf 5 +.Xr reboot 8 +.Xr shutdown 8 +.Xr softwareupdate 8 +.Xr sudo 8 +.Xr systemsetup 8 +.\" HISTORY +.Sh HISTORY +The command line +.Nm +tool first appeared in the 10.2 release of Mac OS X.