MAS Preparation, Part 1

Project modifications

In Preparing for Mac App Store Submission, the first set of changes you should make are to the project itself.

This installment describes the project modifications that need to be made to an existing Mac OS X game project.  The general assumptions are that the existing project is working and properly tested, and that, ultimately, you will want to maintain a single set of source code with conditional compilation to differentiate the store version from other builds.  Note that these are the steps that we took for Pretty Good Solitaire Mac Edition; your project may require some adjustments to these steps.  (Comments where any significant change is necessary would be very appreciated.)

So, without further ado…

0. Create a duplicate store project

Before making any other changes, create a duplicate copy of the entire project folder and name the copy appropriately.  In our case, the original folder was ‘Pretty Good Solitaire’ (which builds full and trial versions of the game) and we created a separate ‘pgsse’ (Pretty Good Solitaire [Mac/]Store Edition) folder for MAS modifications.

The version of your project that you will submit to the Mac App Store is a separate SKU (Shelf Keeping Unit), a build that uses slightly different code and configuration and which is distributed via a different channel.  While it is possible to have the store target within the main project, certain features (e.g., Power PC support, Mac OS X 10.5 support, downloadable data) are not supported in MAS, so it is easier to separate them (at first, anyway).  In any event, doing so at the start gives you a safe playground for making changes without messing up your working project.

1. Update the project version number

As just noted, the store build is a separate version and, thus, should have a different version number.  In our case, we decided that odd minor versions (e.g., “1.01”) would represent the store editions, while even minor versions (e.g., “1.00”) represented the direct downloadable editions.

2. Rename the primary build target

In the new project (of course), rename the primary build target to something appropriate.  In our case, we renamed the full version target to ‘Pretty Good Solitaire store’, which is now the store version.  You could also delete any redundant or obsolete targets remaining in the project.  For example, we deleted the trial version target, as it is built in the original project and the MAS version cannot have any vestiges of a trial version.

Note that this step is not strictly required, but it is a good idea to differentiate between targets, so it is always immediately obvious which project is active, and also to minimize any excess baggage, which reduces the possibility of mistakes.

3. Build with a current Xcode version

Make sure that you build the project with a current version of Xcode.  Submissions to the Mac App Store now require Xcode 4 and, as of this writing, the latest version is Xcode 4.2.1.

If you have an older version of Xcode, this would be a good time to upgrade, and although it will not be mentioned explicitly, you should build the project regularly, ideally after every change, to make sure that the build is not broken and behaves as expected.

4. Define a preprocessor variable

To allow for conditional compilation of certain source code, it is a good idea to define a preprocessor variableAPPSTORE, for any build targets intended for MAS.  In the ‘Build Settings’ for the target (or the whole project, if you prefer), find the setting for ‘Preprocessor Macros’ and add “APPSTORE” to each configuration.  Note that it is common to have different variables for ‘Release’ and ‘Debug’ configurations, so be careful to define APPSTORE for each one without accidentally removing or altering any existing definitions.

Of course, there is no requirement that the preprocessor variable be named “APPSTORE”, but beware that simply using “STORE” results in a naming conflict in the latest Mac OS X SDK.

5. Add necessary frameworks/libraries

In order to test the validity of app receipts, you will need to add the IOKit and Security frameworks and the crypto library.  From the ‘Build Phases’ of the primary target, open the ‘Link Binary With Libraries’ section and, by clicking on the ‘+’ symbol, add ‘IOKit.framework‘, ‘Security.framework‘ and ‘libcrypto.dylib‘.

Note that Xcode 4 adds these frameworks/libraries at the top level of your project; you will probably want to drag them into the ‘External Framework and Libraries’ folder with the other frameworks.

6. Configure debugging symbols

Despite submitting a release version to MAS, Apple requires debugging information to be included with a submission.  To accede to this requirement, you must set ‘Generate Debug Symbols’ to “Yes” and also set ‘Debug Information Format’ to “DWARF with dSYM File” (at least for the ‘Release’ configuration) in the ‘Build Settings’ of the target.

In our original project, we had all debug information disabled and/or stripped from the release builds, but one of our early issues was the lack of the dSYM file with debugging information for Apple.

7. Set correct build architecture

Finally, set ‘Architectures’ to an Intel (only) setting; for our project, that is “32-bit Intel”.

Even if your code and original project supports both PPC and Intel via a “Universal” application, the presence of a PPC build in your submission will result in rejection.  (We found that out the hard/lengthy way.)  At least now there are settings for this; in Xcode 3, you had to use “i386”, which was not even listed as a choice.

Conclusion

