| MacHouse Software |
Last updated: August 17, 2011
|
| AppReady - User's Guide |
0. Installing and uninstalling AppReady Please read the README file that comes with the application. Or click here to download one. Click here to download a test package.
The goal of using AppReady is to make a package out of an application that can be sent to Apple's iTunes Connect through Application Loader. In order to achieve this goal, you must be a member of Apple's Developer Program, which allows you to submit applications to iTunes Connect for review. If accepted, your application will be displayed for sale at Mac App Store. You can join Mac Developer Program at this Apple's web page. After joining Developer's Program, you must create two certificates - Application certificate and Installer certificate. You can create certificates at this web page. Then you must use Keychain Access (Find it in the Utilities folder.) to identify those signed certificates. In order to create application packages through AppReady, you need a specific command-line tool. It's productbuild. This command-line tool is included in Application Tools 1.1, separate from Xcode 3.2.5. Or install Xcode 3.2.6 or Xcode 4.x, which includes productbuild, according to Apple. If installed, productbuild should be found at /user/bin/ In sum, you need the following to create application packages.
Whenever you launch AppReady, you will start with its main window. (See Screenshot 2-0.) This window has a drop box, onto which you want to drag and drop a Mac application to work with. Initially, the Next button is disabled. It will remain disabled until you import a Mac application. Also, you must set your certificate names in Preferences before using AppReady, or the Next button will remain disabled. If certificates are left blank in Preferences, the help tag of the Next button will indicate so even after dragging and dropping an application icon onto the drop box. (See Screenshot 2-1.)
So your first task is open Preferences under AppReady. Then switch to the Certificates tab. Next, launch Keychain Access. Select My Certificates under Category. (See Screenshot 2-2.) If you have already been certified by Apple and have installed 2 certificate files, you should see them there. You need to copy the exact names of application certificate and installer certificate into AppReady's corresponding text fields. (See Screenshot 2-3.)
After dragging and dropping an application file onto the drop box on the main page and then clicking on the Next button, you will have a different window with several tab buttons. At the top of the page, there is a group box. It should be labeled the name of the application. (See Screenshot 2-4.) The edit field inside it shows the path to the application file. The entire path will be available as a help tag. If you click on the Show button, you can actually locate the application file. However, this button will be disabled in real time if the application file goes missing. And if AppReady cannot locate the application file, you will see a red symbol right below the file path edit field. If it's red, then you will not be able to work on the application. On the other hand, by showing the green symbol in real time, AppReady makes sure that the application is currently accessible and then that you can edit its information.
Under Contents, you can add files and folders to the Package. As shown in Screenshot 2-5, drag and drop files and folders directly onto the listbox. Next, choose a destination in the Package under the group box labeled Package destination. Finally, choose either Copy or Move under the group box labeled Copy/Move. If you choose Copy, then AppReady will copy source files/folders into the destination. If you choose Move, source files/folders will be relocated into the destination without duplication as long as the source and destination share the same volume.
Initially, the Copy button at the bottom should be disabled. Once you drag and drop one or more files onto the listbox, this button will become accessible. So click on it to relocate source files into the destination. Click on the Open button to open the selected destination folder to see if AppReady has relocate source files into the destination if necessary. If you want to remove a file, right-button-click on the path and choose Remove File. Likewise, right-button-click on any of them and choose Remove All Files to clear the file list.
Apple requires that your application has a 512 x 512 icon. If your application has one that is smaller than that size, then you may want to use Icon, which means you don't have to. In fact, it'll be only the matter of saving several seconds. You can replace icons manually by opening Package. If you want to use Icon, then simply drag and drop a Mac icon onto the drop box. (See Screenshot 2-6.) The name of the icon file must correspond to the application name itself. Or the Copy (or Move) button will remain disabled. And the name of the icon file must be XXX.icns where XXX is the name of the application you imported on the main window. That being stated, if you import an icon for a wrong application, the Copy (or Move) button will remain disabled as well.
This component is designed to remove specific framework files from the Frameworks folder of the Package. And the list under tab will automatically list all the frameworks files found in the Frameworks folder. (See Screenshot 2-7.) Simply, turn on the checkboxes in deciding which file delete. Finally, click on the Delete button at the bottom to delete the selected frameworks files.
Plist is a simple feature that will let you rewirte the plist file of your Mac application. It is also capable of adding keys that are not found in the original state. AppReady will only revise or add keys for the fields that are not left blank. For example, if the CF BundleIdentifier is left blank, AppReady will skip this field after you press Update. If none of the fields is filled, then the Update button will remain disabled.
Note that you must enter a long version next to CFBundleVersion. More specifically, enter 3 numbers, each of which is separated by a period. If the version you have entered is valid, then a green symbol will appear next to the edit field. (See Screenshot 2-8.) Currently, the top version number cannot be greater than 9. LS MinimumSysVer refers to the minimum OS version you want the application to run under. It's not required. If you don't want to set the minimum OS version, then leave the edit field blank. However, Apple suggests that setting a minimum OS version is a simple way of protecting your application from software piracy. Click here for more information (See under Set a Minimum System Version.) Updating Version 1.4.2, AppReady will read selected application's Plist values. So when you click on the Plist tab, you should see some of the values already filled.
Click on the Fix button, and AppReady will perform a quick remedy on the appropriate framework file using install_name_tool (command-line tool). This fix will be done only if the selected application (hereafter, RB app) was built with REAL Studio. Just briefly, the problem with RB apps involving HXRuntime is that it has a dynamic shared library that points to /usr/local/lib/HXRuntime, which may not exist.
With Version 1.4.0 and Version 1.4.2, AppReady works as follows. If the selected application does not have the dynamic shared library in question, AppReady will display a message that says "The RB dynamic shared library cannot be found." (See Screenshot 2-9a.) If the selected application is not an RB app, you are likely to see this message. So there is nothing fix. Therefore, the fix button should be grayed out. Instead, if you see a message in red that says "A link to /usr/local/lib/HXRuntime is found," you will also find that the button at the bottom is clickable. (See Screenshot 2-9b.) If you leave it unfixed, a Mac App Store may reject your application because there is a dynamic library that points to HXRuntime, which cannot be found.
After fixing the link problem, AppReady find out once again whether or not the dynamic library in question points to HXRuntime. If it doesn't, then you should see a message in green that says "A link to /us/local/lib/HXRuntime is not found.' (See Screenshot 2-9c.) So the selected RB app is good to go. Unlike previous versions (1.3.3 or earlier), once this link problem is fixed, you won't have to do it again for the same RB app.
In order to upload your software file to Apple's iTunes Connect through Application Loader, you must convert it into the package form. Before using AppReady, make sure that you have installed Application Tools, which should include productbuild, a command-line tool. The current version of Application Tools is 1.1 as of March 1, 2011. If AppReady cannot locate productbuild, you will not be able to move on. And a message in red will appear above the Start button that says "You cannot create a package because productbuild (CLT) cannot be found." And the Start button will remain grayed out until you install productbuild.
When you switch the tab to Sign/Pack, you will find three text fields that are already filled with code. (See Screenshot 2-10.) If you want, click on each copy button to copy the corresponding code into the clipboard so that you can run it with Terminal manually. Or click on the Start button at the bottom to let AppReady do the job for you. Of course, certificates must be valid, or AppReady will not be able to finish code-signing the application. If the entire process is successful, you will see a message dialog. (See Screenshot 2-11.) And you will find an application package under the same folder where you have your application file. By the way, before creating a package, you may want to enable the checkbox that says Fix permission. If this checkbox is enabled, AppReady will set the permission on the application file to 755 before packaging it. Failure to correct the permission on the application file may let Mac App Store reviewer to reject your binary by saying that he or she cannot launch the application. Furthermore, make sure that application's playlist follows iTunes Connect's rule. If it's an initial release, the playlist can have a 2-digit version (i.e., 1.1). It can certainly be a 3-digit version (i.e., 2.3.4). We have never submitted an applicaiton with a 4-digit version. So we can't say with certainty whether or not iTunes Connect accepts 4-digit versions. If it's a software update, iTunes Connect will not accept a playlist with a 2-digit version. The playlist has to have a 3-digit version (or maybe a 4-digit version).
With Version 1.4.2, when you click on the Start button, AppReady will read selected application's Plist and see if there are any missing values. For example, if the Plist file does not have a bundle identifier, AppReady will display a warning message as shown in Screenshot 2-11a.
|