At this point, you should have a new project with a store target and all of the build settings configured appropriately.  In the next installment, Part 2: Property List (Info.plist) changes, we will discuss the necessary adjustments and additions to the information property list for your project.

Preparing for Mac App Store Submission

Making a Mac OS X game project suitable for MAS

If you currently have a Mac product and have not already done so, you may be considering submission to the Mac App Store (MAS).

In the upcoming series of posts, I will be detailing the process that we went through to get Pretty Good Solitaire Mac Edition, and some of our other game products, successfully submitted to MAS.  There were a number of rejections along the way, as the App Store Review Guidelines [note: requires Mac developer agreement], while extensive, are not comprehensive (nor are they 100% consistent, as we had some products accepted and others rejected with identical behaviors).

Over multiple submissions, and fewer rejections, we developed a submission checklist which I will detail roughly (some items are specific to our games) in these upcoming posts:

We have had product in the Mac App Store since launch day, more than a year ago.  If you already have a game that runs on Mac OS X, it makes sense to make the several modifications to get it into MAS, another channel to find customers.  However, in our experience, it is not a viable substitute for direct downloadable sales.  The channel is not (yet) the primary ‘go to’ location for Mac software, although the availability of Lion (Mac OS X 10.7) only on MAS should shift more customers.  Additionally, there is the same downward pressure on pricing (towards free) seen on the iOS App Store, sales are lackluster, and (of course) you are giving 30% directly to Apple.

I would certainly not recommend developing a project solely for the Mac App Store, nor eliminating a direct downloadable sales channel in favor of MAS, but with an existing project it may be worth the fairly limited extra effort it takes to be there, too.

Pretty Good Solitaire Mac Edition 2.3

Now with 350 games!

Yesterday, Goodsol Development published Pretty Good Solitaire Mac Edition 2.30, the latest version of the premier computer Solitaire program for Apple Mac OS X.

Pretty Good Solitaire Mac Edition 2.30 adds 50 new solitaire games, bringing the total to 350 games in the trial version, and 400 games in the full version (with 50 bonus games).  This game also introduces the Tour Explorer, which allows players to play game tours for a total score in pursuit of the perfect tourClick here for a list of other features in PGSME.  You can download a trial version of the product and buy it for only $24.95!  This version is a free upgrade for all previous PGSME customers, and new customers will get free upgrades through the end of 2012, which will include even more releases and new games.

As mentioned in my 2011: Year in Review article, this product is the culmination of a fairly long development and beta test cycle.  Surprisingly, the game tours feature (like the game groups before it) was the biggest single issue in getting the product released sooner.  Not only does the feature consist of four separate dialog boxes, plus two more back-end data classes, but the only specification was a somewhat flawed implementation, so I needed to rethink and redesign the entire feature, and then tweak the behavior until we had something that worked well.  Complicating matters was the fact the beta testers were not inclined to play game tours, and none are quality assurance professionals (nor aspiring to be), so in essence, only we developers (mostly me) were doing any real testing of this feature.

Of course, the sheer mass of 50 new games, when combined, contributed much more to the overall development and testing time, though none (even the real “oddballs”) took a huge amount of time alone.  Fortunately, our beta testers were more meticulous about play testing individual games, so the few significant bugs I let slip through to the beta versions were (hopefully) identified and crushed.  I challenge anybody to find a bug in PGSME now.

After a short breather, I will be back on development of PGSME 2.4 (a.k.a., GS400), which will contain (surprise!) another 50 games for a total of 400 (plus at least 50 bonus games).  Bring it on!

 

Objective-C: @property gotcha #1

Sometimes “best” practices can bite you.

In Apple iOS documentation, they strongly recommend the use of declared properties to automatically generate access methods to class variables.  In header files, you would have something like this:

@interface MyClass
{
    IBOutlet UIView* view;
}

@property (nonatomic, retain) IBOutlet UIView* view;

@end

 

Technically, this generates access methods named ‘view’ and ‘setView’, but in practice one generally accesses the class variable with the dot notation (i.e., ‘self.view’) .  The implementation of this class (minus any explicit methods) would be:

@implementation MyClass

@synthesize view;

@end

 

Accessing the variable with dot notation calls the access methods (as does calling them explicitly, obviously), but simply using ‘view’ (without the ‘self’ reference) accesses the variable directly, omitting any other functionality associated with the accessors, such as (in the above example) retaining the new view.  This is generally a poor practice except in initialization and deallocation routines, where it is preferred.

So, in order to assure that one does not accidentally skip the accessors, the recommended best practice is to use the ability of @synthesize to generate accessors that access a slightly different variable name.  In other words, instead of ‘view’ and ‘setView’ referencing the ‘view’ variable, they can be instead made to access ‘view_’:

@synthesize view = view_;

 

This is, in theory, a good idea because one can only access the variable directly with the explicit addition of an underscore (in this case), and simply referencing ‘view’ instead of ‘self.view’ should produce a compiler error.  (Note that we use a trailing underscore because leading underscores already have a specific meaning in our coding guidelines.)

Problem: If you modify the class implementation as noted above to put this into practice, you introduce a bigger problem into your code.  It turns out that @synthesize actually creates a class variable if none of the specified name exists, but it does not generate a warning or error if the one of the ostensible name does exist.  In other words, the above line would create a new ‘view_’ class variable, and create accessor methods, despite the fact that ‘view’ already exists.  The ‘view’ and ‘setView’ methods modify ‘view_’, so ‘self.view’ does the same, but failing to ‘self’ reference, rather than generating the intended error, actually modifies the orphaned ‘view’ variable.  Instead of having an extra compiler check, you instead have two very similar variables in the same class and any error becomes even harder to diagnose.

If the @property/@synthesize combination essentially replaces normal variable declarations, it obviates the whole issue of these declarations.  This seems rather silly/weird, since declaring [class] variables is a staple of C[++], and the method of doing this in Objective-C is one of the first lessons taught.  Nevertheless…

Solution: To make this idea an actual best practice, at least for simple classes, omit the entire parenthesized section of the class declaration and just declare all variables via @property/@synthesize statements.  You would end up with something like the following:

@interface MyClass
@property (nonatomic, retain) IBOutlet UIView* view;
@end
@implementation MyClass
@synthesize view = view_;

- (id)init
{
    self = [super init];
    if ( self )
    {
        view_ = nil;
    }
    return self;
}

- (void)dealloc
{
    [view_ release];
    [super dealloc];
}

@end

 

All (or most) other references to the class variable would be via dot notation, ‘self.view’, which would (of course) modify the ‘view_’ variable via accessors, as desired.

Happy coding!

Carbon nibs update

A spurious warning appears to be spurious.

In my last post, Carbon nibs under Lion, I gave a solution to the problem of Carbon nib (interface) files not being supported in Xcode 4, while Xcode 3 would not run under Mac OS X 10.7 (Lion).  That solution was to run Interface Build 3.2.6 and convert the nibs to a newer format.

Toward the end of the post I mentioned that many windows in the converted nib files produced a warning: “This window’s content rectangle does not lie entirely on the screen with the menu bar and may not be completely visible for all screen resolutions and configurations.”  In testing, these files did not exhibit any errant behavior, but shipping a product, even a beta, with build warnings is against our development guidelines.

Since that post (and in preparation for a proper build, without warnings), I did a little research and experimentation and discovered that the problem appears to be a minor issue with the conversion, where the resulting data is aberrant enough to generate a warning, but is handled correctly in the resulting application.  Although I did not dig deeply enough to identify the exact source of the problem, it is related to window positioning (as one may have guessed).

The solution, oddly, is simply to open the offending nib file, select the (or each) window, click on the Size (ruler) tab in the Inspector, and then drag the window position image, even slightly.  As far as I can discern, any movement (within the simulated window) fixes the problem; at least, it fixed it for all of my affected windows.  Clearly, the size of the windows was not the issue, since that was not changed, and the position should never have been a problem, either, for windows with the ‘Center’ attribute enabled (as most of mine were).  I also note that the windows I created from scratch since moving to this Lion/IB 3.2.6 setup were unaffected.

One other idiosyncrasy to note is that the build process also produces the following message: “View is clipping its content.”  It is not a warning, just a message, and I assumed that it was related to the above warning until the warnings were fixed.  It is a straightforward message, albeit with no reference to the specific view involved, so I looked into find the problem there as well.

As it turns out, there is a very useful tool with IB 3.2.6 to assist with this.  Select ‘Layout->Show Clipping Indicators’ to enable a feature that displays a small “+” at the bottom of any view that is clipping its content.  I never noticed this setting before, and it can be very handy.  Alas, it also reveals (in our case) that the messages are just pointless chatter, since they are being given for list views with extra columns that are intended to scroll horizontally.  Fortunately, they do not produce a warning message, so the messages are easily ignored; in fact, they only appear on the full build log, so I may have never noticed them had I not been debugging a nearby warning.

[The most meaningful comment that I received for the last post was (seriously), “I’ve a cockroach on my pillow.  Wanna see it?”  The days of technical development posts may be numbered.]

Carbon nibs under Lion (Mac OS X 10.7)

Apple’s overly aggressive deprecation sucks.

If you are still maintaining a Carbon application for Mac OS X, you may have stumbled upon a serious issue with handling of nib (interface) files in Xcode 4 under Lion, and if you have not yet, you probably will soon.  Hopefully, this post will help you resolve problems or avoid some of the pitfalls.

The Problems

Apple marches forward and aggressively deprecates development technology.  In this particular case, they release Xcode 4 and only allow submissions to the Mac App Store from the latest version, forcing developers to upgrade.  We are maintaining and enhancing a product that was developed using Carbon, based on Apple’s (then) recommendation for cross-platform products, and was about 90% complete when they announced its deprecation in favor of Cocoa.

Additionally, we upgraded to Lion (to properly provide customer support), unaware that the latest version of Xcode 3, version 3.2.6, would not install or run on Lion.  Instead, we could only download and install Xcode 4.1, which does not provide support for Carbon nib files.  With Snow Leopard, we could download both versions normally, but from Lion, the Xcode 3 download link is removed and Xcode 4 is only available via the Mac App Store.  More accurately, the installer is available via the Mac App Store; you still need to find it in Launchpad and run it before Xcode is ready.

There are two particular problems that occur with Carbon nibs in Xcode 4.1:

First, there is no editing capability for modifying them, so when you highlight a Carbon nib, the editing window only displays an Interface Builder icon, but (importantly and annoyingly) there is no message that editing is not supported.  Unless you already know that is the case, you will waste some amount of time attempting to figure out how to activate the “integrated” Interface Builder.

Second, the build tools provided cannot process the older nib files, so you will get a message similar to the following: ‘error: ibtool could not strip “Main.nib” because it is not a valid Interface Builder document.

Of course, there are a few obvious options here.  If you stop upgrading your development system, you can still build on Xcode 3.2.6 under Snow Leopard, except that you cannot submit to the Mac App Store.  You may be able to have both versions in parallel, but that is not an option on Lion at all, and the nib build issue still exists in Xcode 4 (although the solution to that is provided below).  Finally, you can give in to Apple’s strongarm tactics and rewrite your application to use Cocoa, but that is not always feasible, economically or otherwise.  (In our case, we are trying to maintain our products and support our customers while we rewrite it with Cocoa.)

Or, I suppose, you could flip Apple the bird and abandon their Mac platform; that has crossed my mind more than once, but it is not really an option for us.  Instead, I found a way to resolve the two main problems above, without too much effort.  (That is, it will be fairly easy for you readers; it took me significant time to figure this all out.)

The Solution

To resolve the inability to edit Carbon nib files within Xcode 4, take advantage of the fact that Interface Builder was an external tool with Xcode 3, and that it does run in Lion.  Simply copy Interface Builder 3.2.6 from a (Snow Leopard) partition on which it is installed to the Lion partition.  It should be located (by default) in the ‘/Developer/Applications’ folder, and note that it must be copied to the same directory on the Lion partition after Xcode 4.1 is installed.  (It will not run properly from a different folder, and the Xcode installer apparently removes it [so make a backup copy].)  Since Xcode will no longer launch (the external) Interface Builder automatically, you will probably want to make an alias for it in a convenient location.

Then, to resolve the build problems with the older nib files, you must use the separate Interface Builder tool to covert your nib files to a newer (XIB) format.  This is accomplished by opening each nib file in IB, selecting ‘File->Save As…’ from the menu, changing the ‘File Type’ to “Interface Build Carbon Document (XIB 3.x)”, and saving.  You will then need to open your project in Xcode, add all of the new .xib files to it, and delete the older .nib files.  Clicking on one of the .xib files in Xcode will show/edit it as an XML file (instead of just an icon) but, of course, you will probably only want to edit it in your newly installed IB3.

There may (read: probably will) be other issues, both with Xcode 4 itself and with the newer SDKs.  For example, we use one (and only 1) function defined in ‘QuickdrawAPI.h’, which has been removed from the OS X 10.7 SDK, so we had to back down to the 10.6 SDK (plus each SDK has different versions of the zlib library available).  Also, several of our windows from (converted) nib files produce a new warning: “This window’s content rectangle does not lie entirely on the screen with the menu bar and may not be completely visible for all screen resolutions and configurations.”  (We dynamically adjust most of our windows anyway, so it appears to make no difference, but we have yet to eliminate these warnings.)

Nevertheless, making the above changes will allow an older Carbon-based application to be built on Lion using Xcode 4.1, leaving you free to discover more fun and excitement.

[If you find this information useful, please leave a meaningful comment.]

New Goodsol Solitaire Forum

Newsbrief: A new web forum is launched.

This week, Goodsol Development launched its new/improved Goodsol Solitaire Forum, now available at http://www.goodsol.net/forum (same old address).

After a short transition period, domain name propagation time, and the requisite teething issues, this forum is (again) the primary source for discussion and support of the following titles (of ours):

My profile name is Seelhoff; I hope to see you there.

Pretty Good Solitaire Mac Edition 2.21

First, the Good News…

PGSME 2.21Pretty Good Solitaire Mac Edition 2.21 is now available in the Mac App Store.

Pretty Good Solitaire Mac Edition 2.21 is essentially the same as Pretty Good Solitaire Mac Edition 2.20, including all 350 games (including bonus games), with the alterations required for MAS inclusion.  Mostly, this is just the elimination of any registration codes or acknowledgment that Apple is not the one and only possible source of this product.

Click here for PGSME 2.21 on the Mac App Store.  (We would really appreciate decent reviews, too.)

 

… and then the Bad News.

Apple, in its myopic wisdom, has determined that updated products should not be shown at the top of the various product lists, so PGSME 2.21, despite having 50% more primary games than its MAS predecessor, PGSME 2.14, which itself helped make the initial Mac App Store launch successful, is not listed on the first (visible) page of ‘All Card Games’ (nor under ‘New and Noteworthy’ on the general ‘Games’ page).

I can understand and appreciate the concept of not automatically bumping up minor updates and bug fixes, thus encouraging spam-like behavior and regular submission of inconsequential changes, but when one of the launch day products adds 100 new games (plus another 10 bonus games), after being trouble free for 5 months, it seems genuinely unfair to penalize it with keeping its (now) almost bottom of the list position.  In fact, it is actually counterproductive, as it encourages us to bombard them with releases of “different” titles using our internal product names (GS200, GS300, GS350, GS400, etc.).  Apple needs to review this policy.

Fortunately, despite the lack of attention from Apple itself, our customers recognize the quality of our product and, somehow, have managed to find out about the new release.  Pretty Good Solitaire Mac Edition is (as I write this) back to #3 on the ‘Top Grossing’ chart in ‘Card Games’, so we have been voted onto the page anyway.

Nice.

Pretty Good Solitaire Mac Edition 2.2

What is your profession? Fun! Fun! Fun!

After half a year in development, the latest version of Pretty Good Solitaire Mac Edition has been released by Goodsol Development this week.

300 solitaire games for Mac OS X

Pretty Good Solitaire Mac Edition 2.20 adds one hundred new solitaire games to the product, and also makes some significant interface improvements, including customizable game groups, to allow players to arrange games just the way they desire.  The 300 games in this title are joined by 50 bonus games (in the full version), to make PGSME the ultimate solitaire game for Mac OS X.

You can download a trial version of the product, or buy it for only $24.95!  (That is not even a dime per game for hours upon hours of relaxing enjoyment; where else could you get that much fun for less than 10 cents?)  This version is a free upgrade for all previous PGSME customers, and new customers will get free upgrades through the end of 2012, including PGSME 2.3 later this year.

In other news…

By popular request, our RSS feed has now been updated to display each article in its entirety.  (Thanks, Rich, and you are very welcome.)

Goodsol Solitaire 101 (and more)

GS101 versions 2.04 and 2.05 are released.

101 favorite solitaire gamesGoodsol Solitaire 101 version 2.04 is now available for download on both Mac OS X and Windows, while version 2.05 is also available in the Mac App Store.  (The only differences between these two versions are minor restrictions imposed on the latter by Apple.)

Goodsol Solitaire 101 contains 101 of the most played solitaire games from Goodsol Development, including all of the favorites included in Most Popular Solitaire, plus 34 bonus games.  All of this can be purchased for only $19.95 (although quick readers may be able to catch a special introductory price on the Mac App Store).

Goodsol products on the Mac App Store

a dozen great FreeCell gamesThrough a fluke of timing and the whims of one Apple reviewer, FreeCell Plus 4.05 arrived on the Mac App Store last week, while the store version of Goodsol Solitaire 101 (submitted first) appeared just a few days ago.  However, the debuts of these two products are very encouraging.  All four of our playing card solitaire products have spent time in the Top 10, seemingly taking turns to share the spotlight.

As of this writing, all four of these solitaire titles are among the top 24 card games in the Mac App Store (3 in the top dozen):

Fortunately, FreeCell Plus has been camped in the ‘Top Paid’ chart since its release, usually among the top 3 card games.  Unfortunately, it is our least expensive (current) offering, which shows the downside of eliminating trial versions in favor of straight sales (and indicates that shareware still works).